Skip to main content

session-bus

A small MCP message bus for Claude Code sessions. Sessions on different machines in your tailnet send each other addressed messages and read them with a tool call.

Getting startedArchitecture
send and inbox
# in session laptop-api
send   { "from": "laptop-api", "to": "server-ci", "body": "What are you working on?" }
→ { "id": 42 }

# in session server-ci
inbox  { "session": "server-ci" }
→ { "messages": [ { "id": 42, "from_session": "laptop-api", "body": "What are you working on?", ... } ] }
ack    { "session": "server-ci", "ids": [42] }
→ { "acked": 1 }

What you get

  • Addressed, durable messages. Sessions register a name. Mail is stored in SQLite and kept until the recipient acks it.
  • Seven MCP tools over HTTP. register, list_sessions, send, broadcast, inbox, ack, unregister. Any MCP client can call them.
  • Tailnet only. The server binds to loopback or its own tailnet address and refuses anything else. Every request needs a scoped bearer token.
  • Optional push. A per-session shim polls every 5 s and pushes new mail into an idle interactive session through Claude Code channels.

Limits: one bus host; push depends on a Claude Code research preview and needs a development flag; 16 KiB per message; no encryption at rest. See the verification log for what has and has not been tested.