peer-agents

peer-agents

Use this skill when you want another AI coding agent to either advise you (consultation) or do work for you (task hand-off). The peer runs in a tmux session in the same working directory. You exchange turns until you peer end the session.

Both shipped peers run unattended (codex --yolo, claude --dangerously-skip-permissions) so hand-off works without permission prompts. The peer can read files, write files, run commands, and report back.

Hard rule: only use the peer CLI

Never run tmux send-keys, tmux paste-buffer, tmux attach, or any other raw tmux command against a peer session. peer send already handles paste + Enter + sentinel polling + reply extraction. Raw tmux calls will skip the Enter (the prompt sits in the pane unsubmitted), bypass the sentinel logic, or corrupt the session state.

The only commands you should ever invoke against a peer are: peer spawn, peer send, peer read, peer end, peer list, peer reap, peer kill-all. If you find yourself reaching for tmux ..., stop and use peer send instead.

When to use

Consultation / second opinion (peer reads, you decide):

• "Get a Codex review of src/auth.py before I merge"
• "Have Claude give me a second take on this bug — am I missing something?"
• "Disagreement loop": ask, push back on the reply, iterate

Task hand-off (peer acts in your CWD):

• "Codex, implement the rename refactor in src/users/. Update all callers. Run the tests."
• "Claude, fix the failing tests in tests/integration/. Don't touch unrelated files."
• "Codex, run the migration script and tell me what failed."
• Run two peers in parallel: one researches a library while the other refactors

Either intent — use the same primitives: The difference between consultation and hand-off is how you phrase the prompt, not a CLI flag. Be explicit about which mode you want.

When NOT to use

• One-off question you can answer yourself
• The peer would just need to read a file you've already read
• A task small enough that delegating costs more time than doing it
• Heavy fan-out workloads ("do X to all 100 files") — peers are for dialogue and discrete hand-offs, not a worker pool

Tools available on $PATH

• peer spawn <profile> — start a peer, prints session id on stdout
• peer send <id> "<prompt>" — send a turn, blocks until the peer signals done, prints reply
• peer read <id> — re-print the last reply (if you lost it)
• peer end <id> — kill the session
• peer list — show all live peer sessions on the socket (not scoped to this conversation; v0.1 has no ownership concept)

Profiles shipped: codex, claude. Both run unattended (no permission prompts).

Standard flows

Consultation (peer reads only):

ID=$(peer spawn codex)
REPLY=$(peer send "$ID" "READ-ONLY REVIEW. Do not edit anything. Review src/auth.py for security issues with exact line numbers.")
echo "$REPLY"
REPLY=$(peer send "$ID" "On line 42 you flagged the timing comparison — is hmac.compare_digest sufficient?")
echo "$REPLY"
peer end "$ID"

Task hand-off (peer acts in CWD):

ID=$(peer spawn codex)
REPLY=$(peer send "$ID" "TASK: Rename UserService to AccountService across src/. Update all imports and tests. When done, run pytest and report the result. Do not modify unrelated files.")
echo "$REPLY"
# verify what actually changed before trusting the report:
git diff --stat
git status
peer end "$ID"

Two peers in parallel (one delegates, one consults):

WORKER=$(peer spawn codex)
REVIEWER=$(peer spawn claude)
peer send "$WORKER" "TASK: Add input validation to src/api/handlers.py" &
peer send "$REVIEWER" "READ-ONLY: Audit src/api/handlers.py for missing validation; list issues by line." &
wait
peer end "$WORKER"; peer end "$REVIEWER"

How replies are detected

Every prompt you send is automatically wrapped with two per-turn marker lines the peer is instructed to emit:

<<<<START-a3f1>>>>     ← printed before the reply
<<<<DONE-a3f1>>>>      ← printed after the reply

peer send blocks until both lines appear (line-anchored, on their own) in the peer's pane, then returns everything between them as the reply text. The TUI's echo of your prompt mentions the markers as inline text within instruction sentences — never on their own line — so a TUI echo never triggers a false match. Default timeout: 300 seconds. Pass --timeout 600 for longer turns.

Critical gotchas

1. Always quote the prompt. peer send $ID "review foo.py" — without quotes, shell splits and the peer gets garbage.
2. Be explicit about intent in every prompt. Peers run unattended and can write files. State the mode up front:
   • Consultation: prefix with READ-ONLY REVIEW. Do not edit anything.
   • Hand-off: prefix with TASK: and list explicit constraints (which files, which not, run tests after, etc.)
   • Without an explicit boundary, the peer may guess wrong and edit files you didn't want touched.
3. After a hand-off, verify with git diff / git status before trusting the peer's report. The peer may report "done" while having edited more (or less) than expected. The sentinel only proves the peer finished, not that it did the right thing.
4. Don't run two hand-off tasks against overlapping files in parallel. Both peers share the same CWD; concurrent writes to the same paths will clobber. Parallel is fine for non-overlapping work or for one-writer + one-reader patterns.
5. End sessions when done. peer end <id>. Sessions don't auto-clean — run /agentic-workflow:peer-reap to kill sessions idle longer than 60 minutes, /agentic-workflow:peer-kill-all to nuke everything. peer list shows all live sessions on the socket (including ones spawned by other conversations) — review before reaping.
6. If the peer ignores the sentinel and you get a timeout, don't retry into the confused session. End it and start fresh.
7. Don't delegate work you can do faster yourself. Each peer call burns another model's budget.
8. Never drive the tmux pane directly. peer send does paste-buffer + Enter + sentinel-polling + reply-capture as one atomic operation. If you fall back to tmux send-keys or tmux paste-buffer you will almost always forget the trailing Enter and the prompt will sit in the pane unsubmitted, looking like the peer hung. There is no scenario in this skill where raw tmux commands are the right tool — use peer send every time.

Exit codes

• 0: success
• 2: unknown profile
• 4: peer never reached its ready prompt (spawn failed)
• 5: session id not found
• 7: sentinel timeout (peer didn't finish in time)
• 8: peer died during the turn

After every spawn: hand the controls to the user

The user cannot see the tmux session you just spawned, and they cannot see the session id unless you print it. Immediately after a successful peer spawn, always post a handoff block back to the user that contains all four of:

1. The session id you got back from peer spawn.
2. The watch command (read-only attach).
3. The peer send command they (or you) use to send the next turn.
4. The end command.

Template — fill in the actual <id> and replace <your prompt> with a placeholder, leaving the rest verbatim:

Spawned peer: <id>

To watch (read-only, detach with Ctrl+b d):
  tmux -S "${CLAUDE_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/claude-tmux-sockets}/peer.sock" attach -t <id>

To send the next turn (always quote the prompt):
  peer send <id> "<your prompt>"

Other useful commands:
  peer read <id>        # re-print the last reply
  peer list             # show all live peer sessions
  peer end <id>         # kill this session when done

Print this block even if you are about to send the first turn yourself — the user still needs to know how to interject, watch, or take over.