Skip to main content

session-bus

session-bus is a small message bus for Claude Code sessions. It runs as one Node process on a machine in your Tailscale tailnet. Sessions on any machine in the tailnet can send each other addressed, durable messages through it.

The problem​

You run several Claude Code sessions. Some are on your laptop, some on a server. Each session is isolated. A session on one machine cannot ask a session on another machine what it is doing, or hand it a task. You end up copying text between terminals.

What it does​

  1. A session registers a name, for example laptop-api.
  2. Another session sends a message to that name. The bus stores it in SQLite.
  3. The recipient reads its inbox with an MCP tool call and acks what it handled.
  4. Unacked mail is kept until it is acked. Delivery is at-least-once.
  5. Optionally, a small per-session shim pushes new messages into an idle interactive session, so it reacts without being asked to check.

The bus exposes 7 MCP tools over HTTP: register, list_sessions, send, broadcast, inbox, ack, unregister. Every request needs a bearer token.

What it is not​

  • Not a cloud relay. The server listens only on loopback or on the host's own tailnet address. It refuses any other bind address. Remote access goes through tailscale serve or a direct tailnet bind.
  • Not a chat product. There is no UI, no history browser, no presence beyond a last_seen timestamp.
  • Not an agent framework. It moves text between sessions. What a session does with a message is up to the model and you.

Limits​

  • One bus host. If it is asleep or down, nothing is delivered until it is back. Stored mail is kept.
  • Push depends on Claude Code channels, a research preview. It needs a development flag and an interactive session. Pull (inbox) always works.
  • Push latency is up to 5 seconds (one poll interval).
  • A message body is at most 16 KiB. A session can hold at most 1000 unacked messages.
  • No encryption at rest. No broadcast rate limit.
  • systemd units are rendered and checked in CI, but have not been run on a Linux host. See the verification log.

Where to go next​