Session bus
Two or more Claude Code sessions in one folder have no IPC. This gives them one: each session owns a single-writer, append-only markdown outbox, and a watcher turns the other sessions' appends into notifications.
Setup — identical in every session
Run these in order. The commands are byte-identical in every session — the slot is negotiated on disk, so nobody has to be told whether they are A or B.
mkdir -p bus && cp "${CLAUDE_SKILL_DIR}/scripts/claim.sh" "${CLAUDE_SKILL_DIR}/scripts/watch.sh" "${CLAUDE_SKILL_DIR}/scripts/post.sh" bus/
sh bus/claim.sh
claim.sh prints your slot letter (A, B, …). That letter is your identity;
it is re-derived from disk, so it survives compaction. Re-running is safe — it
returns the same letter, never a second one.
Then copy references/protocol.md to bus/README.md so
a session without this skill installed can still follow the rules.
Arm the watcher with the Monitor tool — persistent: true is required, or it
dies after 5 minutes and its silence looks exactly like a quiet channel:
Monitor(command: "sh bus/watch.sh <YOUR-LETTER>", persistent: true,
description: "session bus: peers' outboxes")
Post a hello, then read every peer's bus/<slot>/out.md in full.
The rules
- Write only your own outbox, and only through
post.sh:sh bus/post.sh <your-letter> "<subject>" "<body>". Never use Write/Edit on a bus file — Write rewrites the whole file, which truncates it briefly and reads all history into context. Never touch a peer's file, not even to fix a typo. Single-writer is what makes append-only safe. - Put the payload in the subject. The subject is what reaches peers as a
notification; bodies are read by opening the file. Bodies may contain markdown
freely —
post.shneutralizes headings in them, so a##in a body cannot be replayed to peers as a message you did not send. This only holds if you post throughpost.sh. - Anything that needs an answer must start its subject with
@<slot>, naming exactly one peer. Unaddressed asks with several peers get answered by everyone or by no one. Status and findings stay unaddressed. - Prefix genuinely blocking asks with
BLOCKING:— and say them to the human out loud too. - Re-read peers' outboxes at the start of every turn and after any long job. The watcher accelerates polling; it does not replace it. This is the backstop for your own watcher dying, which you cannot detect from inside.
Confirm the channel works before trusting it
Do not assume the bus is live because the watcher started. Post a hello, and have the peer report back what it saw. Until a message has made a round trip, treat the channel as unproven and tell the human anything time-critical directly.
What this does not do
- It cannot tell you a peer is alive. The heartbeat says only "that peer's watcher is ticking." A session that never armed a watcher is byte-identical to a dead one. The watcher's messages are worded to say only what was observed — keep it that way; never report a peer as dead.
- It cannot deliver to a session that isn't listening. The human is the only guaranteed-alive actor and the only wake path.
- Speed is not authority. Two agents agreeing quickly is exactly where "who approved this?" goes wrong. Spending money, pushing code, deleting things, and contacting people still route through the human.
Reference
- references/protocol.md — the protocol, copied into
the project as
bus/README.md. - references/design-notes.md — why the scripts are
written the way they are: which primitives are actually atomic, why counting
uses
grep -c ''and notwc -l, what was rejected. Read before changing a script.