Debug Mode
Debug mode
The debugagent is the one built-in agent that writes code, compiles with your MCU's toolchain, flashes the board, and reads the serial line — closing the loop on real hardware instead of guessing.
When to use it
Reach for the debug agent when you describe a hardware symptom — a reset loop, panic, watchdog, brownout, hard fault, a sensor that won't read — or ask Flash to "debug/fix this on the board". It's not for read-only architecture analysis (that's the architecture agent) or a code change that doesn't need hardware (that's general).
my SPI peripheral isn't responding — help me debugthe device panics on boot — use the board to find where it hangsThe loop
The agent's system prompt encodes a disciplined cycle:
Repro
Locate & hypothesise
find_symbol / component_api (both give file:line), then state one likely cause before touching anything.Fix
Build
build_firmware; if it fails, read the errors and fix before continuing — it never flashes a broken build.Flash & verify
flash_firmware (gated by a confirmation), then read_serial against the success marker. If the symptom persists, loop back with what it learned.Give it a success criterion
The more concrete the criterion, the better the loop closes. Tell it a serial pattern that must appear (e.g. DEBUG_AGENT_RECV 4) or must stop (e.g. Guru Meditation), or a window of time without resets. That's what read_serial checks for the baseline and the final verification, and it cites the result in its answer.
What you see in the TUI
Every step is reflected live — not dumped at the end:
| Step | What you see |
|---|---|
file_edit | The diff is typed in as red/green wash blocks with an intent header. |
| Edit permission | A permission card with an approve / deny selector. |
build_firmware / flash_firmware | The view jumps to the BUILD panel; the log streams there. |
| Flash confirmation | A card: flash now / allow for session / skip. |
read_serial | The view jumps to DEBUG; board output appears live and the capture expands in chat. |
This works because the agent drives the same build and serial sessions the panels use — one owner of the serial port, so you watch in DEBUG exactly as the agent captures. Headless (flash query --agent debug) it falls back to ephemeral sessions and works the same.
Safety
- Anti-loop guard — if a build fails twice on the same error, it stops, re-reads the whole file, and reports rather than editing blind.
- Dry-run honesty— if results are simulated, it won't claim on-hardware verification; it says the fix is built and reasoned but verification is pending a board.
- Shell deny-list —
bashruns under an unconditional deny-list (nosudo, recursive deletes, writes to block devices,curl | sh,git reset --hard, …).
Multi-target
The agent is MCU-agnostic. Per-target knowledge lives in command resolution — platformio.ini → PlatformIO, sdkconfig → ESP-IDF, west.yml → Zephyr, Arduino CLI — plus Stage 0 and the <COMMANDS> block in FLASH.md. Adding a new target doesn't touch the debug agent.