PIO Agent

Inspect an ESP core dump from a file or explicitly authorized device partition read, optionally analyzing it against an explicit ELF. Device reads can reset hardware and require separate device and host-command grants.

Decode crash addresses against the selected current or retained ELF. Requires build permission for metadata; does not prove flashed-device identity.

Audit declared and installed project dependencies, with optional separately authorized build and LDF graph evidence.

Reads one approval request and expiry without exposing approve or deny mutations to the agent.

Gets detailed information about a specific board including MCU, frequency, flash, RAM, and supported frameworks.

Retrieves a short-lived authenticated launch URL for the browser dashboard. Automatically starts the local web server on demand if offline.

Reveals who currently owns the hardware queue lock.

Reports active, inactive, or stale serial monitor state with a bounded incremental cursor.

Returns the active policy profile and allowed/approval-required/denied operations.

Dumps platformio.ini JSON.

Returns a compact pre-flight snapshot of a PlatformIO project: declared environments, source files under src/, `lib_deps`, build-cache state, firmware artifact path, connected serial devices, and a `nextSteps` checklist. Call this FIRST when starting work on a project instead of issuing several read_file/list_devices/cat-log calls — it collapses that ritual into a single deterministic response. Pure I/O, no toolchain invocation; safe to call repeatedly.

Initializes a new PlatformIO project with the specified board and optional framework. Creates project structure with src/, include/, lib/, and test/ directories.

Installs a library from the PlatformIO registry either globally or to a specific project. Supports version specification.

Lists all available PlatformIO boards with optional filtering by platform, framework, or MCU. Supports 1000+ boards across 30+ platforms.

Lists all connected serial devices that can be used for firmware upload and monitoring.

Lists all installed libraries either globally or for a specific project.

Lists pending project-scoped approval requests without exposing any approval mutation.

List structured target metadata for selected or all environments. Requires build permission; does not execute the listed targets.

Returns compact project-scoped task history after reconciling stale tracked processes.

Opens the PIO Agent project, device, and task panel in a Codex host that supports MCP Apps. The headless result identifies the selected project without starting the browser dashboard.

Inspect ESP partition artifacts and firmware fit. Optional buildMetadata requires build permission and can execute project scripts. Optional readDevice resets/reads an explicitly selected serial device with separate permissions.

Run a fresh PlatformIO build with optional parallel jobs and compact diagnostics. Canonical build permissions apply.

Run static analysis with structured defects, source locations and CWE. Canonical check permissions apply.

Clean selected build artifacts, optionally including dependencies. Canonical destructive cleanup permission applies.

Capture and save the selected ESP core-dump partition, optionally analyzing it against the matching project ELF. Configuration, metadata, device, export and analysis permissions remain separate.

Decode supplied crash text or an owned monitor session against a verified ELF snapshot. Build metadata collection and serial reads retain separate canonical permissions.

Compatibility dependency audit using canonical permissions and optional authorized build evidence.

List serial device hints and caller-owned monitor sessions under canonical permissions.

Collect bounded heap/stack telemetry from an owned session or an authorized temporary monitor. Reports sample-window trends, explicit unknown units and incomplete collection; does not prove a memory leak.

Open, read and close an owned serial monitor. Both opening and reading must be authorized before startup; unconfirmed closure retains device ownership.

Read an owned monitor with cursors and bounded Python-compatible regex matching on completed lines. Maximum wait 120 seconds; response and storage byte limits apply.

Start an owned serial monitor using explicit arguments, resolved project settings, or an unambiguous device candidate. Opening requires hardware authorization and exclusive device ownership.

Write UTF-8 text to an owned serial session after payload-bound hardware authorization. Limited to 64 KiB including the optional newline.

Inspect the effective ESP partition layout and optionally compare a serial device. Build metadata and hardware access retain separate canonical permissions.

Inspect serial-port presence, permissions and observed holders without opening or closing the device. Missing holder evidence does not prove availability.

Initialize a PlatformIO project with ordered options. Canonical initialization and configuration-read permissions apply before filesystem changes.

Run a named target through the canonical effect permissions and caller-owned serial lifecycle.

Report ELF sections, largest symbols/files and partition-aware PlatformIO accounting under canonical build permissions. Static RAM excludes runtime heap and stack.

Inspect PlatformIO Core, effective server policy and caller-owned monitors through canonical permissions.

Run PlatformIO tests with per-case results. Embedded tests can upload and open hardware; canonical high-risk test permission applies. Build-only policy disables upload and test execution.

Build and upload firmware through shared upload permissions and caller-owned serial cleanup.

Install a library, platform or tool in a project and save dependencies through PlatformIO.

List project packages and environments. Requires build permission because PlatformIO loads platform code.

Report outdated project packages. Requires build permission because PlatformIO loads platform code.

Search PlatformIO library, platform or tool registry packages by type and page.

Remove a library, platform or tool from a project and its declared dependencies.

Update project dependencies within declared version constraints, with retained output and configuration change hashes.

List resolved project environments, inherited board/framework/port settings and configured defaults without running build scripts.

Generate bounded build metadata for selected or all environments. Requires build permission; may execute project scripts or install dependencies.

Scans the latest active background serial trace spool, returning a filtered string block.

Release the explicit queue lock matching your session ID.

Forcefully cleans all server locks and terminates any tracked daemon or compilation PIDs globally or locally.

Run a named PlatformIO target with effect-based permissions. Serial upload targets coordinate owned monitors and endpoint custody; network/probe destinations require their dedicated workflow.

Validates unit tests locally/remote.

Searches the PlatformIO library registry for available libraries by name, keywords, or description.

Report GNU symbols and PlatformIO memory accounting for one environment. Metadata and size checks require build permission and may execute project scripts.

Manually start or restart the background serial-to-disk spooler for a specific device.

Kills the active background serial listener and unlocks the UART.

Gets sys diagnostic path output.

Removes target library.

Upgrades library versions.

Builds and uploads a SPIFFS/LittleFS filesystem image to the connected device. PREFERRED over `pio run --target uploadfs` in a shell — same hardware-lock and port-auto-detect benefits as `upload_firmware`. Supports `start_monitor=true` to re-attach serial after upload.

Uploads compiled firmware to a connected device. PREFERRED over `pio run --target upload` in a shell — this tool routes through the hardware lock to serialize port access, auto-detects the port, and (with `start_monitor=true`) re-attaches the serial monitor after the device re-enumerates. Automatically rebuilds via `build_project` semantics if the cache is cold.