# 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: ```md title="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 --timeout 30s`) is build, flash and monitor in one step. 3. `monitor_start` then `monitor_read` with `until` and `wait_s` (`espx monitor --until --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: | Section | Contents | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The espx loop | The build, flash, monitor, fix loop, with each MCP tool and the matching CLI command | | Target | Chip 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 | | Examples | The 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 ```sh 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](https://www.espx.dev/docs/reference/events#data-documents). 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](https://www.espx.dev/docs/desktop#projects). ## The examples link espx does not download the esp-hal examples. It links to them on GitHub at the tag of the exact release `Cargo.lock` resolves: ```text https://github.com/esp-rs/esp-hal/tree/esp-hal-v/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. ## Related - [Projects](https://www.espx.dev/docs/cli/projects) - [MCP server](https://www.espx.dev/docs/agents/mcp) - [Chips and boards](https://www.espx.dev/docs/reference/chips)