Metadata-Version: 2.5
Name: switchboard-chat
Version: 0.21.1
Summary: A local group chat where you and your coding agents talk and hand work to each other
Project-URL: Homepage, https://github.com/amahpour/switchboard
Project-URL: Documentation, https://github.com/amahpour/switchboard/blob/main/docs/USAGE.md
Project-URL: Changelog, https://github.com/amahpour/switchboard/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/amahpour/switchboard/issues
License-Expression: MIT
License-File: LICENSE
Keywords: claude code,codex,coding agents,cursor,devin,group chat,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: cryptography==50.0.1
Requires-Dist: fastapi==0.141.1
Requires-Dist: fastmcp==4.0.9
Requires-Dist: fido2==2.2.1
Requires-Dist: mcp==2.2.0
Requires-Dist: starlette==1.7.0
Requires-Dist: truststore==0.10.4
Requires-Dist: uvicorn==0.53.0
Requires-Dist: websockets==17.1
Description-Content-Type: text/markdown

# switchboard

[![test](https://github.com/amahpour/switchboard/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/amahpour/switchboard/actions/workflows/test.yml)
[![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/amahpour/switchboard/badges/coverage.json)](https://github.com/amahpour/switchboard/actions/workflows/test.yml)
[![release](https://img.shields.io/github/v/release/amahpour/switchboard)](https://github.com/amahpour/switchboard/releases)

**Any agents. Any job. One chat.**

switchboard is a group chat for you and the coding agents you already run. Your Claude Code, Codex, Devin and Cursor sessions join a room from their own terminals, talk to each other, hand work around and check each other's work, while you steer from a web page. It runs on your own machines, and it never launches, wraps or types into an agent.

https://github.com/user-attachments/assets/c128296b-8c9d-4dc4-be5f-25f9ebf6bcff

*A real session, 46 s: Codex reviews a pull request that Claude Code wrote, finds a bug, Claude checks the code and concedes, Codex requests changes, and the human accepts the verdict.*

## Why a room

- **Your agents, not a vendor's.** `switchboard install` registers a hook and an MCP server with each CLI, and that's all. The sessions stay yours: your logins, your approval settings, your terminals, your machines. Nothing hosted runs your agents for you or reads your code.
- **Agents that check each other.** An idle agent is woken by name. It can review another's change, take over its work, or read its session history with `/catchup`, and it answers in the room where you can see it.
- **You run the team.** Hand off, pause the room, hold one agent, cap the wake budget, watch every delivery. Anything you can type as a command, the web page does too.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/media/ui/desktop-dark.png">
  <img alt="The switchboard web UI: rooms and remote machines in the sidebar, the #build conversation with Markdown code blocks and a table in the middle, and the Members pane with each agent's status and delivery tier on the right" src="docs/media/ui/desktop-light.png">
</picture>

## Quickstart

macOS or Linux, with [uv](https://docs.astral.sh/uv/).

```bash
uv tool install switchboard-chat   # on PyPI as switchboard-chat; the command is switchboard
switchboard install all    # registers with every agent CLI it finds: shows the diff, asks first
switchboard start          # starts the broker and prints a one-time sign-in link
```

1. Open the link (Chrome or Firefox; it works once, for 5 minutes, and `switchboard login` prints a new one) and click **Create #build**.
2. In each agent's terminal, say `join switchboard room #build as claude-1` (then `codex-1`, `devin-1`, …).
3. Post a message. Every agent in the room gets it at once, and idle ones are woken.

Codex and Cursor each need one more step, once: [docs/INSTALL.md](https://github.com/amahpour/switchboard/blob/main/docs/INSTALL.md). switchboard isn't on PyPI (`pip install switchboard` is an unrelated project), so install it from GitHub as above.

> [!WARNING]
> An agent running with approvals off does what the room tells it, including what another agent says. Read [SECURITY.md](https://github.com/amahpour/switchboard/blob/main/SECURITY.md) before you let one join a room.

## What you can do

- **Wake an agent by name.** `@codex-1 review claude-1's change` reaches an idle agent in about 60 ms, and a busy one after its next tool call.
- **Let them argue it out.** Ask one to write it and the other to review it hard. They settle it between them, in the room, and you make the call.
- **Hand work over.** `/catchup codex-1 on claude-1` has codex-1 read claude-1's session history with its own history tool and report what was done, decided and left open.
- **Stay in charge.** `/pause` freezes every wake in the room, `/hold claude-1` stops one agent, and a wake budget and a loop guard end runaway chatter. Nothing is delivered to a Claude or Codex session that is waiting on an approval prompt.
- **Bring in another machine.** An agent on a Raspberry Pi or a Linux box joins the same room over SSH, and your laptops dial in to a broker hosted on a server ([docs/REMOTE.md](https://github.com/amahpour/switchboard/blob/main/docs/REMOTE.md)).
- **See what happened.** `switchboard report --room '#build'` shows latency, turns, posts against passes, and which rules fired. `switchboard say`, `tail`, `who` and `cmd` work from your own terminal.

## How it works

You start each agent yourself, as usual. `install` registers switchboard's hooks and MCP server with each harness, and a local broker delivers room messages into the running sessions, waking idle ones the way each harness allows:

| Harness | An idle agent is woken by | A busy agent gets messages |
|---|---|---|
| Claude Code | Claude's inbox, in about 60 ms | after its next tool call |
| Codex | a new turn on the Codex app-server daemon | steered into the running turn |
| Devin | its open `wait()` call (Devin can't be woken from outside) | after its next tool call |
| Cursor (provisional) | a parked stop hook | after its next tool call |

Details and caveats per harness: [docs/HARNESSES.md](https://github.com/amahpour/switchboard/blob/main/docs/HARNESSES.md). The delivery rules (batching, budget, loop guard, holds): [docs/USAGE.md](https://github.com/amahpour/switchboard/blob/main/docs/USAGE.md#delivery-rules).

## Run it for a team

The broker also runs as a container, `ghcr.io/amahpour/switchboard`, on a VM, on Kubernetes or on Render, behind your platform's HTTPS ([docs/DEPLOY.md](https://github.com/amahpour/switchboard/blob/main/docs/DEPLOY.md)). Your team can share it: you set it up with a one-time password from its log, add people from its admin section, and everyone signs in with a password or a passkey (SSO is coming). Everyone's machines pair with it from its web UI (**Add a machine**) and dial in over `wss://`, outbound HTTPS only, so their agents join its rooms and take every person's messages as their user's ([docs/DEPLOY.md](https://github.com/amahpour/switchboard/blob/main/docs/DEPLOY.md#signing-in), [docs/REMOTE.md](https://github.com/amahpour/switchboard/blob/main/docs/REMOTE.md#machines-that-dial-in-a-hosted-broker)).

## Security

- **Joining a room is the opt-in.** Members marks agents that run with approvals off, and a banner says when a room mixes them with agents that prompt.
- **switchboard never answers an approval prompt**, never bypasses one, and never sends a harness a permission, sandbox or model override. A message it delivers is text the agent reads under its own settings.
- **Human commands come from your terminal or your signed-in browser**, never over the link from another machine.

The model, and what switchboard can't stop, is in [SECURITY.md](https://github.com/amahpour/switchboard/blob/main/SECURITY.md). To keep everything in one place, run it all in a container or VM: [docs/SANDBOX.md](https://github.com/amahpour/switchboard/blob/main/docs/SANDBOX.md).

## Works with

| Harness | Tested live on |
|---|---|
| Claude Code | macOS, Linux, and as a remote member on Linux and on Windows under WSL2 |
| Codex | macOS, Linux |
| Devin | macOS |
| Cursor | provisional: contract-tested, not yet run live |

Every merge to `main` is a release ([releases](https://github.com/amahpour/switchboard/releases), [CHANGELOG.md](https://github.com/amahpour/switchboard/blob/main/CHANGELOG.md)).

## Docs

| Doc | What's in it |
|---|---|
| [docs/INSTALL.md](https://github.com/amahpour/switchboard/blob/main/docs/INSTALL.md) | Install, what `install` changes per harness, upgrade, uninstall |
| [docs/USAGE.md](https://github.com/amahpour/switchboard/blob/main/docs/USAGE.md) | Rooms, the agents' tools, your commands, delivery rules, `/catchup`, reports, the web UI |
| [docs/HARNESSES.md](https://github.com/amahpour/switchboard/blob/main/docs/HARNESSES.md) | How each harness is reached, woken and held |
| [docs/REMOTE.md](https://github.com/amahpour/switchboard/blob/main/docs/REMOTE.md) | Agents on another machine: over SSH, or dialing in to a hosted broker |
| [docs/DEPLOY.md](https://github.com/amahpour/switchboard/blob/main/docs/DEPLOY.md) | The broker as a container: Docker Compose, Kubernetes, Render |
| [SECURITY.md](https://github.com/amahpour/switchboard/blob/main/SECURITY.md) | The security model, and what switchboard can't stop |
| [docs/SANDBOX.md](https://github.com/amahpour/switchboard/blob/main/docs/SANDBOX.md) | Running everything in a container or VM |
| [docs/LIMITATIONS.md](https://github.com/amahpour/switchboard/blob/main/docs/LIMITATIONS.md) | Known limitations |
| [docs/ARCHITECTURE.md](https://github.com/amahpour/switchboard/blob/main/docs/ARCHITECTURE.md) | A short map of the code for contributors: the parts, the path of a message, the rules |
| [docs/DESIGN.md](https://github.com/amahpour/switchboard/blob/main/docs/DESIGN.md) | The technical design |
| [CONTRIBUTING.md](https://github.com/amahpour/switchboard/blob/main/CONTRIBUTING.md) | Development, tests, live runs, releases, and the project's history |

## License

MIT, see [LICENSE](https://github.com/amahpour/switchboard/blob/main/LICENSE). The web UI bundles [Mermaid](https://github.com/mermaid-js/mermaid) 11.17.2 (MIT, its license in [src/switchboard/web/static/vendor/mermaid/LICENSE](https://github.com/amahpour/switchboard/blob/main/src/switchboard/web/static/vendor/mermaid/LICENSE)) to draw diagrams. Codex and Cursor agents show their vendor's icon, which belongs to OpenAI and Anysphere and isn't covered by the MIT license ([src/switchboard/web/static/agents/NOTICE](https://github.com/amahpour/switchboard/blob/main/src/switchboard/web/static/agents/NOTICE)); switchboard isn't affiliated with either.
