<p align="center"> <img src="assets/logo.svg" width="440" alt="switchboard"> </p>

English | 繁體中文 | 简体中文 | 日本語 | 한국어

switchboard: a session board for Claude Code (a Claude Code mod)

A Claude Code plugin, built on Claude Code mods, that lists every local Claude Code session in one Board pane, so you can see at a glance which sessions are working, which are idle, and which are blocked on you. Sessions in the Desktop Code tab and sessions in iTerm, Terminal.app or the VS Code terminal all show up in the same list. The Board opens both in Claude Desktop and in Claude Code in a terminal.

<p align="center"> <img src="assets/board/board.en.png" alt="The switchboard Board pane with two sessions that need you, two working and one idle (illustration)" width="412"> </p> <p align="center">_{Illustration: two sessions need you (an approval and a question), two are working, one is idle.}</p>

The way a switchboard operator sees which lines are lit, switchboard has every session report its own state and puts the ones waiting on you at the top:

| State | Meaning | Example | |---|---|---| | Needs You | Nothing moves until you look | A permission prompt for npm install, a multiple-choice question, a question box at the end of a Desktop turn, a turn stopped by an API error | | Working | Claude is running a turn | Thinking, calling tools, running subagents | | Idle | The turn is over and nothing is blocked | Finished and waiting for your next prompt; a turn you interrupted yourself | | Ended | The session was closed or its process exited | Removed from the list at once |

Why does a plain-text question count as Idle? Needs You only reacts to explicit signals (permission prompts, choice cards, the question box Desktop shows at the end of a turn, errors), so when it lights up, something really is waiting on you. A question Claude asks in plain text is Idle, and the last-reply preview on its row lets you spot it.

Quick start

claude plugin marketplace add wide3751/switchboard
claude plugin install switchboard@switchboard

Restart Claude Desktop, then in the Code tab:

1. Type /switchboard:open, or click ▦ Open board above the prompt
2. The Board opens on the right, with a line such as ▲ 2 need you at the top

From then on the Board opens in every Desktop session by default. See Install and Usage for details.

Install with an AI agent

Paste this to Claude Code or any other coding agent:

Install switchboard by following https://github.com/wide3751/switchboard/blob/main/README.md

Requirements

• macOS
• The Claude Desktop app with the Code tab
• Claude Code with mods support (developed and tested on v2.1.299; type /status in the Code tab to check)
• Optional: git for branch and change details, and gh signed in for pull request details

Install

1. Add the marketplace and install. There are two ways; GitHub is recommended:

   Option A: from GitHub (recommended) — no need to download the project:

claude plugin marketplace add wide3751/switchboard
claude plugin install switchboard@switchboard

To update to a new version later, update the marketplace, then the plugin, and restart Claude Desktop (running install again on an installed plugin does not upgrade it):

claude plugin marketplace update switchboard
claude plugin update switchboard@switchboard

Option B: from a local folder — for when you have cloned the project and want to install your own changes:

git clone https://github.com/wide3751/switchboard.git ~/Projects/switchboard
claude plugin marketplace add ~/Projects/switchboard
claude plugin install switchboard@switchboard

2. Restart Claude Desktop, then type /switchboard:open in the Code tab and check that the Board opens.

Sessions that were already open before you installed do not load the mod. They still appear on the Board, but with basic status only; restart them to get full details.

Usage

| Command | Description | |---|---| | /switchboard:open | Open the Board in this session, Desktop or CLI |

On the Board:

• Header: how many sessions need you and how long the longest one has waited. The same count appears in the pane title, for example Switchboard · 2
• Account usage: on a subscription, 5-hour and weekly rate-limit usage with their reset times; on API billing, the total spent across sessions
• Sections: Needs You → Working → Idle; within a section, most recent activity first. Idle sessions stay on the list however long they sit, and the Idle section can be collapsed
• Click a title to jump to that session: a Desktop session opens in Claude Desktop; a CLI session in iTerm or Terminal.app switches to its tab. Needs You rows also have Go handle it →
• Expand ▾ on a row shows the rest of its details
• View opens the settings below

While the Board is closed in a Desktop or CLI session, an ▦ Open board button sits above the prompt; one click opens it without typing the command. If you close the Board in a session, it no longer opens there by itself until you run /switchboard:open or click that button again.

In a CLI session (iTerm, Terminal.app, the VS Code integrated terminal), /switchboard:open opens the Board right in that terminal, with the same content as in Desktop, truncated to the terminal's width. In a fullscreen terminal that is wide enough it docks beside the conversation; otherwise it sits above the prompt. If your terminal doesn't report mouse clicks, move into the pane with the keyboard, pick with the arrow keys and press Enter.

Supported terminals:

| Where claude runs | Listed on the Board | Opens the Board | Click to jump | Tested | |---|---|---|---|---| | Claude Desktop Code tab | ✓ | ✓ | ✓ switches to that session | ✓ | | iTerm | ✓ | ✓ | ✓ switches to its tab | ✓ | | Terminal.app | ✓ | ✓ | ✓ switches to its tab | ✓ | | VS Code integrated terminal | ✓ | ✓ | Shows the folder | Not yet | | Other terminals (Warp, Ghostty, …) and tmux | ✓ | ✓ | Shows the folder | Partly (tmux: listing and opening the Board) | | VS Code extension (graphical UI) | — | ✕ | — | Not yet |

Every terminal session is listed and reports its status, because that only needs Claude Code itself. Jumping needs the terminal to let another app switch its tabs, so for now it only works in iTerm and Terminal.app. Inside tmux, a session counts as tmux rather than the terminal around it, so it shows the folder too. Everything for iTerm and Terminal.app has been tested by hand, including jumping. Inside tmux only listing and opening the Board were tested. The VS Code integrated terminal, Warp, Ghostty and the VS Code extension haven't been tested yet; their rows describe what should happen.

Settings (the View panel; stored globally and shared by all sessions):

| Name | Default | Values | |---|---|---| | Show in every Desktop session | on | on: the Board opens whenever a Desktop session starts or finishes a turn, so it stays in view as you switch; off: only in sessions where you ran /switchboard:open | | Show in every CLI session | off | on: the Board opens whenever a CLI session (a terminal running claude) starts or finishes a turn; off: only in sessions where you ran /switchboard:open. Set separately from the Desktop option | | Language | Auto | Auto (follows the macOS language), EN, 日本語, 한국어, 简中, 繁中 | | Billing | Auto | Auto, Subscription (shows rate limits), API (shows cost) | | Section | Working | Which section the density and fields below apply to: Needs You, Working or Idle | | Density | per section | Compact, Standard, Detailed, or Custom when you pick fields yourself |

Fields each row can show:

| Field | Shows | |---|---| | Time | How long the session has been in its current state | | Location | Project folder | | Branch | git branch, ahead/behind, uncommitted files | | Changes | Lines added and removed against the base branch, like Desktop's Changes | | PR | The branch's pull request; for a Desktop session with unpushed work and no PR, Create PR ↗ jumps to it | | Progress | Todo progress and the current item | | Activity | The tool call in progress | | Background tasks | Running subagents and background shell commands | | Context | Context window usage | | Connectors | Connected MCP connectors, and ones that need auth | | Last reply | A short excerpt of Claude's latest reply | | Model | The model; shown anyway when an active session uses a different model from the rest | | Usage | Turns, plus cost on API billing | | Environment | Worktree or Remote | | Source | The terminal a CLI session runs in | | Full path | The full working directory |

On a Needs You row the approval preview (the command it wants to run), the question with its options, or the error that stopped the turn always shows.

Examples

Three sessions are running: one is stuck on a permission prompt, one is working, one is done. The Board header shows:

▲ 1 needs you
Approve 1 · longest 3m

Its row shows the command it wants to run, for example $ npm install jsonwebtoken, with Go handle it → next to it.

Once nothing is waiting:

✓ Nothing needs you
Working 1 · Idle 2

Limitations

• macOS only: the Board opens in Claude Desktop and in Claude Code in a terminal; the VS Code extension's graphical UI isn't supported. CLI sessions don't open it by themselves unless you turn on Show in every CLI session; otherwise run /switchboard:open.
• CLI sessions jump only in iTerm and Terminal.app: in other terminals (VS Code, Warp, Ghostty, …) clicking one shows the folder it runs in. The first jump makes macOS ask whether to allow controlling iTerm or Terminal; choose Allow.
• Narrow terminals don't open it by themselves: with Show in every CLI session on, Claude Code only draws a pane it wasn't asked for once the terminal is at least 144 columns wide (110 if you've opened the Board there before). Until then the ▦ Open board button stays above the prompt; click it or run /switchboard:open to open the Board at any width. Widen the terminal and the waiting Board appears by itself.
• Updates are polled: every 3 seconds, so a change shows up within a few seconds rather than instantly. Each session that shows the Board scans on its own.
• Sessions without the mod show basic status only: no Errored state, approval preview or last reply, for example sessions that were open before you installed.
• Local sessions only: subagents and cloud sessions are not listed.

Troubleshooting

| Symptom | What to do | |---|---| | /switchboard:open answers that the hooks did not load | Look for hooks module switchboard errors with claude --debug or in the debug log | | The command says the Board can't be shown here | You ran it in the VS Code extension's graphical UI; type it in the Desktop Code tab or in Claude Code in a terminal instead | | A row says switchboard not loaded, basic status only | That session was opened before you installed; restart it | | No PR shown | Install gh and run gh auth login; the session's folder must be a GitHub repository | | Clicking a CLI session only shows a path | Only iTerm and Terminal.app can jump; switch to other terminals yourself. If iTerm or Terminal.app also only shows a path, allow controlling them in System Settings › Privacy & Security › Automation, or restart that session (sessions started before this version did not record their terminal) | | Show in every CLI session is on, but the Board doesn't appear in a terminal | The terminal is too narrow for a pane that opens by itself (under 144 columns). Click ▦ Open board above the prompt or run /switchboard:open, or widen the terminal | | Code changes have no effect | Installed copies are cached by the version in plugin.json. Bump the version, run claude plugin update switchboard@switchboard and restart |

Privacy and data

switchboard runs entirely on your Mac and sends nothing to any service of its own.

• Written locally: each session's status report at <Claude config dir>/switchboard/reports/<sessionId>.json, with the model, branch, todo progress, current activity, approval preview, question, error, a short excerpt of the last reply, background tasks, rate limits, connectors and the pull request. Reports from sessions that no longer exist are removed
• Read locally: Claude Code's own ~/.claude/sessions/*.json records and these reports. Other sessions' .jsonl transcripts are never read
• Commands it runs: git (branch and changes), gh pr view (the pull request, which contacts GitHub with your own gh login), ps (which sessions are alive), defaults read -g AppleLanguages (UI language), open (jumping to a session), osascript (switching to the session's tab in iTerm or Terminal.app)

How it works

Every session loads the mod, which has two jobs:

1. Reporter: listens to its own session's events (session.start, turn.start, tool.call, turn.complete, …) and writes its status report.
2. Board: only in sessions that show the Board. Every 3 seconds it merges the reports with Claude Code's session records, drops sessions whose process is gone, and draws the list.

Whether a session exists is decided only by Claude Code's records and whether its process is alive, so a stale report can never keep an ended session on the list. When the two sources disagree, the newer one wins.

Contributing

Issues and pull requests are welcome. Before changing behavior, read CONTEXT.md for the terminology and the decisions in docs/adr/ (both in Chinese). When you add or change UI text, update all five languages in agens-view/hooks/i18n.ts.

Docs

• CONTEXT.md: terminology (Session, Needs You, Board, Status Report…)
• docs/adr/: architecture decisions

License

MIT