switchboard-relay 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. switchboard_relay-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +21 -0
  2. switchboard_relay-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md +19 -0
  3. switchboard_relay-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +10 -0
  4. switchboard_relay-0.1.0/.github/dependabot.yml +33 -0
  5. switchboard_relay-0.1.0/.github/workflows/ci.yml +53 -0
  6. switchboard_relay-0.1.0/.github/workflows/release.yml +61 -0
  7. switchboard_relay-0.1.0/.gitignore +35 -0
  8. switchboard_relay-0.1.0/.pre-commit-config.yaml +18 -0
  9. switchboard_relay-0.1.0/.release-please-manifest.json +3 -0
  10. switchboard_relay-0.1.0/CHANGELOG.md +27 -0
  11. switchboard_relay-0.1.0/CONTRIBUTING.md +46 -0
  12. switchboard_relay-0.1.0/LICENSE +21 -0
  13. switchboard_relay-0.1.0/PKG-INFO +270 -0
  14. switchboard_relay-0.1.0/README.md +236 -0
  15. switchboard_relay-0.1.0/RELEASING.md +67 -0
  16. switchboard_relay-0.1.0/examples/README.md +54 -0
  17. switchboard_relay-0.1.0/packaging/homebrew/switchboard.rb +48 -0
  18. switchboard_relay-0.1.0/pyproject.toml +110 -0
  19. switchboard_relay-0.1.0/release-please-config.json +13 -0
  20. switchboard_relay-0.1.0/scripts/update-tap.sh +191 -0
  21. switchboard_relay-0.1.0/src/switchboard/__init__.py +12 -0
  22. switchboard_relay-0.1.0/src/switchboard/server.py +640 -0
  23. switchboard_relay-0.1.0/src/switchboard/store.py +493 -0
  24. switchboard_relay-0.1.0/tests/conftest.py +30 -0
  25. switchboard_relay-0.1.0/tests/feature/test_cli.py +177 -0
  26. switchboard_relay-0.1.0/tests/feature/test_server.py +327 -0
  27. switchboard_relay-0.1.0/tests/integration/test_integration.py +263 -0
  28. switchboard_relay-0.1.0/tests/integration/test_stdio_subprocess.py +90 -0
  29. switchboard_relay-0.1.0/tests/unit/test_store.py +538 -0
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: Bug report
3
+ about: Something isn't working as expected
4
+ title: ""
5
+ labels: bug
6
+ ---
7
+
8
+ **What happened**
9
+ A clear description of the bug.
10
+
11
+ **To reproduce**
12
+ Steps or a minimal snippet (which tools/commands, what you sent, what you expected).
13
+
14
+ **Environment**
15
+ - switchboard version (`switchboard --version`):
16
+ - How it's run: stdio (default) / `serve` daemon:
17
+ - OS + Python version:
18
+ - Number of participating sessions:
19
+
20
+ **Logs**
21
+ Any relevant stderr output (switchboard logs to stderr).
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: Feature request
3
+ about: Suggest an idea for switchboard
4
+ title: ""
5
+ labels: enhancement
6
+ ---
7
+
8
+ **Problem**
9
+ What are you trying to do that switchboard doesn't support today?
10
+
11
+ **Proposed solution**
12
+ What would you like to see? (A new tool, an option, a behavior change?)
13
+
14
+ **Alternatives / workarounds**
15
+ Anything you've tried or considered.
16
+
17
+ **Scope check**
18
+ switchboard intentionally stays single‑machine, dependency‑light, and auth‑free (see the
19
+ non‑goals in the README). Does this fit that scope, or is it a bigger direction?
@@ -0,0 +1,10 @@
1
+ ## What & why
2
+
3
+ <!-- What does this change do, and what problem does it solve? -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] `ruff check .` and `ruff format --check .` pass
8
+ - [ ] `pytest` passes with coverage ≥ 95%
9
+ - [ ] Tests added/updated in the right tier (`unit` / `feature` / `integration`)
10
+ - [ ] Docs updated (README / CHANGELOG) if behavior or tools changed
@@ -0,0 +1,33 @@
1
+ version: 2
2
+ updates:
3
+ # Python dependencies declared in pyproject.toml (runtime + test/dev extras).
4
+ # `fix` prefix + scope => PR titles like "fix(deps): bump the python group ...",
5
+ # which release-please treats as a patch bump, so dependency updates flow into
6
+ # the next release. Grouped so all bumps land in a single PR.
7
+ - package-ecosystem: "pip"
8
+ directory: "/"
9
+ schedule:
10
+ interval: "weekly"
11
+ open-pull-requests-limit: 5
12
+ commit-message:
13
+ prefix: "fix"
14
+ include: "scope"
15
+ groups:
16
+ python:
17
+ patterns: ["*"]
18
+
19
+ # GitHub Actions used by the CI and release workflows. These are CI-only and do
20
+ # not change the published package, so they use `chore` (release-please ignores
21
+ # them — no point cutting a PyPI release for a byte-identical artifact). Switch
22
+ # the prefix to `fix` if you want action bumps to trigger releases too.
23
+ - package-ecosystem: "github-actions"
24
+ directory: "/"
25
+ schedule:
26
+ interval: "weekly"
27
+ open-pull-requests-limit: 5
28
+ commit-message:
29
+ prefix: "chore"
30
+ include: "scope"
31
+ groups:
32
+ github-actions:
33
+ patterns: ["*"]
@@ -0,0 +1,53 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ # Cancel superseded runs on the same ref.
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ jobs:
14
+ lint:
15
+ name: Lint & format (ruff)
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - name: ruff check
20
+ uses: astral-sh/ruff-action@v3
21
+ with:
22
+ args: "check --output-format=github"
23
+ - name: ruff format --check
24
+ uses: astral-sh/ruff-action@v3
25
+ with:
26
+ args: "format --check"
27
+
28
+ test:
29
+ name: Test (py${{ matrix.python-version }})
30
+ runs-on: ubuntu-latest
31
+ strategy:
32
+ fail-fast: false
33
+ matrix:
34
+ python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
35
+
36
+ steps:
37
+ - uses: actions/checkout@v4
38
+
39
+ - name: Install uv
40
+ uses: astral-sh/setup-uv@v6
41
+ with:
42
+ python-version: ${{ matrix.python-version }}
43
+
44
+ - name: Create venv and install package with test extras
45
+ run: |
46
+ uv venv
47
+ uv pip install -e '.[test]'
48
+
49
+ - name: Run tests (coverage threshold enforced via pyproject)
50
+ run: .venv/bin/python -m pytest
51
+
52
+ - name: Verify console entry point
53
+ run: .venv/bin/switchboard --version
@@ -0,0 +1,61 @@
1
+ name: Release
2
+
3
+ # release-please watches conventional commits on main and maintains a release
4
+ # PR that bumps the version + CHANGELOG. Merging that PR creates the tag and
5
+ # GitHub Release; the publish job then builds and pushes to PyPI.
6
+ on:
7
+ push:
8
+ branches: [main]
9
+
10
+ permissions: {}
11
+
12
+ jobs:
13
+ release-please:
14
+ name: Release Please
15
+ runs-on: ubuntu-latest
16
+ permissions:
17
+ contents: write
18
+ pull-requests: write
19
+ outputs:
20
+ release_created: ${{ steps.release.outputs.release_created }}
21
+ tag_name: ${{ steps.release.outputs.tag_name }}
22
+ steps:
23
+ - uses: googleapis/release-please-action@v4
24
+ id: release
25
+ with:
26
+ token: ${{ github.token }}
27
+
28
+ publish:
29
+ name: Publish to PyPI (Trusted Publishing / OIDC)
30
+ needs: release-please
31
+ if: ${{ needs.release-please.outputs.release_created == 'true' }}
32
+ runs-on: ubuntu-latest
33
+ environment:
34
+ name: pypi
35
+ url: https://pypi.org/p/switchboard-relay
36
+ permissions:
37
+ id-token: write # MANDATORY for OIDC trusted publishing; no API tokens.
38
+ contents: write # to attach built dists to the GitHub Release
39
+ steps:
40
+ - uses: actions/checkout@v4
41
+
42
+ - name: Install uv
43
+ uses: astral-sh/setup-uv@v6
44
+ with:
45
+ python-version: "3.13" # pin the build interpreter for reproducible releases
46
+
47
+ - name: Build sdist and wheel
48
+ run: uv build
49
+
50
+ - name: Publish to PyPI
51
+ uses: pypa/gh-action-pypi-publish@release/v1
52
+
53
+ - name: Attach built dists to the release
54
+ env:
55
+ GH_TOKEN: ${{ github.token }}
56
+ run: >
57
+ gh release upload "${{ needs.release-please.outputs.tag_name }}"
58
+ dist/* --repo "${{ github.repository }}"
59
+ # Homebrew: after a release, run `scripts/update-tap.sh <version>` on macOS.
60
+ # It bumps the formula AND regenerates the pinned Python resource stanzas
61
+ # (which no CI action can do in a sandbox). See RELEASING.md.
@@ -0,0 +1,35 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ build/
7
+ dist/
8
+ *.egg
9
+
10
+ # Virtual environments
11
+ .venv/
12
+ venv/
13
+ env/
14
+
15
+ # uv
16
+ uv.lock
17
+
18
+ # Test / coverage
19
+ .pytest_cache/
20
+ .coverage
21
+ htmlcov/
22
+ .tox/
23
+ .mypy_cache/
24
+ .ruff_cache/
25
+
26
+ # SQLite databases (switchboard's runtime state)
27
+ *.db
28
+ *.db-wal
29
+ *.db-shm
30
+
31
+ # Editor / OS
32
+ .DS_Store
33
+ *.swp
34
+ .idea/
35
+ .vscode/
@@ -0,0 +1,18 @@
1
+ # Run `pre-commit install` once to enable these on every commit.
2
+ # Update hook versions with `pre-commit autoupdate`.
3
+ repos:
4
+ - repo: https://github.com/astral-sh/ruff-pre-commit
5
+ rev: v0.15.1
6
+ hooks:
7
+ - id: ruff
8
+ args: [--fix]
9
+ - id: ruff-format
10
+
11
+ - repo: https://github.com/pre-commit/pre-commit-hooks
12
+ rev: v5.0.0
13
+ hooks:
14
+ - id: trailing-whitespace
15
+ - id: end-of-file-fixer
16
+ - id: check-yaml
17
+ - id: check-toml
18
+ - id: check-added-large-files
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.1.0"
3
+ }
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format is based on
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.1.0](https://github.com/mgd43b/switchboard-relay/releases/tag/v0.1.0) (2026-07-15)
8
+
9
+ Initial release.
10
+
11
+ ### Added
12
+
13
+ - Local MCP server giving independent Claude Code sessions a shared, durable messaging
14
+ channel over SQLite (`~/.claude/switchboard.db`, override `$SWITCHBOARD_DB`).
15
+ - Tools: `register`, `participants`, `send`, `inbox`, `wait`, `ask` (one‑call
16
+ request/response), `broadcast`, and `unregister`.
17
+ - Durable mailboxes with exactly‑once drain; a participant registry with TTL liveness;
18
+ name‑ and role‑based addressing.
19
+ - stdio transport (default, one process per session, shared via SQLite) and an experimental
20
+ streamable‑HTTP daemon (`switchboard serve`) with opt‑in Channels push (`SWITCHBOARD_PUSH`).
21
+ - Human‑facing inspection CLI: `switchboard participants`, `switchboard tail [--follow]`, and
22
+ `switchboard prune` (delete old dead‑letter messages and expired participants).
23
+ - Environment configuration: `SWITCHBOARD_DB`, `SWITCHBOARD_TTL`, `SWITCHBOARD_NAME`,
24
+ `SWITCHBOARD_ROLE`, `SWITCHBOARD_PUSH`, `SWITCHBOARD_HOST`, `SWITCHBOARD_PORT`.
25
+ - Tooling: ruff lint + format, pytest with an enforced coverage gate (100% today), CI on
26
+ Python 3.10–3.14, PyPI trusted‑publishing release workflow, and a Homebrew tap formula.
27
+
@@ -0,0 +1,46 @@
1
+ # Contributing to switchboard
2
+
3
+ Thanks for your interest! switchboard aims to stay small, dependency‑light, and well‑tested.
4
+
5
+ ## Setup
6
+
7
+ ```bash
8
+ uv venv && uv pip install -e '.[dev]'
9
+ pre-commit install # optional: run ruff automatically on commit
10
+ ```
11
+
12
+ ## Before you push
13
+
14
+ The CI gate is: **ruff (lint + format) clean**, **all tests pass**, and **coverage ≥ 95%**.
15
+ Run the same checks locally:
16
+
17
+ ```bash
18
+ uv run ruff check .
19
+ uv run ruff format --check .
20
+ uv run pytest # coverage gate enforced via pyproject
21
+ ```
22
+
23
+ ## Tests
24
+
25
+ Tests live in three tiers (see [tests/conftest.py](tests/conftest.py)); pick the right one for
26
+ your change and keep coverage up:
27
+
28
+ - `tests/unit/` — pure logic (the SQLite store), time injected, no I/O beyond a temp DB.
29
+ - `tests/feature/` — tool/feature behavior through the `Switchboard` layer with a fake Context.
30
+ - `tests/integration/` — the tools over a real MCP transport (in‑memory and real stdio subprocesses).
31
+
32
+ Run one tier with `uv run pytest -m unit` (or `feature` / `integration`).
33
+
34
+ ## Design guardrails
35
+
36
+ - **`store.py` stays pure**: no clocks, no sleeps, no MCP imports. Time is passed in as `now`;
37
+ TTL is a parameter. This is what keeps it deterministically testable.
38
+ - **Durability is the source of truth**: every message is a SQLite row delivered exactly once.
39
+ Push (daemon mode) is only ever a best‑effort *nudge* on top — it must never be required for
40
+ correctness.
41
+ - **Multi‑process safety**: many independent processes share one DB file (WAL). Writes that must
42
+ be atomic use `BEGIN IMMEDIATE` or a single `ON CONFLICT` statement.
43
+
44
+ ## Releasing
45
+
46
+ Maintainers: see [RELEASING.md](RELEASING.md).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mgd43b
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: switchboard-relay
3
+ Version: 0.1.0
4
+ Summary: A local MCP server that gives independent Claude Code sessions a shared, durable messaging channel.
5
+ Project-URL: Homepage, https://github.com/mgd43b/switchboard-relay
6
+ Project-URL: Repository, https://github.com/mgd43b/switchboard-relay
7
+ Project-URL: Issues, https://github.com/mgd43b/switchboard-relay/issues
8
+ Author: mgd43b
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,claude,claude-code,inter-session,mcp,messaging,model-context-protocol
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Software Development :: Libraries
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: mcp<2,>=1.9
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
26
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
27
+ Requires-Dist: pytest>=7.4; extra == 'dev'
28
+ Requires-Dist: ruff>=0.9; extra == 'dev'
29
+ Provides-Extra: test
30
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
31
+ Requires-Dist: pytest-cov>=5.0; extra == 'test'
32
+ Requires-Dist: pytest>=7.4; extra == 'test'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # switchboard
36
+
37
+ [![CI](https://github.com/mgd43b/switchboard-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd43b/switchboard-relay/actions/workflows/ci.yml)
38
+ [![PyPI](https://img.shields.io/pypi/v/switchboard-relay)](https://pypi.org/project/switchboard-relay/)
39
+ [![Python](https://img.shields.io/pypi/pyversions/switchboard-relay)](https://pypi.org/project/switchboard-relay/)
40
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
41
+
42
+ **A local MCP server that gives independent Claude Code sessions a shared, durable messaging channel.**
43
+
44
+ Claude Code's built‑in session channel is injected only by the desktop/GUI app, so
45
+ terminal CLI sessions can't use it. A *config‑level* MCP server, by contrast, loads on
46
+ **every** surface — terminal CLI, desktop, and IDE — and its tools are allowlistable. `switchboard`
47
+ is a tiny such server: it routes named messages between any set of Claude Code sessions on
48
+ one machine, backed by SQLite so mailboxes survive restarts.
49
+
50
+ ```
51
+ worker:feature-x ──send("lead", "what's the API for X?")──▶ ┌───────────┐
52
+ │switchboard│ (SQLite mailbox)
53
+ lead ◀──inbox() / wait()── "what's the API for X?" ──────────└───────────┘
54
+ lead ──send("worker:feature-x", "use client.foo()")─────────▶ …delivered to worker's inbox
55
+ ```
56
+
57
+ The canonical pattern: a long‑running **lead** session that short‑lived **worker** sessions ask
58
+ questions of — no copy‑pasting between windows. But `switchboard` just routes named messages, so
59
+ any addressing scheme works.
60
+
61
+ ---
62
+
63
+ ## Install
64
+
65
+ `switchboard` is a standard Python package (Python ≥ 3.10). Install it so the `switchboard`
66
+ command is on your `PATH`:
67
+
68
+ ```bash
69
+ # Homebrew (macOS/Linux)
70
+ brew install mgd43b/taps/switchboard
71
+
72
+ # with uv (recommended)
73
+ uv tool install switchboard-relay
74
+
75
+ # or pipx
76
+ pipx install switchboard-relay
77
+
78
+ # or from a checkout of this repo
79
+ uv tool install .
80
+ ```
81
+
82
+ Then register it with Claude Code at **user scope** (loads in every project, on every surface):
83
+
84
+ ```bash
85
+ claude mcp add --scope user -- switchboard
86
+ ```
87
+
88
+ That's it. Open any Claude Code session (terminal or desktop) and the eight `switchboard`
89
+ tools are available. Verify with `claude mcp list`.
90
+
91
+ > **No install step?** If you'd rather not install anything, point Claude Code at `uvx`:
92
+ > ```bash
93
+ > claude mcp add --scope user -- uvx switchboard-relay
94
+ > ```
95
+
96
+ ### Make the tools run without a confirmation prompt (allowlist)
97
+
98
+ MCP tools are named `mcp__switchboard__<tool>`. To let them fire without a per‑call prompt,
99
+ add them to `permissions.allow` in your user settings (`~/.claude/settings.json`):
100
+
101
+ ```json
102
+ {
103
+ "permissions": {
104
+ "allow": [
105
+ "mcp__switchboard__register",
106
+ "mcp__switchboard__participants",
107
+ "mcp__switchboard__send",
108
+ "mcp__switchboard__inbox",
109
+ "mcp__switchboard__wait",
110
+ "mcp__switchboard__ask",
111
+ "mcp__switchboard__broadcast",
112
+ "mcp__switchboard__unregister"
113
+ ]
114
+ }
115
+ }
116
+ ```
117
+
118
+ Or allowlist the whole server with a single entry: `"mcp__switchboard"`.
119
+
120
+ ---
121
+
122
+ ## Tools
123
+
124
+ | Tool | Signature | What it does |
125
+ |------|-----------|--------------|
126
+ | `register` | `register(name, role?)` | Claim an address for this session (e.g. `"lead"`, `"worker:feature-x"`). `role` is an optional shared address (e.g. `"worker"`). Re‑call to heartbeat or change role. Returns the live participants. |
127
+ | `participants` | `participants()` | List sessions seen within the TTL window: `name`, `role`, `idle_seconds`. |
128
+ | `send` | `send(to, body, reply_to?)` | Append a message to `to`'s durable inbox. `to` matches a participant **name or role**. `reply_to` threads a reply to a message id. Returns the new message `id`. |
129
+ | `inbox` | `inbox(peek?, since?)` | Read messages addressed to you. **Drains** by default (each message delivered once); `peek=true` reads without removing; `since=<id>` returns only messages newer than that id. |
130
+ | `wait` | `wait(timeout_s?)` | Block up to `timeout_s` seconds (default 30, max 3600) until a message arrives, then drain and return it. Returns `timed_out: true` on timeout. |
131
+ | `ask` | `ask(to, body, timeout_s?)` | **Request/response in one call:** send `body` to `to`, then block until a reply threaded to it comes back (`reply_to` = the returned `question_id`). Leaves other inbox messages untouched; returns `timed_out: true` if no reply in time. |
132
+ | `broadcast` | `broadcast(body)` | Send `body` to every currently‑live participant except yourself. Returns the per‑recipient message ids. |
133
+ | `unregister` | `unregister()` | Leave the switchboard (drop out of `participants()`). Your mailbox is preserved for if you return. |
134
+
135
+ Messages are **durable**: a message sent to a name that hasn't registered yet simply waits in
136
+ that mailbox until it's read. Addressing by `role` fans a message out to whichever participant
137
+ reads with that role — for reliable one‑to‑one delivery, use unique names.
138
+
139
+ ---
140
+
141
+ ## The lead / worker pattern
142
+
143
+ **In your long‑running lead session** (e.g. a coordinator you keep open in a terminal):
144
+
145
+ ```
146
+ Register me on switchboard as "lead", then keep calling wait() in a loop:
147
+ whenever a message arrives, answer the question by sending a reply back to
148
+ its sender (use reply_to), then wait() again.
149
+ ```
150
+
151
+ Claude will `register(name="lead")` and then park in `wait()`. Pair it with the
152
+ [`/loop`](https://code.claude.com/docs/en/slash-commands) skill to keep it going hands‑free:
153
+
154
+ ```
155
+ /loop wait for a switchboard message, answer it, and reply to the sender
156
+ ```
157
+
158
+ **In each worker session:**
159
+
160
+ ```
161
+ Register me on switchboard as "worker:auth" with role "worker", then use ask()
162
+ to ask the lead how our auth middleware refreshes tokens.
163
+ ```
164
+
165
+ The worker calls `ask("lead", "…")` — one call that sends the question and blocks for the
166
+ answer. The lead's loop picks it up, replies with `reply_to` set, and the worker's `ask()`
167
+ returns the reply. No window‑switching, no manual `wait()`.
168
+
169
+ > **Tip:** launch a worker pre‑addressed with environment variables so it doesn't even need an
170
+ > explicit `register` call — set `SWITCHBOARD_NAME=worker:auth` and `SWITCHBOARD_ROLE=worker`
171
+ > in that session's MCP server env.
172
+
173
+ ### Peek at the traffic from your terminal
174
+
175
+ `switchboard` doubles as a small inspection CLI over the same database — handy for debugging
176
+ who's connected and what's queued, without an MCP client:
177
+
178
+ ```bash
179
+ switchboard participants # live participants (name, role, idle time)
180
+ switchboard tail # queued (undelivered) messages
181
+ switchboard tail --follow # …and keep watching
182
+ switchboard prune # delete old dead-letter messages + expired participants
183
+ ```
184
+
185
+ Example recipes for the lead loop and workers live in [`examples/`](examples/).
186
+
187
+ ---
188
+
189
+ ## Configuration
190
+
191
+ All optional. Set as environment variables (e.g. via `claude mcp add --env KEY=value`):
192
+
193
+ | Variable | Default | Meaning |
194
+ |----------|---------|---------|
195
+ | `SWITCHBOARD_DB` | `~/.claude/switchboard.db` | SQLite database path (shared by all sessions). |
196
+ | `SWITCHBOARD_TTL` | `300` | Seconds of inactivity before a participant drops out of `participants()`. |
197
+ | `SWITCHBOARD_NAME` | — | Auto‑register this session under this address (skips an explicit `register`). |
198
+ | `SWITCHBOARD_ROLE` | — | Role to pair with `SWITCHBOARD_NAME`. |
199
+ | `SWITCHBOARD_PUSH` | `0` | Opt into experimental push (see below). Only meaningful in daemon mode. |
200
+
201
+ Example with a custom TTL:
202
+
203
+ ```bash
204
+ claude mcp add --scope user --env SWITCHBOARD_TTL=600 -- switchboard
205
+ ```
206
+
207
+ ---
208
+
209
+ ## How it works (and its one limitation)
210
+
211
+ Each Claude Code session spawns its **own** `switchboard` process (stdio transport). Those
212
+ processes don't talk to each other directly — they share state through the SQLite database, which
213
+ gives you durability and cross‑session delivery for free. `wait()` long‑polls that database.
214
+
215
+ This design has one consequence worth knowing: **switchboard cannot wake a session that isn't
216
+ already doing something.** A recipient learns about a message by calling `inbox()` or `wait()`
217
+ (on its next turn, or while parked in a `/loop`). Nothing can push into a fully idle or closed
218
+ session — that's a property of how Claude Code sessions work, not a switchboard limitation.
219
+
220
+ ### Experimental: push via Channels (daemon mode)
221
+
222
+ There's an opt‑in path for lower‑latency delivery into a session that's *currently open*. Run
223
+ switchboard as a single shared HTTP daemon instead of per‑session stdio:
224
+
225
+ ```bash
226
+ # start the daemon (push is a daemon-side opt-in)
227
+ SWITCHBOARD_PUSH=1 switchboard serve --host 127.0.0.1 --port 8765
228
+ # point every session at it instead of the stdio server
229
+ claude mcp add --scope user --transport http switchboard http://127.0.0.1:8765/mcp
230
+ ```
231
+
232
+ In daemon mode all sessions connect to one process, so `send()` can emit a Claude Code
233
+ [Channels](https://code.claude.com/docs/en/channels) notification (`notifications/claude/channel`)
234
+ to a connected recipient. The notification is a **nudge to check your inbox**, not the message body —
235
+ the durable SQLite row stays the single source of truth, so a recipient still `inbox()`‑drains the
236
+ message exactly once (and a role‑addressed nudge reaches every connected member, but only one drains
237
+ the row). This is **experimental**: it requires the recipient session to be running and subscribed to
238
+ switchboard as a channel (Claude Code's channels feature is itself a research preview and may require
239
+ extra flags), and it never replaces durable delivery. Leave it off (the default) and everything works
240
+ via polling.
241
+
242
+ ---
243
+
244
+ ## Development
245
+
246
+ ```bash
247
+ uv venv && uv pip install -e '.[dev]'
248
+ uv run pytest # runs all tiers; coverage gate is enforced (fail-under 95%)
249
+ uv run pytest -m unit # or a single tier: unit | feature | integration
250
+ uv run ruff check . # lint
251
+ uv run ruff format . # format
252
+ ```
253
+
254
+ - `src/switchboard/store.py` — the durable SQLite store (registry + mailboxes). Pure and clock‑free.
255
+ - `src/switchboard/server.py` — the FastMCP server: identity binding, the eight tools, the `wait()` poll loop, and best‑effort push.
256
+ - `tests/` is split into three tiers:
257
+ - `tests/unit/` — the SQLite store in isolation.
258
+ - `tests/feature/` — tool/feature behavior through the server layer (identity, push, roles, the CLI) with a fake Context.
259
+ - `tests/integration/` — the tools driven over a real MCP transport, including **two real stdio subprocesses** sharing one database.
260
+
261
+ CI (Python 3.10–3.14) runs ruff + the full suite with the coverage gate on every push and PR.
262
+ Releases and Homebrew packaging are documented in [RELEASING.md](RELEASING.md).
263
+
264
+ ## Non‑goals (v1)
265
+
266
+ Single machine only (no cross‑machine bus), no auth/encryption, no transcript search, no GUI.
267
+
268
+ ## License
269
+
270
+ [MIT](LICENSE)