peer-sessions

A Claude Code skill for running a fleet of Claude Code sessions on one machine and making them talk to each other with SendMessage.

Claude Code 2.1.224 added cross-session messaging: one session can send a message to another, and that message arrives as a user prompt in the receiving session. This skill turns that primitive into a working loop — spawn a fleet, hand out briefs, collect the replies, and tear it down when you ask.

Install

npx skills@latest add ray-amjad/peer-sessions

Or copy this folder into ~/.claude/skills/peer-sessions/.

Requirements

• Claude Code 2.1.224 or newer on macOS or Linux. Older builds publish no messaging socket, so a session is alive but no other session can reach it.
• cmux for the spawn scripts. The messaging itself needs no terminal multiplexer — only the fleet layout does.

The loop

spawn a fleet → send a brief to each peer → end your turn → replies arrive as new user turns → hand back the teardown

python3 ~/.claude/skills/peer-sessions/scripts/spawn-fleet.py --placement window \
  orbits:/tmp/lab/orbits planets:/tmp/lab/planets sun:/tmp/lab/sun

window F8464A83-... (new)
+ orbits    uds:/tmp/cc-socks/17466.sock
+ planets   uds:/tmp/cc-socks/17398.sock
+ sun       uds:/tmp/cc-socks/17585.sock
3 ready in 10s.

Then send each peer a brief that ends with your own address, and stop. A peer reply is the notification — it wakes you as a new turn, so a poll loop only burns tokens.

Where the fleet appears

--placement decides the layout. The script prints the matching teardown commands, so you never close more than you made. Teardown is off by default — the fleet stays alive, with its context, until you ask for it to go.

--direction right|left|up|down places each new pane, --focus true|false decides whether the UI moves to the fleet, and --per-workspace 1 gives every session its own workspace. See references/placement.md.

What is in the box