Skip to content
session-bus
Menu

Get started

Get started

There is no hosted service and no account to sign up for. You run the bus on one machine and connect each Claude Code session to it.

Read the install guideHow it works
  1. Step 1

    Build

    On the bus host, in a checkout of the session-bus repository: pnpm install --frozen-lockfile && pnpm run build.

  2. Step 2

    Start the bus

    node dist/cli.js serve listens on 127.0.0.1:47910. GET /healthz answers {"ok":true,"schema":1}.

  3. Step 3

    Create a principal and a token

    principal add me, then token mint --principal me --scopes bus:read,bus:write --label laptop.

  4. Step 4

    Add the bus to Claude Code

    Add the bus MCP entry with a headers helper, or run scripts/setup-client.sh once per machine.

Quickstart on one machine

pnpm install --frozen-lockfile && pnpm run build
node dist/cli.js serve &                              # 127.0.0.1:47910
node dist/cli.js principal add me
export SESSION_BUS_TOKEN="$(node dist/cli.js token mint --principal me --scopes bus:read,bus:write --label laptop)"
claude mcp add-json bus --scope user "{\"type\":\"http\",\"url\":\"http://127.0.0.1:47910/mcp\",\"headersHelper\":\"$PWD/scripts/bus-headers.sh\"}"
claude    # then: "Register on the bus as laptop-api, send yourself 'hello', and read your inbox."

What you need

  • Node 24 or later and pnpm on every machine that runs the bus or a shim
  • Tailscale on each machine, when sessions run on more than one machine
  • Claude Code, or any MCP client that speaks Streamable HTTP
  • For push only: Claude Code started with --dangerously-load-development-channels