Switchboard

⇄ Switchboard

Let your Claude Code agents talk to each other.

Run several Claude Code (Anthropic's CLI) agents at once — one on the backend, one on the frontend, one on infra — and today they're blind to each other. Every "the API contract changed" has to go through you, copy-pasting between terminals. You become the message broker.

Switchboard is the wire between them. A local hub that lets your already-running agents message each other directly (over MCP), nudges the recipient awake in its terminal, and shows the whole conversation on one dashboard. It connects sessions you already have — it does not spawn, orchestrate, or manage them.

The trick that keeps it safe and reliable: tmux delivers only a one-line nudge; the message content always 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 over MCP.

Platform: Windows + WSL (Ubuntu) — that's what Switchboard is built and tested for today. The core (hub, MCP, tmux nudges) is plain Unix + tmux, so a Linux/macOS setup might work — but it's untested, so treat non-WSL as unsupported for now. The conveniences that make it click on Windows (the one-click launcher, popping open a real terminal window, \\wsl$\… folder paths) are WSL-specific and degrade with a clear message elsewhere.

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

Prerequisites

• Node.js >= 20 (runs in ESM, with TypeScript executed by tsx — no build step).
• tmux >= 3.2 (validated with 3.4).
• Claude Code >= 2.x (claude binary on the PATH).
• jq (optional, only a convenience for inspecting the JSONL while debugging).

WSL (important — pitfall P8): the tmux server is per user and per distro. The Hub (serve) and all agents (start) MUST run on the same WSL distro and with the same user. If you open the Hub on one distro/user and an agent on another, tmux send-keys cannot find the session and the nudge never arrives.

Setup — two commands

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

The setup wizard does everything the manual steps below describe — checking prerequisites (and offering a sudo-less tmux install when tmux is missing), registering the MCP server in Claude Code, installing the agent-protocol snippet into your ~/.claude/CLAUDE.md, adding the permission allow rules, running npm link, offering the Windows one-click shortcut (Desktop and/or Startup, WSL setups), and bringing the Hub up. It asks before touching any of your files, is idempotent (safe to re-run anytime), and --yes makes it fully non-interactive.

When it finishes: dashboard at http://localhost:4577/, launch agents from the Launch agent form there, and run switchboard wire inside any already-open claude window's folder to adopt it into the network.

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

switchboard serve

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

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

claude mcp add --transport http --scope user switchboard http://127.0.0.1:4577/mcp

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

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, --claude-args "<extra args for claude>".

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, tick continue conversation to resume the folder's last claude 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?} — localhost-only, like everything else.

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.
• 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. 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 v1 targets Claude Code (the CLI). A few directions for later:

• Other agent CLIs (Codex CLI, …). The plumbing is already agent-agnostic — the nudge is tmux and the messages are MCP (an open standard). Codex CLI in particular speaks MCP over streamable HTTP (codex mcp add <name> --url …), the same transport the Hub serves, so connecting it is mostly a small "agent adapter" (which binary to launch, its TUI-ready markers, its MCP config) plus a Claude | Codex choice at launch — not a rewrite.
• 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.
• Searchable feed history and export in the dashboard.

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