Agent Switchboard

Your coding agents as peers on one machine. Claude Code talks to a pi worker and an OpenCode worker: it delegates whole tasks, nudges running sessions, and hears back — every pair messageable, nothing copy-pasted between terminals.

Setup — pick one

A. Just try it (taste, may break later when npm prunes its cache):

npx -y -p github:raymond-UI/agent-switchboard switchboard-install

B. Use it (durable, still no clone) — this is the normal path:

npm install -g github:raymond-UI/agent-switchboard
switchboard-install

C. Hack on it: git clone https://github.com/raymond-UI/agent-switchboard, then node scripts/install.mjs.

All three install the worker plugins, register the bridge, and print the one Stop-hook snippet for your Claude settings. You need: Node.js ≥ 18, the Claude Code CLI, and whichever workers you want (pi, OpenCode v1.18+). Windows works identically (forward slashes in settings paths).

It worked if: agent_sessions lists your workers, and pi_inbox answers without errors. Then hand a worker something tiny with absolute paths.

Related MCP server: pi-delegate

The loop (30 seconds)

Instructions to workers must be self-contained with absolute paths — they can't see your Claude conversation.

Upgrading

Re-run whatever installed it — it reinstalls plugins, re-registers MCP, and reprints the hook snippet. Idempotent; running sessions keep their loaded copies, new sessions pick everything up:

switchboard-install          # paths B and C (C: `node scripts/install.mjs`)
npx -y -p github:raymond-UI/agent-switchboard switchboard-install   # path A

No migration steps between versions so far; if one ever lands, it will be announced at the top of this section.

Tested: pi 0.85.0, OpenCode 1.18.30, Node 20/22/24 (CI × ubuntu/macos/windows).

Across machines (worker box)

Run pi and OpenCode on a second machine so the coordinator (your laptop running Claude) stays light. Install switchboard on both (path B above), then:

switchboard-pair                 # 1. on the WORKER: prints a code, starts serving
switchboard-connect sb1.…        # 2. on the COORDINATOR: paste that code

Restart Claude on the coordinator and you're done. It uses the same tools and the same hook snippet, and async results still reach the session that started them. Claude is told which machine the workers are on. Paths you give workers refer to the worker machine (switchboard-connect --status shows their working dirs).

Notes: the code contains the access token (switchboard-pair --rotate revokes it). Both machines need to be on the same LAN, or use Tailscale from anywhere. Undo with switchboard-connect --local.

Always-on worker: switchboard-pair --service instead of step 1. It installs a background service (launchd on macOS, systemd user unit on Linux) that starts at login and restarts if it crashes, and prints the same code. Run it from the project dir (or set PI_CWD/OC_CWD). It captures your PATH and model settings but not provider API keys. Re-run after changing them. Remove: switchboard-pair --remove-service. Windows: keep switchboard-pair open in a terminal.

From your phone: switchboard-pair also prints a Phone link. Open it on a phone on the same network (or Tailscale) to get a chat page for pi and OpenCode: send tasks, watch them run, nudge or stop them, read replies and cost. The link logs the phone in; treat it like the code. Full diagram: docs/network-vision.html.

Two agents, one checkout: give each its own worktree (./scripts/setup-worktree.sh /path/to/project) or split folders by agreement. Two writers in one tree with no ownership split will stomp each other — the tooling detects, it doesn't merge.

Rules that bite (read once)

1. Replies need addresses. agent_send to a live session id is precise; * broadcasts wake every paired session (each burns a turn).

2. New sessions don't inherit backlog. Workers only receive messages sent after they were born (exact id/file addressing bypasses). Re-brief instead of relying on history.

3. Async results are pull-only... with one new exception. A pi_ask_async / oc_ask_async ticket result lands in pi_inbox for everyone AND fires the Stop hook for the Claude session that dispatched it (multi-agent safe: each Claude writes its own dispatcher sidecar, the bridge stamps the ticket at dispatch time, the hook routes by exact match). Tickets that were never stamped (no PreToolUse hook, or different tool) stay pull-only.

4. Idle Claude sessions can't be pushed to. The Stop hook fires on transitions; a parked session needs one nudge (check pi_inbox) or a desktop notification — there is no timer hook. Nothing is ever lost: the bus is durable, pull anytime.

5. Async results are pull-only by default. Ticket results skip the Stop hook so they can't spray into a sibling session — collect by ticket id in pi_inbox. (If the PreToolUse dispatcher hook is installed, async results ALSO fire the Stop hook for the Claude session that dispatched them.)

6. The bus is trusted. Anyone who can write to AGENT_BUS can whisper to your agents. Same bar as project files. Bus dirs auto-ignore themselves in enclosing git repos.

Who can orchestrate whom

| Orchestrator | Drives pi | Drives OpenCode | Drives Claude | How | |---|---|---|---| | Claude Code | pi_ask | oc_ask | — (self) | MCP bridge, always on | | OpenCode | MCP bridge | MCP bridge | delegate_claude tool | Add bridge to opencode.json; flag-gated tool | | pi | bus only (message_claude {to}) | delegate_oc / bus | delegate_claude tool | Flag-gated tools |

Worker→worker also works over the bus (message_claude {to}). Multi-orchestration is flag-gated (SWITCHBOARD_MULTI_ORCH=1) and depth-capped (SWITCHBOARD_DEPTH/SWITCHBOARD_MAX_DEPTH, default cap 2): delegation depth travels in env across every spawn, and any delegate tool at the cap refuses with a clear error instead of looping A→B→A forever. Live-verified: pi → delegate_claude round-trip (DELTEST).

Reference

Tools (16): pi_ask[_async], pi_steer, pi_abort, pi_new_session, pi_state, oc_ask[_async], oc_steer, oc_state, oc_abort, oc_new_session, agent_send, agent_sessions, agent_tickets, pi_inbox. One-line descriptions in-tool; details here.

Env (essentials): AGENT_BUS (must match on all sides when dirs differ), PI_CWD / OC_CWD, PI_MODEL / OC_MODEL (provider/model), PI_ASK_TIMEOUT_MS (15 min), RESULT_CAP (8k chars, overflow spills to $AGENT_BUS/results/). Full table in code: bridge/env.mjs, bridge/oc-session.mjs.

Layout: bridge/ (env, bus, format, MCP server, pi-session, oc-session, launcher), hooks/pi-inbox.mjs (Stop hook), pi-extensions/, opencode-plugin/, test/ (stubs + node:test suites), scripts/ (installer, pair/connect, worktree setup). Original design doc: PRD-agent-switchboard.md.

Security: localhost only (bridge servers bind 127.0.0.1 with per-spawn passwords; MCP is stdio, no auth by design). The one exception is switchboard-pair, which you run on purpose: it binds the network and requires the token. It refuses to bind the network without one. Traffic is plain HTTP: over Tailscale it's encrypted, but on shared Wi-Fi the token and your messages are readable, so prefer the Tailscale address (listed first). Don't weaken silently — see CONTRIBUTING.md.

For contributors

npm test — zero deps, stub-first (fixtures for both harnesses' protocols), live runs for final verification only. Hard rules: claim-before-emit on every take-one primitive; worker→Claude is always async (a sync callback into a blocked ask deadlocks both processes); never import the MCP server into the test runner (stdin listener hangs it). Design history (settle races, ticket spray incident, stale-backlog gate, UI-blanking bisect, poisoned-preload immunity) lives in git log + code comments. MIT — see LICENSE.