switchboard-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

Switchboard project: a local hub that connects independent Claude Code instances running in tmux sessions on WSL, enabling asynchronous message exchange between them (via MCP) with a web dashboard for observation. It connects already-running sessions — it does not spawn or orchestrate agents.

PRD-switchboard.md is the source of truth. The implementation follows the PRD's phases 0–7, in order. Before working on any area, read the corresponding PRD section (and the pitfalls table, section 17).

Executor rules (from the PRD, mandatory)

• Run the phases IN ORDER. Phase 0 (validation spikes) is mandatory and cannot be skipped. Only advance to Phase N+1 with all of Phase N's "Done When" truly verified (by running the command, not assuming).
• Each phase ends with its own commit: feat(phase-N): <summary>.
• If a Phase 0 spike fails → STOP and report the full error. Do not improvise an alternative architecture without approval.
• Do not add dependencies outside the locked stack (PRD section 5). Need something? Ask first.
• Do not invent features outside the PRD. A divergence becomes a question, not a unilateral decision.
• Priority order in conflicts (section 4): local security > convenience; debuggability > elegance; delivery reliability > real time; never block the agent's turn (every MCP tool answers in < 1s); MVP (Phases 0–5) before any pixel of the dashboard.

Locked stack

• Node.js >= 20 (ESM), TypeScript 5.x executed with tsx — no build step, no bundler.
• Production: @modelcontextprotocol/sdk, express, zod, ulid, commander, @xterm/xterm + @xterm/addon-fit, marked, @highlightjs/cdn-assets. Dev: vitest, @types/express, @types/node.
• Browser deps (@xterm/*, marked, @highlightjs/cdn-assets) are all served by the hub straight out of node_modules at /vendor/*, so the dashboard still fetches nothing off this machine. marked renders the chat casca's markdown (tables/lists/code); highlight.js colours the fenced code. These are owner-approved dashboard-polish deps.
• @xterm/xterm is the ONE browser dependency, owner-approved, and it is a terminal EMULATOR — the thing you cannot sanely hand-roll (weeks of escape-sequence bugs). It is served by the hub from node_modules at /vendor/*, so the dashboard still fetches nothing off this machine. It does NOT drag node-pty or websockets in with it: the dashboard terminal is a tmux CONTROL-MODE client (tmux -C attach-session, driven over plain pipes — see src/server/tmux.ts / terminal.ts), input rides send-keys -H (through the pane guard), and SSE already carries the stream. Control mode is what makes the first frame race-free: command responses and %output share ONE ordered stream, so the initial capture-pane and the live deltas cannot overlap or gap (the earlier capture-pane snapshot + pipe-pane tee were two separate commands with an unclosable gap, and Claude Code's cursor-relative repaints turned every lost/duplicated byte into text written over text).
• System prerequisites: tmux >= 3.2, claude >= 2.x, jq (debug).
• Forbidden in v1: websockets, database, ORM, frontend framework, bundler, docker, node-pty. The node-pty ban is about NOT owning the agent's process: a pty running the AGENT would make us a wrapper, and the agent would die with the dashboard. Control mode sidesteps that entirely — tmux owns the agent's pty, our control client is just another observer/driver of the session, and the agent outlives every viewer (test: terminal.integration.test.ts "detach kills the client but NEVER the session").