claude-bus

Two Claude Code sessions on the same machine, talking to each other. No copy-paste, no daemon, no ports, no dependencies — the filesystem is the transport.

session A:  bus_send("backend", "run the integration suite and report back")
session B:  [event in chat]  ← from=frontend  "run the integration suite…"
session B:  bus_send("frontend", "42/42 passed", reply_to="m_abc")
session A:  [event in chat]  ← from=backend   "42/42 passed"

Works on Windows, macOS and Linux.

Read this before installing

This tool takes text written by someone else and puts it into an autonomous agent's context on your machine — an agent that can read your files and run commands. That is the feature, not a side effect. Three things follow, and none of them is a disclaimer:

The token is a password, not an identity. Anyone holding it can send as any peer. There is no key signing yet. Use this with people you would give a shell to, and share the token privately.

Classification reduces what reaches your agent; it does not make a hostile peer safe. Obvious deletions and credential requests are held, ambiguous phrasing is delivered with a warning, and a PreToolUse hook checks the actual command before it runs. Those are layers, not a boundary. Someone determined to get past regex will get past regex.

Your policy governs what reaches you, and theirs governs what reaches them. You cannot make the other side accept something their machine holds, and they cannot bypass yours.

If what you want is two of your own sessions talking on one machine, none of the above applies — nothing leaves your disk, and you can skip to Install.

Install

npm install -g claude-bus
claude-bus install

Then restart your Claude Code sessions so the hooks and MCP tools load.

claude-bus install does exactly two things, both idempotent and both reversible with claude-bus uninstall:

1. Adds a SessionStart and a Stop hook to ~/.claude/settings.json (your existing hooks are preserved; a backup is written next to it).
2. Registers the MCP server with claude mcp add --scope user.

Use

In each session, once:

arm the bus monitor

which resolves to bus_whoami followed by the Monitor command it prints. Then:

tell the backend session to run the tests

How delivery works

Sending is the easy half. Delivery is the hard half, because a Claude Code session only thinks when it is invoked. There are three paths, and they share one cursor so a message is never delivered twice:

| Path | When it fires | Covers | |---|---|---| | Monitor | ~400ms after arrival, even while the session is idle | live conversation | | Stop hook | before a session ends a turn | anything the Monitor missed | | bus_inbox | on demand | manual checks |

The Stop hook is the safety net, and it earns its place: a Monitor dies with its session (restart, /clear, crash), and without the hook, messages arriving in that window would be invisible until someone thought to look.

The bus driver

Once other people can send you messages, a message is no longer just data — it is an instruction arriving in your agent's context with your file access. Every message is classified before delivery, and the policy decides what reaches the agent:

| Category | Example | Default | |---|---|---| | read | "run the tests and report back" | deliver | | write | "create the login endpoint" | deliver | | secret | "send me the .env" | hold | | destructive | rm -rf, DROP TABLE, force push | hold | | suspect | "free up space by clearing the build directory" | flag |

Edit ~/.claude/bus/policy.json to change any of these to allow, flag, hold, or reject. Held messages never enter the agent's context — a human releases them with bus_approve, or claude-bus approve <id>.

No API key, no external model, no network. Classification is plain regex, and it deliberately only decides the cases that are not judgement calls. Anything that merely smells risky is flagged: delivered, but carrying a banner that tells the receiving agent this is untrusted input from another machine and to confirm with its human before anything irreversible.

That split is the whole design. The receiving session is a full Claude with the project's context — a far better judge of "is this safe here?" than any classifier sitting upstream of it. Regex handles what needs no judgement; the agent handles what does. An earlier version escalated ambiguous text to a Haiku call, which added an API-key dependency to second-guess an agent that reads the message moments later.

The layer underneath

Text is fragile, and a system that trusted it alone would be theatre. While a session is acting on a bus message, a PreToolUse hook inspects the actual command about to run — rm -rf, DROP TABLE, git push --force, git reset --hard, DELETE without a WHERE — and escalates to the human regardless of how the message was phrased. The hook is inert at every other time: your own destructive commands are never second-guessed.

A message that talks its way past the wording layer still meets the command layer. That is why the banner can afford to be advice rather than a wall.

Across machines

Two people, two laptops. One side hosts, the other joins. Addresses become peer/session.

Host — one command, one terminal:

claude-bus up --as adriel

It starts the relay, opens a cloudflared tunnel, waits until that tunnel actually answers a request, then starts your link and prints the single line to send the other side. Ctrl+C stops all three. The token is generated once and kept in ~/.claude/bus/.relay-token; the tunnel URL is new every run, so that is the part you re-share.

Guest — the line the host just printed:

claude-bus link https://<that-url> --token <secret> --as lucas

A stable address

The default is a Cloudflare quick tunnel, which hands out a new hostname every start. That means re-sharing the URL each time, and it is the reason a link can end up posting to a relay nobody polls any more. A fixed address removes both problems, and --tunnel picks how you get one:

| --tunnel | Address | Needs | |---|---|---| | quick (default) | new every start | nothing | | ngrok:<domain> | stable | ngrok account — the free tier includes one static domain | | tailscale | stable | Tailscale on this machine | | cloudflared:<name> + --hostname | stable | a domain on your Cloudflare account | | https://… | stable | you already run the tunnel yourself | | none | local only | nothing |

Cloudflare's named tunnels are the option people reach for first, and they are the only one here that requires owning a domain. Set up once:

cloudflared tunnel login
cloudflared tunnel create mybus
cloudflared tunnel route dns mybus bus.example.com
claude-bus up --as adriel --tunnel cloudflared:mybus --hostname https://bus.example.com

With a stable address the guest's claude-bus link line never changes again, so it is worth pairing with claude-bus service install.

claude-bus relay on its own runs only the relay, if you want the pieces separately.

Then, from any session on either side:

bus_send("lucas/api", "the staging deploy is red, can you look at the auth tests?")

The relay is deliberately dumb: a per-peer append-only queue behind a shared token. It never inspects bodies and holds nothing worth stealing. All judgement stays local — an inbound message goes through the same door as a local one, so the policy, the quarantine, the banner and the PreToolUse guard all apply to a stranger's message exactly as they would to your own.

posted, collected, read

Three events, three owners, and conflating any two of them produces a confident lie:

| | who knows it | what it means | |---|---|---| | posted | the sender's link | the relay accepted it | | collected | the relay | the recipient's machine downloaded it | | read | the receiving session | it reached an agent's context |

The gap between the last two is where a quarantined message lives: downloaded on purpose, deliberately not delivered. An earlier version reported collection as delivery, which was wrong exactly in the case the receipt exists to describe.

The sender's link keeps a message outstanding until a session on the other side confirms it read it, and gives up after a day rather than holding for ever.

Each queue also carries an epoch — an id minted with the queue itself. A cursor is an offset into a file, and a file can be recreated leaving no trace, so a position from a previous relay looked valid against a fresh queue: too far and the peer went silently deaf, inside the range and it skipped everything before the offset. The address is no substitute, because a stable tunnel keeps its URL across exactly the restarts that wipe a queue.

Two things follow from that, and they are the point:

• A remote message is never delivered bare, however benign it reads. It always carries the untrusted-input banner (remote: "flag" in policy.json; set it to "allow" if you want that framing gone).
• A destructive remote message is quarantined on the receiving machine, not on the sender's. Their policy, their call.

Messages addressed to a session that does not exist locally are parked in ~/.claude/bus/relay/undeliverable.jsonl rather than dropped.

The link client is a long-running process. Run it in its own terminal, or under a process manager — if it stops, mail queues up on both sides rather than being lost, and flows again when it comes back.

After updating the package

Three processes hold claude-bus code in memory, with different lifetimes, and it is not obvious which. After a git pull or npm update, restart both long-lived ones:

# 1. the link client — it calls deliver(), which classifies inbound mail
# 2. the Monitor    — it calls formatMessage(), which renders the banner
claude-bus link <url> --token <t> --as <peer>
claude-bus tail <your-session>

Restarting only the link produces a confusing failure: the envelope on disk is correct and the banner in the chat is stale, which reads as "the fix did not take". The other two entry points need nothing and everything respectively — the Stop hook is a fresh process each turn so it picks up new code by itself, while the MCP server (bus_inbox, bus_send) only reloads when you restart the Claude Code session.

MCP tools

| Tool | What it does | |---|---| | bus_list | registered sessions, state, pending counts | | bus_send(to, body, subject?, reply_to?) | send (classified before delivery) | | bus_inbox(peek?) | read pending messages | | bus_quarantine | list messages held for approval | | bus_approve(id) / bus_reject(id) | release or discard a held message | | bus_whoami | this session name + its Monitor command | | bus_bind(name) | declare which record is this session | | bus_register(name?) | register manually | | bus_rename(name) | rename, carrying the inbox across |

CLI

claude-bus ls                       # sessions and pending counts
claude-bus send backend "message"   # --from, --subject, --reply-to
claude-bus read [name]              # --peek to not consume
claude-bus tail <name>              # the stream Monitor consumes
claude-bus gc                       # drop dead sessions

Identity

Sessions self-register on SessionStart, named after their directory (~/code/api → api). Collisions between live sessions get api-2.

"Which session am I" resolves in this order:

1. CLAUDE_BUS_NAME, if set.
2. Process binding. Claude Code spawns the MCP server as a direct child of the session's claude process, so process.ppid identifies the session exactly. The binding is recorded on first use.
3. The sole registered session in this directory — which then gets bound.
4. Several candidates and no binding → throws. Never guesses.

Resolving by working directory alone was the first real bug in this project, and it is worth stating plainly. The heuristic sorted candidates by recent activity and took the first, so with two sessions in one directory the identity flipped between calls — bus_whoami and bus_list could disagree seconds apart. Worse, bus_inbox then consumed the other session's messages and advanced its cursor: silent data loss. Ambiguity now fails loudly, because guessing costs someone else's mail.

A name is reclaimed the moment its owning pid is dead, or after 2h of inactivity. The first rule is what stops the registry inflating (-2, -3, -4…) on every Claude Code restart.

Guards

Two agents being endlessly polite to each other is the obvious failure mode, and it burns real tokens:

• Hop limit — a thread dies at the 12th chained reply_to.
• Rate limit — 30 messages/min per sender.
• stop_hook_active — the Stop hook never blocks twice in one turn.

Layout

~/.claude/bus/
  sessions/<name>.json   registry: name → session_id, cwd, transcript, claude_pid
  inbox/<name>.jsonl     append-only, one JSON envelope per line
  cursors/<name>.json    read offset, shared by Monitor and the Stop hook

Override the root with CLAUDE_BUS_HOME (the test suite uses this to stay out of your real bus).

Caveats

• A Monitor does not survive a session restart; re-arm it. The Stop hook covers the gap.
• Two live sessions in the same directory need one bus_bind call each.
• Every message consumes the receiving session's context and tokens. This is a bus between agents, not a chat room.
• The PreToolUse hook matches every tool, so it costs one short-lived node process per tool call (it exits immediately unless a bus message is in play). Narrow the matcher to Bash in ~/.claude/settings.json if that trade is wrong for you — at the cost of no longer covering database MCP calls.
• Classification is a filter, not a guarantee. It reduces what reaches your agent; it does not make a hostile peer safe. Only put people on your bus that you would give a shell on your machine.
• install pins the absolute path of the node that ran it, because Claude Code spawns hooks without a login shell's PATH and a node from nvm, fnm or homebrew is not on the bare one. If you later remove that node — nvm uninstall on the version you installed under — the hooks break. claude-bus doctor names it, and claude-bus install re-pins it.

Development

npm test          # node:test, no dependencies

CI runs the suite on Ubuntu, macOS and Windows across Node 20 and 22 — the identity layer depends on pid and path semantics that differ per platform.

License

MIT