Inter-agent message bus for local Claude Code sessions
Project description
Spanreed
An inter-agent message bus for local Claude Code sessions. Run one Claude session per repo; let them coordinate.
Status: alpha. The architecture and primitives are validated (see
docs/findings.md) and a working implementation is in place — pending end-to-end manual smoke test in real Claude Code. Not yet published to PyPI or the official marketplace.
Named after the spanreed: a paired magical writing tool from the Stormlight Archive that transmits text across vast distances. One side writes, the other side reads.
Install
Once published (not yet on PyPI):
uv tool install spanreed-bus
claude /plugin marketplace add Monkopedia/spanreed
claude /plugin install spanreed@spanreed
For now, from a local clone:
git clone git@github.com:Monkopedia/spanreed.git
cd spanreed
uv tool install --editable .
claude /plugin install $(pwd)/plugins/spanreed --scope user
The MCP server (spanreed-mcp) and CLI (spanreed) need to be on $PATH for the plugin to find them — uv tool install handles this.
Quickstart
Open two terminals, each in a different repo:
# Terminal A
cd ~/projects/repo-a && claude
# Terminal B
cd ~/projects/repo-b && claude
In terminal A, ask Claude to talk to the other session:
Ask agent at repo-b what version of Node it's using.
Claude in repo-A discovers the peer, sends the question, the peer answers, the answer comes back. The conversation is visible in both transcripts.
How it works
Two layers on Claude Code primitives:
- MCP server (
spanreed-mcp, per-session) exposes the bus API as typed tools: register, send, recv, list,wait_for_replywith timeout. - Plugin (auto-loaded) wires up a SessionStart hook for bus context, a Monitor for inbound wakeups, and points Claude at the MCP server.
State lives under ~/.claude/spanreed/ (registry + per-agent inboxes + per-session cursors). No central daemon — each session's MCP server is local and coordinates through shared files.
Read the full design in docs/architecture.md. Wire-format spec in docs/protocol.md.
Update
uv tool upgrade spanreed-bus
claude /plugin update spanreed@spanreed
Development
See docs/development.md for environment setup, running tests, and contribution conventions. The CLAUDE.md at the root captures the discipline rules — Claude sessions working on this repo should read it.
License
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file spanreed_bus-0.0.1.tar.gz.
File metadata
- Download URL: spanreed_bus-0.0.1.tar.gz
- Upload date:
- Size: 80.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6ae0e1f46c44ba08238e14c2bf9c235960af245f2d763290544c5ad1b502e375
|
|
| MD5 |
2463aa57402d77f7861781e305165739
|
|
| BLAKE2b-256 |
e681dc5062bc8bb1865fa1b8d8613197e5ee3c163353d27298c51b5c35fd8891
|
File details
Details for the file spanreed_bus-0.0.1-py3-none-any.whl.
File metadata
- Download URL: spanreed_bus-0.0.1-py3-none-any.whl
- Upload date:
- Size: 19.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4295198a6305c1983d6704d5e8dae1a2fa509d35368737c4f6c16b8a2dfa23bf
|
|
| MD5 |
ee30e7beaef6911a2e1b7c89c279ce40
|
|
| BLAKE2b-256 |
a27a54bca3fb030f1f3a7f53b7ab3bafcf8df74c2807f14a27e97ef15d10b482
|
