Agent/CLI ergonomics: non-interrupting reads, a run→capture cycle, and Claude Code integration

[bdbarnett]

Context

I drove a Waveshare ESP32-P4 (720×720 DSI, C6 Wi-Fi) entirely through scripts/mpftp from a Claude Code session: detect → build firmware with user C modules → flash → provision Wi-Fi → mip install → run examples → instrument LVGL → diagnose two real bugs → rebuild → reflash → verify. It worked, and the firmware half in particular was excellent. Everything below is friction I hit doing that, ordered by how much time it cost.

1. A read that doesn't interrupt the running program (biggest one)

exec / get / put all enter the raw REPL, which Ctrl-Cs whatever is running and clears module state. Observing a running script is what kills it. Probe after probe appeared to "stall at stage 00" — every one of those stalls was my own get interrupting the script mid-import. I lost more time to this than to the actual bugs.

The workaround I converged on:

1. script appends progress to /result.txt, one line per stage
2. mpftp run -d COM4 script.py (--no-follow, returns at once)
3. wait without touching the port
4. get /result.txt

Requests:

• mpftp watch-file /result.txt or a --no-interrupt read path that streams a board file without entering raw REPL.
• Make the second port a first-class read channel. This board exposes role=repl (UART) + role=cdc_debug (native CDC); debug-tee is the right idea but see §5.
• Failing both, document the write-to-file pattern in docs/agent-guide.md — it's the single most useful technique I found and I had to derive it.

2. One command for the run → wait → collect cycle

I typed this shape maybe thirty times:

mpftp hard-reset -d COM4; sleep 10
mpftp run -d COM4 probe.py; sleep 20
mpftp get -d COM4 /result.txt ./result.txt; cat ./result.txt

Proposal:

mpftp probe -d COM4 probe.py --reboot-first --capture /result.txt --wait 20

…emitting the captured file as JSON. This is the agent loop for anything that outlives a raw-REPL session.

3. --reboot-first, because stale state looks like breakage

Re-importing board_config re-initialises the display and leaves prior timers armed. Two or three iterations in, the board saturates and every symptom looks like a code bug. Brad had to tell me "you likely need to reboot between iterations" — after which a probe that had been failing passed immediately. A --reboot-first flag on run/exec (and a note in the guide) would save agents that whole detour.

Related: hard-reset runs main.py. When main.py is a previous app, every reset boots into it. A --skip-main / --safe-boot option, or a documented "rename main.py aside while iterating", would help.

4. WSLENV for micropython.exe (silent wrong-code bug)

Launching the Windows binary from WSL, it never receives MICROPYPATH unless WSLENV=MICROPYPATH/l is exported, and silently falls back to %USERPROFILE%\.micropython\lib. I spent a while convinced I'd broken appdev — the board was running a months-old installed copy. mpftp knows it's launching a Windows binary; it should set WSLENV itself, or warn when MICROPYPATH is set but unreachable by the target interpreter.

5. debug-tee didn't work from WSL

mpftp debug-tee COM42 --log-path /tmp/tee.log reported "log_path": "\\tmp\\tee.log" and no file appeared at /tmp/tee.log, /mnt/c/tmp/tee.log, or ~/.mpftp/. WSL path translation on the sidecar side. This is the feature that would have solved §1, so it's worth fixing first.

6. firmware build --clean doesn't clear a foreign CMake cache

The build dir held a cache pointing at /home/brad/gh/other/esp-idf (an SDK that had since moved). --clean ran idf.py fullclean, which refused ("doesn't seem to be a CMake build directory") and left the bootloader subproject cache intact; the next build failed on does not match the source ... used to generate cache. rm -rf build-<BOARD>-<VARIANT> fixed it. Suggest --clean fall back to removing the build dir when fullclean refuses, or a --distclean.

7. Machine-readable errors

Several failures came back as bare text where success is JSON — Expecting value: line 1 column 1 (char 0) from a wedged port, [Errno 2] /result.txt from a missing file. Agents parse JSON; a consistent {"ok": false, "error": ..., "hint": ...} envelope plus meaningful exit codes would let a tool retry intelligently instead of guessing.

Credit where due: "timeout waiting for first EOF reception" already does this well — it explains that the board is fine and busy, names --no-follow, and says the COM handle was released. More errors like that one.

8. Smaller things

• put --verify returning a sha256 is genuinely reassuring — keep it, and consider --verify by default.
• firmware detect reporting secure-boot / flash-encryption before an erase is exactly the right safety gate.
• Board debris accumulates fast when probing (/probe_*.py, /result.txt). A mpftp clean --dry-run would be nice.
• mip install defaulted to micropython.org/pi/v2 and reported Package not found for a package that exists on a different index; passing index= fixed it. Worth surfacing in the CLI as mpftp mip --index.

9. Claude Code integration

Brad raised this and I think it's right. The CLI is already agent-shaped — JSON out, one concern per subcommand, no interactive prompts. Two paths:

• MCP server: expose ports / connect / run / probe / firmware * as tools. An agent gets typed schemas instead of parsing --help, and the non-interrupting read from §1 becomes a natural tool boundary.
• Claude Code plugin: skills wrapping the workflows (flash this board, run this example, bisect this firmware) plus the agent guide as skill context. The write-to-file probe pattern is exactly the kind of hard-won technique a skill should encode so nobody re-derives it.

The docs are already unusually good for this — docs/agent-guide.md is written to agents, and the role=repl vs role=cdc_debug table answered my port question without asking. That foundation is why the session worked at all.

🤖 Generated with Claude Code

[bdbarnett]

Part 2 — CircuitPython and flash-constrained boards (RP2040)

Follow-up from a second session: a Waveshare RP2040-Touch-LCD-1.28 (waveshare_rp2040_touch_lcd_1_28, CircuitPython 10.2.1, 1 USB port, COM59). Where the P4 exercised the MicroPython + firmware path, this one exercised the CircuitPython path — and the two are much less symmetric than docs/agent-guide.md implies.

10. CircuitPython already solves §1 — and nobody told me

put/get/ls/hash on a CircuitPython board route through the mounted CIRCUITPY volume, not the serial port:

$ mpftp put -d COM59 ./probe.py /probe.py
{"path": "/probe.py", "size": 18, "via": "circuitpy_msc"}

sidecar.py:1855 (_circuitpy_msc_root) and the six call sites at sidecar.py:1295–1394 do this already. This is the non-interrupting read channel I asked for in §1, shipped, on the one interpreter where it's possible — and I didn't find it until I read the source. It isn't in --help, isn't in the agent guide, and the "via" field is the only signal it happened.

Two asks:

• Document it prominently. "On CircuitPython, file operations do not interrupt the running program" is a headline fact for agents. It inverts the entire §1 workflow.

• Go the last mile: an MSC-only mode that never opens the port. Right now every standalone invocation still calls ensure_device first, which connects and Ctrl-Cs the running program — purely to learn that the interpreter is CircuitPython, after which the serial handle goes unused. That detection is available without serial:

  D:\boot_out.txt
  Adafruit CircuitPython 10.2.1-dirty on 2026-08-21; Waveshare RP2040-TOUCH-LCD-1.28 with rp2040
  Board ID:waveshare_rp2040_touch_lcd_1_28
  UID:E462A052C73E4A29
  

  That UID equals the port's serial_number (mpftp ports reports SER=E462A052C73E4A29 for COM59), so a volume can be matched to a device with no serial contact whatsoever. A --msc flag, or just auto-detection when a labelled volume matches the requested device, would make CircuitPython file ops genuinely zero-impact. For an agent iterating on a running app that is the difference between observing and destroying.

11. CircuitPython is a second-class citizen outside file ops

--help advertises interpreter parity for serial, and mostly delivers. But:

• mpftp bootloader is a silent no-op on CircuitPython. sidecar.py:1670 sends import time, machine; machine.bootloader() — machine does not exist on CircuitPython. It's dispatched via exec_raw_no_follow (return value never read), the exception is swallowed by a bare except: pass, the transport is force-closed, and it returns {"ok": true}. The board does not enter the bootloader and the CLI reports success. I lost time trusting it. The CircuitPython equivalent is:

  import microcontroller
  microcontroller.on_next_reset(microcontroller.RunMode.BOOTLOADER)
  microcontroller.reset()

  which works reliably over serial and is how I ended up flashing. This is a one-branch fix and the highest-value CircuitPython bug here — it's the gateway to every reflash.

• firmware * has zero CircuitPython awareness. grep -i circuitpython python/firmware_engine.py returns nothing. That's a defensible scope decision, but --help says "Build & flash MicroPython firmware" while the surrounding docs describe a general board tool, so an agent tries it. Either reject CircuitPython explicitly with a pointer, or grow a CP path — the build is genuinely different (see §12) but the flash half is much easier than ESP32: no esptool, no partition table, no baud negotiation. Enter the bootloader, copy one .uf2 to the RPI-RP2 volume, done. Given mpftp already knows how to find a removable volume by label, firmware flash for UF2 boards is close to free.

• hard-reset runs code.py on CircuitPython just as it runs main.py on MicroPython, with the same iteration hazard from §3.

12. Building CircuitPython is not building MicroPython

If a CP firmware path is ever added, these bit me and will bite it:

• -Werror=float-equal. CircuitPython enables it; MicroPython does not. Any user C module that compares a float against an exact literal — even a deliberate if (angle != 0.0f) fast path — fails to build on CircuitPython and builds clean on MicroPython. Vendored LVGL trips it too (lvgl/src/widgets/ arc and chart), which is why I could not include LVGL in this build at all. C modules need per-source -Wno-float-equal scoping, not a global relaxation.
• Enable-flag location differs by port. unix uses ports/unix/variants/<variant>/mpconfigvariant.mk; MCU ports use ports/<port>/boards/<board>/mpconfigboard.mk. Tooling that assumes one shape silently skips the other — my own build script had a hard "unix only" gate that made a working port look unsupported.
• Double-include is a real hazard. A module .mk gets included from both the enable makefile and the port Makefile; without an include guard every source lands in SRC_C twice and the link fails with multiple definition of … naming the same object file on both sides. That error message reads like a build-system bug and isn't one.

13. Flash is the binding constraint, and the error arrives last

The RP2040 has a 1020 KB firmware region. Final build: 979,772 B — 93.80%. Adding one C module (pygraphics) cost ~59 KB, 5.7 percentage points in a single step (88.06% → 93.80%).

The failure mode is brutal for an agent: freezing two pure-Python packages into the image overflowed the region by 4112 bytes, and that is reported by the linker, after a full compile, as a region-overflow line with no attribution to what caused it. Nothing earlier warns. Requests:

• Always surface the memory-region table on both success and failure — it's the single most useful number on a constrained board and it's already printed by the toolchain.
• Report the delta against the previous build of the same board. "93.80% (+5.74)" turns an invisible cliff into a gauge.
• A --no-freeze / frozen-module opt-out escape hatch, since frozen modules are the first thing to cut and the last thing that's easy to cut.

Corollary worth documenting: on RP2040 the CIRCUITPY filesystem survives a UF2 reflash — firmware lands at 0x10000000 in a separate region, and my code.py and lib/ were untouched afterward. Same reassurance as flashing ESP32 at 0x2000, and equally non-obvious.

14. WSL, again

/mnt/d does not exist for a removable CIRCUITPY volume — WSL does not auto-mount removable drives, so anything reaching for the POSIX mount finds nothing. _find_circuitpy_host_roots (sidecar.py:1793) handles this correctly by falling back to D:\ for the Windows-side Python, which is the right call and worth keeping in mind for any new code path.

Less kind: copying a .uf2 from WSL to a Windows volume via /mnt/<letter> fails, and PowerShell's Copy-Item reports the failure non-terminatingly — the command returns 0 and writes nothing. Copying from the \\wsl.localhost\Ubuntu\... UNC path works. Anything in mpftp that writes a firmware image to a host volume from WSL needs -ErrorAction Stop or an explicit post-copy size check, or it will cheerfully report a flash that never happened.

15. Revised priority

Reordering everything in this issue by value-per-line-of-code:

1. bootloader on CircuitPython (§11) — silent success on a no-op, one branch to fix, blocks all reflashing.
2. Document via: circuitpy_msc (§10) — zero code, inverts the agent workflow on CP.
3. --msc / serial-free CircuitPython file ops (§10) — delivers §1 properly on the interpreter that can support it.
4. mpftp probe run→wait→capture (§2) — the MicroPython answer to §1.
5. Memory-region reporting with deltas (§13).
6. --reboot-first (§3) and WSLENV (§4).
7. UF2 firmware flash (§11) — small, and the volume-discovery half already exists.

The MSC discovery reframes §9 too: an MCP server exposing read_board_file that is guaranteed not to disturb a running program on CircuitPython is a much stronger tool contract than one that might.

🤖 Generated with Claude Code

[bdbarnett]

16. Consider UF2 output for MicroPython builds too

Raised by Brad while flashing the RP2040, and it generalises past CircuitPython.

Flashing the ESP32-P4 meant esptool, a serial port, a baud rate, a partition
layout, and an offset (0x2000, chosen to preserve the VFS). Flashing the RP2040
meant copying one file onto a USB volume. The second is dramatically better for
an agent: no port to wedge, no offset to get wrong, no partial-write state, and
the failure mode is a file copy that either happened or didn't.

MicroPython builds UF2 for the RP2 port already, and uf2conv.py will wrap a
binary for any family with a UF2 bootloader — which includes most SAMD, nRF, and
RP2 boards, and ESP32-S2/S3 in their ROM DFU-adjacent modes. Where a board can be
flashed either way, mpftp emitting (and preferring) UF2 would collapse the whole
firmware flash path down to:

1. put the board in bootloader mode
2. wait for the volume to appear
3. copy
4. wait for it to re-enumerate as a REPL

mpftp already has every piece of that. _find_circuitpy_host_roots
(sidecar.py:1793) is volume discovery by label — generalise it to RPI-RP2,
FTHRSAMD, NRF52BOOT, etc. and it's most of the implementation. The one thing
it needs that isn't there yet is a correct bootloader entry (§11).

Two caveats worth designing around rather than ignoring:

• UF2 does not preserve the filesystem the way an offset flash does. It does
  on RP2040 — the firmware region and the CIRCUITPY partition are separate, and
  my board files survived — but that is a per-family property, not a guarantee.
  Worth reporting, not assuming.
• Copy verification is mandatory on Windows/WSL (§14): Copy-Item failing
  non-terminatingly means "flashed successfully" and "wrote nothing" look
  identical from the exit code. A post-copy size or re-enumeration check turns
  that into a real result.