Peer Sessions — Development skill for Claude Code

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.

Placement	Where the peers land	Pick it when
split	new panes beside your own pane, in your workspace	1-3 peers, short work, you want to watch them. Your pane