Agent serial access

Getting Started

Agent serial access

Let Claude Code or Codex read the serial console of your board instead of asking you to paste logs. The agent can wait for a boot line and, when you allow it in the serial tab, type into the port or borrow it for flashing.

NeuroTerm asks in the serial tab before the agent borrows the port to flash; nothing happens until you click Allow. The board is simulated in the demo.
NeuroTerm asks in the serial tab before the agent borrows the port to flash; nothing happens until you click Allow. The board is simulated in the demo.

Where it works

Agent serial access works for Claude Code and Codex started in a NeuroTerm Local or WSL tab, on Windows or Linux.

It is not available over SSH: an agent on a remote host cannot reach NeuroTerm, so start it in a Local or WSL tab on the computer NeuroTerm runs on. It is not supported on macOS.

Set up

  1. Open Settings → Session → Agent integration and choose Set up… for this computer or a WSL distribution.
  2. Keep the Agent serial access box ticked (it is ticked by default) and confirm. NeuroTerm registers its server with Claude Code and Codex.
  3. Agents already running need /mcp (Claude Code) or a restart (Codex) to see it. Remove on the same card takes it off again.

The same card sets up Agent alerts and Agent resume.

What the agent can do

  • list_serial_sessions — Lists your serial tabs: port, baud rate and whether each is connected.
  • read_serial — Reads a tab’s output as plain text, with colours and cursor codes removed.
  • wait_serial — Waits up to 50 s for a line that matches a pattern, such as a boot prompt.
  • get_serial_markers — Returns the errors, warnings and boot stages NeuroTerm marked in that tab.
  • serial_send — Types up to 1 KB into the port. Needs your Allow.
  • release_serial_port — Asks to borrow the port for flashing, for 10 s to 10 minutes. Needs your Allow.
  • reacquire_serial_port — Gives the port back; the tab reopens it.

You approve in the serial tab

When the agent wants to type into a port, the serial tab shows a banner with the exact bytes and three buttons: Allow, Allow for this session and Deny. It waits 45 s; no answer means no.

Allow for this session lets that agent tab type into that serial tab until you press Revoke, either tab closes or NeuroTerm quits. Borrowing the port is asked for every time.

Borrowing the port for flashing

When you allow a borrow, NeuroTerm closes the port so the agent’s own flashing command (esptool, west, pio and the like) can use it, and other tabs cannot open that port meanwhile.

When the agent gives it back, the tab reopens the port; reopening may reset the board. If the borrow time runs out, the port stays closed until you press Reconnect.

Privacy and safety

The agent talks to NeuroTerm over a local connection only your user account can open, and NeuroTerm sends nothing over the network for it. NeuroTerm does not redact what the agent reads, and the agent may send it to its own AI provider, under that provider’s terms.

Device output is treated as untrusted: the tools tell the agent never to follow instructions found in it.

If the agent cannot see your tabs

  • “not running inside a NeuroTerm tab”: start the agent from a Local or WSL tab, not from another terminal.
  • “NeuroTerm is not running”: open NeuroTerm and check that Agent serial access is set up on that host.
  • The tools only see serial tabs. Codex started natively on Windows can miss the tab it runs in; start it from a WSL tab instead.