v0.1.1

Agent context

What a coding agent reads before it writes firmware: the AGENTS.md from espx new, and espx context.

An agent writing esp-hal code needs facts it cannot guess: which chip, which pins drive the LED, and which esp-hal release the project uses, since the API changes between releases. espx collects them in one text. espx new writes it to the project's AGENTS.md, and espx context prints it on demand with what is attached right now.

AGENTS.md

Every project espx new creates has an AGENTS.md, the file coding agents read before they write code. For a project made with espx new blinky --board xiao-esp32c6, before the first build, it reads like this:

AGENTS.md
# blinky

Bare-metal Rust firmware (esp-hal, `no_std`) for the ESP32-C6, built and flashed with espx.

## The espx loop

Work in this loop and let espx run the tools. Each step is an `espx mcp` tool, with the same step on the command line in brackets.

1. `build` (`espx build`): compiles with `--release`; compiler errors come back with file, line and the rendered message.
2. `flash` (`espx flash`): writes the release binary and resets the board. `run` (`espx run --until <re> --timeout 30s`) is build, flash and monitor in one step.
3. `monitor_start` then `monitor_read` with `until` and `wait_s` (`espx monitor --until <re> --timeout 30s`): read what the firmware logs. `since: "boot"` shows the current boot only.
4. A panic or exception comes back with its backtrace symbolized and the source lines around each frame in this project.
5. Fix the code and go round again. `context` shows these facts plus what is attached now.

Long steps return `{job, state: "running"}` after `wait_s` seconds; continue with `job_wait`. Never ask a person to press a button unless a tool returns `needs_human`.

## Target

- Chip: ESP32-C6 (`esp32c6`), target `riscv32imac-unknown-none-elf`, toolchain `stable`
- Board: `xiao-esp32c6` (Seeed Studio XIAO ESP32C6)
- Pins: LED on GPIO15 (active-low), button on GPIO9, UART TX GPIO16 / RX GPIO17
- Board documentation: https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/
- Bound board: none. Agents may only flash, reset or erase a board that espx.toml binds with `[board] id`.
- esp-hal ~1.1.0 (requirement from Cargo.toml; build once to pin it in Cargo.lock)
- esp-hal features: esp32c6, log-04
- Other esp-rs crates: esp-println 0.17.0

## Examples

Take esp-hal usage from the examples of the exact esp-hal release this project resolves, never from memory or from another version: the API changes between releases. Their link appears here once Cargo.lock pins esp-hal from crates.io, so build first.

The versions depend on the esp-generate template of the day. The sections are always the same:

SectionContents
The espx loopThe build, flash, monitor, fix loop, with each MCP tool and the matching CLI command
TargetChip id and name, Rust target and toolchain channel; the board model and its pins when one is recorded; the bound board from espx.toml; the esp-hal version and features; the other esp-rs crates; defmt logging when the project uses it; the release binary once built
ExamplesThe link to the esp-hal examples at the exact release, or a note to build first

Without a recorded board, the Target section says so and tells the agent to check pins against the board's documentation before driving a GPIO.

AGENTS.md is written once, when the project is created. Run espx context for the current facts.

espx context

espx context
espx context --board xiao-esp32c6
espx context --json

context prints the same markdown for the project in the current directory (or --dir), with an Attached section at the end listing the serial ports with a dev board on them. After a build it carries the exact esp-hal version from Cargo.lock and the examples link. --board names the board model when the project records none. --json prints the gathered facts as one document; see JSON events.

espx finds the board model from --board, else from the Board: line in AGENTS.md or README.md, which espx new --board writes.

The same text is available to agents three more ways:

  • The context MCP tool, which also lists the open monitor sessions.
  • The espx://project/context MCP resource, for the project espx mcp was started in.
  • Copy agent context on a project's Details tab in the desktop app.

espx does not download the esp-hal examples. It links to them on GitHub at the tag of the exact release Cargo.lock resolves:

https://github.com/esp-rs/esp-hal/tree/esp-hal-v<version>/examples

The link appears only when Cargo.lock pins exactly one esp-hal version from crates.io. Before the first build there is no lockfile, so the text says to build first. A git or path dependency on esp-hal, or two esp-hal versions in one lockfile, has no release tag to link to, so there is no link either.

Agents should take API usage from those examples, keeping to the ones that support the chip, and take pins from the context or the board_catalog tool, never from memory. The MCP server's port-example prompt asks an agent to do exactly that for one example.