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.
- switchboard_relay-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +21 -0
- switchboard_relay-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md +19 -0
- switchboard_relay-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +10 -0
- switchboard_relay-0.1.0/.github/dependabot.yml +33 -0
- switchboard_relay-0.1.0/.github/workflows/ci.yml +53 -0
- switchboard_relay-0.1.0/.github/workflows/release.yml +61 -0
- switchboard_relay-0.1.0/.gitignore +35 -0
- switchboard_relay-0.1.0/.pre-commit-config.yaml +18 -0
- switchboard_relay-0.1.0/.release-please-manifest.json +3 -0
- switchboard_relay-0.1.0/CHANGELOG.md +27 -0
- switchboard_relay-0.1.0/CONTRIBUTING.md +46 -0
- switchboard_relay-0.1.0/LICENSE +21 -0
- switchboard_relay-0.1.0/PKG-INFO +270 -0
- switchboard_relay-0.1.0/README.md +236 -0
- switchboard_relay-0.1.0/RELEASING.md +67 -0
- switchboard_relay-0.1.0/examples/README.md +54 -0
- switchboard_relay-0.1.0/packaging/homebrew/switchboard.rb +48 -0
- switchboard_relay-0.1.0/pyproject.toml +110 -0
- switchboard_relay-0.1.0/release-please-config.json +13 -0
- switchboard_relay-0.1.0/scripts/update-tap.sh +191 -0
- switchboard_relay-0.1.0/src/switchboard/__init__.py +12 -0
- switchboard_relay-0.1.0/src/switchboard/server.py +640 -0
- switchboard_relay-0.1.0/src/switchboard/store.py +493 -0
- switchboard_relay-0.1.0/tests/conftest.py +30 -0
- switchboard_relay-0.1.0/tests/feature/test_cli.py +177 -0
- switchboard_relay-0.1.0/tests/feature/test_server.py +327 -0
- switchboard_relay-0.1.0/tests/integration/test_integration.py +263 -0
- switchboard_relay-0.1.0/tests/integration/test_stdio_subprocess.py +90 -0
- 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,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
|
+
[](https://github.com/mgd43b/switchboard-relay/actions/workflows/ci.yml)
|
|
38
|
+
[](https://pypi.org/project/switchboard-relay/)
|
|
39
|
+
[](https://pypi.org/project/switchboard-relay/)
|
|
40
|
+
[](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)
|