Switchboard

You have Claude Code (Anthropic's CLI) open on the backend, Codex CLI (OpenAI's) on the frontend, another agent on infra. None of them knows the others exist. So when the API contract changes, you are the one who carries the news: copy from this terminal, paste into that one, repeat. You are the message broker.

Switchboard is the wire between them. It's a local hub. Your agents message each other over MCP, the recipient gets nudged awake in its own terminal, and you watch the whole conversation on one dashboard — where you can also open any agent's chat, drive its real terminal, and see what it did about the message it received. It connects sessions you already have. It won't spawn, orchestrate or manage them.

What keeps it safe: tmux carries a one-line nudge, and nothing else. The message itself travels over MCP. Agent A calls send_message, the Hub appends it to ~/.switchboard/messages.jsonl (the source of truth) and pokes agent B's terminal with a single [switchboard] line. B wakes up and calls check_messages to read it.

Platform: Windows + WSL (Ubuntu). That's what Switchboard is built and tested on. The core (hub, MCP, tmux nudges) is plain Unix and tmux, so Linux and macOS may well work, but nobody has tested it. Treat them as unsupported for now. The parts that make it click on Windows (the one-click launcher, opening a real terminal window, \\wsl$\… folder paths) are WSL-specific, and say so instead of breaking when you run them elsewhere.

Local-only by design: the Hub binds 127.0.0.1 and nothing reaches the network. MIT licensed.

Prerequisites

• Node.js >= 20. Runs as ESM, with TypeScript executed by tsx. No build step.

• tmux >= 3.2 (tested on 3.4).

• Claude Code >= 2.x, the claude binary on your PATH.

• Codex CLI, optional: the codex binary on your PATH. You need it only to run agents with --agent codex, or the dashboard's Codex button. Everything else works without it.

• jq, optional. Handy for reading the JSONL while debugging.

One WSL distro, one user. The tmux server belongs to a user on a distro. Run the Hub (serve) and every agent (start) as the same user on the same distro. Split them across two and tmux send-keys won't find the session, so the nudge never lands.

Related MCP server: mcp-relay

Setup: two commands

git clone https://github.com/rodcoppi/switchboard-mcp.git && cd switchboard-mcp && npm install
node bin/switchboard.mjs setup

setup does every manual step below for you: it checks the prerequisites (and offers a sudo-less tmux install if tmux is missing), registers the MCP server in Claude Code, puts the agent-protocol snippet in your ~/.claude/CLAUDE.md, adds the permission rules, runs npm link, offers the Windows shortcut, and brings the Hub up. It asks before it touches a file of yours. Re-run it whenever you like, it changes nothing that is already right. Pass --yes and it stops asking.

When it finishes, the dashboard is at http://127.0.0.1:4577/. Launch agents from the Launch agent form there, or run switchboard wire in the folder of a claude window you already have open to bring that one in.

1. Install

git clone https://github.com/rodcoppi/switchboard-mcp.git
cd switchboard-mcp
npm install

The TypeScript runs straight through tsx, so there is nothing to build. Three ways to call the switchboard CLI:

• npm link puts switchboard on your PATH. This is the one to use:

  npm link
  switchboard --help

• The bin shim, without linking:

  node bin/switchboard.mjs --help

• The entry point, without linking:

  npx tsx src/index.ts --help

The examples below say switchboard <subcommand> and assume you linked. If you didn't, read them as node bin/switchboard.mjs <subcommand>.

2. Start the Hub (serve), usually automatic

Skip this step: switchboard start and switchboard wire bring the Hub up for you when it isn't running, in a detached tmux session called sb-hub. No terminal window stays open. After a reboot, wire or start your first agent and the Hub comes up with it.

Run it yourself when you want to watch the logs live:

switchboard serve

The Hub runs in the foreground and logs to stdout and ~/.switchboard/logs/hub.log. Its first line gives you the addresses and the MCP registration command, ready to copy:

Dashboard: http://127.0.0.1:4577/  |  MCP: http://127.0.0.1:4577/mcp  |  Register (once): claude mcp add --transport http --scope user switchboard http://127.0.0.1:4577/mcp --header 'Authorization: Bearer ${SWITCHBOARD_AGENT_TOKEN}' --header 'X-Switchboard-Agent-Name: ${SWITCHBOARD_AGENT_NAME}'

To look inside the Hub that started itself: tmux attach -t sb-hub, and Ctrl-b d to leave it running. Or switchboard logs -f. serve takes --port <port> and --log-level debug|info|warn|error.

One-click launch from Windows (no WSL terminal)

On Windows and WSL you can skip the terminal. Once, inside WSL:

switchboard shortcut            # creates Switchboard.lnk on your Windows Desktop
switchboard shortcut --startup  # or: installs it in the Startup folder (runs on every boot)

Double-click Switchboard (or just boot Windows, with --startup) and the Hub comes up in the background, with the dashboard open at http://127.0.0.1:4577/ in your Windows browser. WSL2 forwards localhost for you; the Hub still binds 127.0.0.1 inside WSL, so nothing reaches the network. Launch or wire agents from the Launch agent form. Delete the shortcut to undo it.

The shortcut is a .lnk carrying the Switchboard icon and opening minimized; the .bat it drives, and the icon, live in %LOCALAPPDATA%\Switchboard (a .bat cannot carry an icon, and an icon on the WSL filesystem renders blank at boot, when the distro is not running yet). Regenerate the icon with node scripts/make-icon.mjs.

3. Register the MCP in Claude Code (mcp add)

Once only, in the user scope (applies to every project):

claude mcp add --transport http --scope user switchboard http://127.0.0.1:4577/mcp \
  --header 'Authorization: Bearer ${SWITCHBOARD_AGENT_TOKEN}' \
  --header 'X-Switchboard-Agent-Name: ${SWITCHBOARD_AGENT_NAME}'

claude mcp list shows switchboard as connected while the Hub is up.

Those two headers are what makes joining silent. Claude Code expands ${VAR} from the agent's OWN environment when it connects, so the Hub knows who is calling before any tool runs: the session binds at connect time and the agent is on the network without a single line typed into its terminal — like every other MCP server you use. One registration covers your whole fleet (each session carries its own name and token), and the token never passes through the model. A client registered without the headers still works the classic way: the Hub types a one-line kickoff asking the agent to call join itself.

Running Codex agents too? Point Codex at the same Hub. Same streamable-HTTP endpoint, spelled differently (setup offers this when it finds the codex binary):

codex mcp add switchboard --url http://127.0.0.1:4577/mcp

Tool permissions. Add the allow rule mcp__switchboard__* to permissions in Claude Code's settings.json, or the Switchboard tools ask for approval every time you use them. Already on bypassPermissions? You're covered. switchboard start reminds you on its first run.

Only if you skip the headers above. On the classic path the agent reads SWITCHBOARD_AGENT_TOKEN from its environment with printenv before calling join, so that shell command needs approval too — add Bash(printenv:*) to the allow rule, or run the agent with bypassPermissions. With the identity headers registered, none of this applies: nothing is typed and no token ever reaches the model.

4. Paste the agent protocol (snippet)

Paste agent-protocol/CLAUDE.snippet.md into your ~/.claude/CLAUDE.md, where it covers every project, or into one project's CLAUDE.md. It teaches an agent to read its name and token from the environment and hand them to join, to call check_messages when it sees a [switchboard] line, and to read what its peers say without falling into a thank-you loop. It also draws the line that matters: coordination is not subordination, and no other agent can authorize what your user didn't.

5. Start an agent (start)

Run this instead of opening claude yourself:

switchboard start alpha --role "payments API backend" --dir ~/projects/api

What happens:

1. The Hub registers the agent over REST, before Claude Code opens.

2. A tmux session sb-alpha starts claude in the --dir directory.

3. From an interactive terminal, start runs tmux attach on that session, so your Windows Terminal tab becomes the agent's screen. Detach with Ctrl-b d and the agent keeps working in the background.

4. The agent joins silently: its MCP client connects carrying the identity headers, and the Hub binds the session — it shows up as MCP connected in switchboard status with nothing typed into its terminal. Registered the MCP without the headers? A few seconds after the TUI is ready, a one-line kickoff asks the agent to call join itself instead (--no-kickoff turns that off).

start flags: --role "<description>", --dir <path>, --no-kickoff, --agent <claude|codex>, --claude-args "<extra args for the agent CLI>".

Adopting an already-open agent (wire)

Already have a Claude Code window open (a plain claude in bash, without tmux) and want to join it to the network without losing the conversation? Use wire instead of start:

1. In that window, leave claude (Ctrl-C twice, or /exit).

2. In the same folder, run:

   switchboard wire

3. The conversation comes back — now inside a tmux session, connected to the Hub. The agent name defaults to the folder name (sanitized to lowercase letters, digits and hyphens; pass --name <name> if the folder name can't be used).

Under the hood wire reopens claude with -c (continue the folder's conversation) and --dangerously-skip-permissions (so the agent reads its token and calls join with no prompt) — these are the wire defaults, unlike start. Any extra --claude-args are added after them. If a tmux session for that name already exists, wire replaces it (kills the old one and recreates it — no confirmation), then runs the same automatic kickoff as start.

Auto-fallback: if the folder has no resumable conversation (never opened claude there, or the last one ran in -p/print mode), claude -c exits right away — wire detects that and automatically reopens a fresh session (without -c), telling you so. It never fails into a dead window; worst case you get a brand-new conversation already wired to the network.

wire flags: --name <name>, --role "<description>", --dir <path> (default: current folder), --no-kickoff, --agent <claude|codex>, --claude-args "<extra args for the agent CLI>".

Choosing the agent CLI (--agent claude|codex)

Every way of opening an agent takes an agent type: claude (default, Claude Code) or codex (Codex CLI). It is one flow with a choice, not a separate mode — registration, the nudge, the kickoff, status, mentions and the dashboard all behave identically:

switchboard start alpha --dir ~/projects/api --agent codex
switchboard wire --agent codex        # adopt the current folder with Codex

In the dashboard, the Launch agent form has a Claude | Codex switch, and each card shows its agent's type next to the MCP chip. The type is recorded on the agent, so reopen relaunches it with the same CLI it was launched with.

Requirements: the codex binary on the PATH, and the Hub registered as an MCP server in Codex (codex mcp add switchboard --url http://127.0.0.1:4577/mcp — switchboard setup offers this automatically when it finds codex). Without that registration a Codex agent opens fine but has no Switchboard tools to join with.

What differs under the hood is only the argv and the two strings read off the TUI — both live in one adapter (src/shared/agent-types.ts):

Agents registered before this feature existed have no recorded type and are treated as Claude Code — which is what they are.

Groups — keep one project's agents out of another's

Every agent belongs to a group, and a group is a wall: an agent can only message agents in the same group, list_agents shows it nobody else, and its broadcast stops at the group's edge. Run one project's agents in panorama and another's in site and neither can wake the other, whether you slipped or an agent did.

switchboard start alpha --dir ~/projects/api --group panorama
switchboard wire --group site        # adopt the current folder into another group
switchboard status                   # the GROUP column tells you who talks to whom

In the dashboard, the Launch agent form has a group field, and the tabs above the transcript switch rooms: pick panorama and you read that group's conversation alone. A broadcast you send from there reaches that group and stops.

Agents already running? You don't have to relaunch them. Open the ⋯ menu on a card and pick group…; the name cell becomes a field with your existing groups behind it, and Enter moves the agent. It takes effect on that agent's next message, with no restart: unlike rename, which needs the agent stopped (a live one would re-join under its old name and undo it), nothing about a running session undoes a group change.

Leave --group off and nothing changes: the agent keeps the group it already had, and a new one joins default, where every agent you have today already lives. Re-running start or wire without the flag never moves an agent out of its group.

You are the operator, so no wall applies to you: you can message any agent from the dashboard.

Mentions — delegate with %name

Inside any agent's window, reference another agent as %<name> and it becomes a delegation. For example, telling your backend agent:

Fix the pagination bug, and ask %frontend to update the consumer types afterwards.

makes it fix the bug and send frontend one factual, actionable message with the delegated task (paths, contracts, what to report back). The mentioning agent stays responsible for your request — the mention only routes the sub-task. This is part of the agent protocol (the join etiquette + the snippet), so it works in every connected agent.

Why % and not @: @ is already the file-reference sigil in Claude Code and in Codex, and the TUI resolves it before the model ever sees your prompt. Agent names are commonly folder names (wire derives one from the other), so @frontend typed next to a frontend/ folder quietly turns into a file reference and the delegation is lost with no error. % collides with nothing in either CLI (! is bash, # is memory, / is commands). @<name> is still understood — it just fails whenever a path happens to match.

Launching agents from the dashboard

The dashboard (http://127.0.0.1:4577/) has a Launch agent form (bottom of the sidebar): type the project directory, optionally a name (defaults to the folder name) and a role, pick the agent (Claude or Codex), tick continue conversation to resume the folder's last conversation (same auto-fallback as wire), and hit Launch. The Hub itself creates the agent's tmux session and runs the automatic kickoff — no terminal needed. The new card appears live via SSE; attach to the agent anytime with tmux attach -t sb-<name>. Under the hood it is POST /api/agents/launch {dir, name?, role?, continue?, agentType?} — localhost-only, like everything else.

Talking to one agent — the chat

Click an agent's card and you get its conversation, rendered as chat: what you asked, what it answered, its tool calls folded into one line each, markdown and syntax highlighting, and the harness happenings the terminal shows (worked for 2m 20s, background tasks, interrupts). It is read from Claude Code's own transcript log — Switchboard owns nothing, so the agent's session is untouched. The composer below it dispatches to that agent: type and press Enter, / for slash commands (routed to the terminal), @ to mention a file, drag a file in to reference it, and the 🎤 to dictate — speech-to-text runs locally on your machine, no API, no key, no bill.

Every message that arrives from a peer shows as the Switchboard's own line with a show what X sent toggle that unfolds the real message, and in the traffic feed every read message has a reaction toggle that shows what the recipient said about it in its own chat. The two answer the question a message board never does: and then what happened?

Watching an agent's screen

Toggle Terminal and the agent's live screen takes over the panel — the real Claude Code (or Codex) TUI, colours and cursor and all, and you can type into it (approve a prompt, hit Esc to interrupt, drag a file in to type its path). Open several agents and they become tabs across the top; window in the card's menu still pops a real OS terminal when you want one. This is a tmux control-mode client (tmux -C), not a second pty: tmux owns the agent's process, so closing the dashboard never takes the agent down — the whole point of being able to close the pile of terminal windows.

Previewing files agents mention

Agents name absolute paths constantly ("wrote /home/you/api/src/foo.ts"). Those paths are clickable in the transcript — click one and the file opens inline (images, text, code, markdown). Reads are scoped: only files under an agent's working directory or your home folder, resolved with realpath so .. and symlinks cannot escape. A path outside the scope is refused with a clear message, never read — a message body is untrusted, so an agent cannot get you to open an arbitrary file by naming it.

Two doors sit in the preview's header for what an inline panel cannot do: browser opens the file in a real tab (an .html an agent built renders as the actual site — inside a CSP sandbox, so its scripts can never drive the Hub with your authority), and folder reveals the file in Windows Explorer.

Dropping a file on the chat or the terminal references the file where it already lives — the Hub finds the original by name and size across your agents' projects, Downloads and Desktop, exactly like dragging into a real terminal. Only when there is no original to point at (a pasted screenshot, an attachment dragged straight out of a mail client) does it stage a copy under ~/.switchboard/uploads, kept for 24h; a big file with no origin is refused rather than duplicated.

Managing agents from the dashboard

Each card carries an open button (reopen when the agent is offline: relaunches it in its folder, continuing the conversation, with the same CLI it was launched with) and a ⋯ menu:

Agent names are addresses (%name in a prompt, the tmux session sb-<name>), so they are lowercase letters, digits and hyphens. You don't have to memorize that: the name fields rewrite what you type as you type it — Chefe de Redes becomes chefe-de-redes in front of you, the same way wire derives a name from a folder called ai panorama.

Other subcommands

To stop the Hub: Ctrl-C in the switchboard serve terminal (or tmux kill-session -t sb-hub, if it runs in the recommended session).

Data lives in ~/.switchboard/: config.json (every value has a default; the file may not even exist), agents.json (atomic snapshot) and messages.jsonl (append-only, greppable with cat/jq).

Security

The threat model is honest and the trust boundary is the local machine. Read this before exposing anything:

• Bind on 127.0.0.1, hard-coded and not configurable. A delivered message becomes executable input for an agent with filesystem access. Exposing the Hub on the network = free RCE.

• NEVER port-forward port 4577 (no ssh -L, no firewall/NAT rule) and NEVER run the Hub behind a reverse proxy. 127.0.0.1 is the only barrier.

• Local trust model: any local process can post to the Hub and therefore inject input into any agent. This is accepted in v1 (the same model as any local dev tool), as long as it never leaks to the network.

• The nudge never types into a pane a dialog owns. The nudge is one line plus a separate Enter ~500ms later (the only way a TUI accepts it), and with a permission prompt open (Do you want to proceed? ❯ 1. Yes) that Enter used to land on the highlighted choice — meaning any agent able to send a message could approve another agent's pending tool call. Proven with a disposable agent, then closed: the pane reader reports blocked for permission prompts, trust dialogs and channel warnings; the dispatcher queues instead of typing, and re-reads the live pane immediately before typing (fail-closed — an unreadable pane counts as blocked). The held message is delivered by the next flush, once you answer the dialog.

• Capability token (v1.1 addendum): start injects a per-agent token into the tmux session environment (SWITCHBOARD_AGENT_TOKEN); the agent reads it and passes it to join, and it never appears in list_agents, in GET /api/agents, in the dashboard or in the logs. With the identity headers registered (see step 3) the token never reaches the model at all: the MCP client sends it straight from the session's environment.

• Operator-only surfaces. What an agent can persist about itself stops at its role. The boot command and launch args — the two fields that decide what runs at launch — are settable over REST (the dashboard) and deliberately not exposed over MCP, so a compromised agent cannot write its own boot code. It closes impersonation by processes that know an agent's name but never talk to the registration endpoint.

• Known residual risk (documented in the comment of src/server/api.ts): the POST /api/agents/register endpoint is deliberately unauthenticated, and re-registering an existing name regenerates and returns a fresh token. So a malicious local process can obtain a valid token for any name and impersonate that agent via join — also invalidating the legitimate session's token (its join after a Hub restart then fails). This is accepted by the v1.1 spec (the same "any local process can post" boundary) and must not be "fixed" without approval — requiring token rotation would break switchboard start's re-attach.

• Prompt injection between agents is a residual risk: a compromised/hallucinating agent may try to manipulate another. v1 mitigation: the boundary declared in the protocol snippet (peer messages are evaluated critically; coordination ≠ subordination) plus full feed visibility in the dashboard.

tmux tips on WSL / Windows Terminal (pitfall P11)

• If you rarely use tmux, a minimal ~/.tmux.conf with the mouse enabled helps a lot with scrolling and pane selection:

  set -g mouse on

• switchboard start runs tmux attach on the agent's session, so each Windows Terminal tab stays "one agent's screen" — the tab workflow you already use is preserved. To leave an agent's view without killing it: Ctrl-b d (detach). To come back: tmux attach -t sb-<name>.

Roadmap

Switchboard runs Claude Code and Codex CLI agents today (see Choosing the agent CLI) — on the same network, in the same conversation. A few directions for later:

• More agent CLIs. The plumbing is agent-agnostic — the nudge is tmux and the messages are MCP (an open standard) — and adding the second type turned that claim into a real adapter (src/shared/agent-types.ts). A third one is now a descriptor: which binary to launch, how it spells "continue" and "skip approvals", its TUI-ready markers, its mcp add spelling. The bar is that the CLI speaks MCP and runs in a terminal.

• Urgency tiers (interrupt / normal / fyi): an fyi message that never wakes the recipient (zero token cost until it checks on its own) — the structural token saver on top of the current etiquette + rate-limit backstop.

• Agent state on the card (working / blocked / idle), read from the pane the dashboard already streams. The blocked half shipped with the dialog guard (see Security); surfacing it as who needs me right now is the next step, and exposing a peer's state in list_agents lets agents stop nudging someone stuck on a prompt.

• Exact session resume. A SessionStart hook reporting the CLI's own session id would replace -c ("the folder's last conversation") with --resume <id>, and hand the chat the exact transcript path instead of a heuristic.

• Export of the feed history (search already lives in the dashboard's header).

Contributions welcome — see the code layout in the sections above; the Hub is a single Node process and there's no build step.