Let Claude Code debug firmware on your real board

Connect Claude Code

You need Claude Code, Termethos 2.0.0 on Windows and Linux, and a board on a serial port, or simulation mode to try it without one.

1. In Termethos, click AI agents (MCP), check Allow AI agents to connect and click Save.
2. Click Copy next to the setup command in the dialog. It has your port and token in it.
3. Run it in a terminal, in your firmware project's folder:

claude mcp add --transport http termethos http://127.0.0.1:7471/mcp --header "Authorization: Bearer <token>"

This adds Termethos for you, in this project. To use it in every project, add --scope user after add.

Sharing the setup with your team

A project's .mcp.json is usually committed, so keep the token out of it and read it from an environment variable instead. Each person sets TERMETHOS_TOKEN to the token from their own Termethos.

{
  "mcpServers": {
    "termethos": {
      "type": "http",
      "url": "http://127.0.0.1:7471/mcp",
      "headers": { "Authorization": "Bearer ${TERMETHOS_TOKEN}" }
    }
  }
}

Check the connection

List your MCP servers. Termethos must be running with the server on.

claude mcp list

In a Claude Code session, /mcp shows the server and its tools. Then ask something simple: "Use termethos to get the connection status." The MCP item in the Termethos status bar turns green while Claude Code uses it.

Tool permissions

Claude Code asks before it uses a tool. To skip the question for the tools that only read, allow them in your project's .claude/settings.json, and keep asking for the ones that send commands or change connections.

{
  "permissions": {
    "allow": [
      "mcp__termethos__get_status",
      "mcp__termethos__list_connections",
      "mcp__termethos__read_trace",
      "mcp__termethos__wait_for_trace",
      "mcp__termethos__read_dashboard",
      "mcp__termethos__list_quick_commands"
    ]
  }
}

Termethos has its own switches too: choose whether agents may send commands, run scripts, connect and disconnect, and create and edit connections. Termethos permissions

Describe your board in CLAUDE.md

Claude Code reads CLAUDE.md at the start of each session. A few lines about your board save it from guessing which command builds, which one flashes and what a good boot looks like. Adapt this template to your project:

## Hardware testing with Termethos (MCP server "termethos")

- Board: ESP32 DevKitC on COM5, 115200 baud, connection "DevKitC" in Termethos.
- Build and flash: `pio run -t upload`. The port must be free:
  call termethos `disconnect` before flashing and `connect` after.
- The firmware prints "ready" when boot is complete.
- Errors start with !E, warnings with !W (read_trace level filter).
- Dashboard: field 0 = free heap, field 1 = Wi-Fi RSSI, field 2 = state.
- Quick command "Reset board" resets the ESP32 through DTR/RTS.
- After a change, verify on the board: wait for "ready", then read
  errors since the reset. Don't call a fix done before that.

The flash-and-verify loop

Claude Code edits and flashes the firmware from your project, with PlatformIO, Arduino CLI, ESP-IDF or whatever your project uses, and works with the board through Termethos. Allow connecting and disconnecting in the Termethos AI agents dialog so it can free the port while it flashes. A typical run:

# 1. edit the firmware source            (Claude Code)
# 2. free the serial port
termethos · disconnect
# 3. build and flash                     (Claude Code)
pio run -t upload
# 4. reopen the port and wait for the boot to finish
termethos · connect
termethos · wait_for_trace   pattern: "ready", timeoutMs: 20000
# 5. verify on the board
termethos · read_trace       level: "warning", since: <cursor from step 4>
termethos · read_dashboard

A prompt that starts it: "Fix the sensor timeout, flash it, and confirm there are no errors after boot and that field 3 shows a reading."

Simulation mode: without a license, Claude Code can read the simulated trace and dashboard, which is enough to try the setup. Commands reach a real device once Termethos is activated.

Prompts to try

The commands in these prompts are examples. Use the ones your firmware understands.