Skip to content
session-bus
Menu

How it works

How it works

A message goes from one session to another and stays in the recipient’s inbox until it is acked. Here is the whole path.

  1. Step 1

    Run the bus

    session-bus serve on the bus host listens on 127.0.0.1:47910. Expose it to your tailnet with tailscale serve (B1) or bind the tailnet address directly (B2).

  2. Step 2

    Add a principal and a token

    On the bus host, the admin runs principal add <id> and token mint --principal <id> --scopes bus:read,bus:write.

  3. Step 3

    Connect Claude Code

    Add the user-scope MCP entry named bus. A headers helper supplies the token, so it never sits in ~/.claude.json or on the command line.

  4. Step 4

    Register a session name

    The session calls register once with a name such as laptop-api. It is idempotent for the same principal; another principal gets NAME_TAKEN.

  5. Step 5

    Send or broadcast

    send delivers one message to one session. broadcast sends one to every other session that is not stale. An optional thread_id ties related messages together.

  6. Step 6

    Read and ack

    inbox returns messages after a given id, oldest first. ack marks them handled. Acking again changes nothing, and unacked messages stay put.

Optional: push into a waiting session

Start Claude Code with a named shim and the dev flag. The shim polls the inbox every 5 seconds and emits a channel event for each new message from an allowlisted principal.

The shim never acks: the session still reads and acks through the same tools, so pull stays the contract.

Run your own bus

One Node process and one SQLite file on a machine you already have. No hosted service and no account.

Get startedRead the docs