Agent Modes

The fwm agent has three operating modes that change which tools it can call and how it interacts with your project. Pick the right tool surface for the task; switch between modes at any time with the matching slash command and the conversation carries forward.

Edit mode

The default. The agent has full read + write access — adding source files, modifying prj.conf, updating Device Tree overlays, calling build, flash, git_commit, etc. Destructive tools always prompt for approval; see Tool-use approval.

fwm > Add a UART shell over USB CDC ACM
[Edit] Plan:
  • Update prj.conf to enable CONFIG_USB_DEVICE_STACK
  • Update prj.conf to enable CONFIG_USB_DEVICE_PRODUCT
  • Update boards/nrf52840dk_nrf52840.overlay
  • Update src/main.c to initialize USB
Apply? [y/n/edit]

Use Edit mode when you want fast, hands-on iteration on a working project.

Plan mode

Plan mode is read-only. The agent inspects the project, reasons about the change, and produces a plan — no writes happen until you accept. Launch directly into Plan mode with --plan:

fwm agent --plan

Or switch inside the REPL:

fwm > /plan
[Plan] Now in plan mode. I will not modify files.
fwm > How would I add Bluetooth Mesh support to this project?

Use Plan mode for big architectural changes you want to review with your team before implementing.

Debug mode

Debug mode focuses on datasheet-aware code review and diagnosis: build failures, runtime crashes, peripheral misbehavior, interrupt-priority issues, memory layout, register configuration, errata cross-referencing, and timing analysis.

fwm > /debug
fwm > west build -b nrf52840dk/nrf52840 fails on uart3 init
[Debug] gpio_pin_configure() called before device_is_ready()
        for uart3. Errata 240 also applies to TWIM3 on this die.
        Suggested fix: add device_is_ready() guard.

Use Debug mode when something is broken and you need a focused troubleshooting session.

Plan / Debug → Edit handoff

When a /plan or /debug session finishes with a report, the REPL asks whether to switch into /edit mode and hand the plan/report to the edit agent as a single follow-up — accept, decline, or add a custom follow-up message.

Switching modes

/edit     # full read + write
/plan     # read-only, produces a plan
/debug    # read-only, datasheet-aware analysis

The current mode is shown in the REPL status bar.