Claude Peers Bible

Claude Peers — Multi-Instance Communication

Claude Peers is a built-in MCP server in Claude Code that allows multiple Claude Code instances running on the same machine to discover each other, communicate, and collaborate in real time. No extra configuration required — it ships with Claude Code.

This is the foundation for all multi-instance parallel development in CC Commander.

What Claude Peers Provides

Four MCP tools available to every Claude Code instance:

Discovery Scopes

list_peers accepts a scope parameter that controls which instances are visible:

Default scope is repo. Start with repo scope unless you have a specific reason to go broader.

Message Anatomy

When you receive a message via check_messages or a <channel source="claude-peers"> notification, it includes:

• from_id — The peer's unique instance ID (use this to reply)
• from_summary — What the sender is working on (set via set_summary)
• from_cwd — The sender's working directory
• content — The actual message body

Always read from_summary and from_cwd to understand context before responding.

Setup Protocol

No MCP configuration needed. Claude Peers is available by default. Every instance should follow this startup sequence:

1. Set your summary immediately — Call set_summary with a concise description of your role and current task
2. Discover peers — Call list_peers to see who else is active
3. Announce if coordinating — If you are a coordinator, send a message to each peer confirming the work plan

Example set_summary:
"Coordinator: managing 3 peers for auth feature — frontend, backend, tests"

"Backend peer: implementing JWT auth endpoints for /api/auth/*"

"Security reviewer: auditing auth implementation for OWASP top 10"

Communication Patterns

Pattern 1: Coordinator

One Claude Code instance manages the workflow. Others report to it.

Coordinator (you)
  |-- send_message --> Peer A (frontend)
  |-- send_message --> Peer B (backend)
  |-- send_message --> Peer C (tests)
  |
  |<-- check_messages -- Results from A, B, C
  |
  V
Synthesize, merge, verify

Best for: Feature development, build pipelines, any workflow needing a single point of control.

Coordinator responsibilities:

1. Plan the work breakdown before spawning peers
2. Send each peer a self-contained prompt with all necessary context
3. Poll list_peers periodically to confirm peers are still alive
4. Collect results via check_messages
5. Handle failures — respawn or reassign if a peer stops responding
6. Synthesize results and run final verification

Pattern 2: Swarm

Multiple equal peers collaborate without a designated leader. Each discovers others and communicates directly.

Peer A <---> Peer B
  ^            ^
  |            |
  v            v
Peer C <---> Peer D

Best for: Exploratory research, brainstorming, when no single peer has authority over others.

Protocol:

1. Each peer sets a descriptive summary on startup
2. Before starting work, each calls list_peers to see the full team
3. Peers send findings to all others as they discover them
4. Any peer can request help from another by sending a targeted message
5. Convergence happens organically — peers build on each other's findings

Pattern 3: Expert Panel

Specialized instances handle specific domains. A synthesizer collects all expert opinions.

Expert: Security ----\
Expert: Performance --+--> Synthesizer --> Final Report
Expert: UX ----------/

Best for: Code review, architecture decisions, audit workflows.

Each expert:

1. Sets summary describing their domain ("Security expert: reviewing auth module for vulnerabilities")
2. Receives the artifact to review via send_message from the synthesizer
3. Conducts domain-specific analysis independently
4. Sends structured findings back to synthesizer

Synthesizer:

1. Distributes the review target to all experts
2. Collects all expert reports
3. Merges findings, resolves conflicts, ranks by severity
4. Produces unified report

Pattern 4: Writer-Reviewer

One instance writes, another reviews. The writer iterates based on feedback.

Writer --> send_message(code) --> Reviewer
Writer <-- send_message(feedback) <-- Reviewer
Writer --> send_message(revised) --> Reviewer
Writer <-- send_message(approved) <-- Reviewer

Best for: TDD pairs, code review loops, documentation review.

Pattern 5: Research Fanout

Multiple instances search in parallel. One synthesizes all findings.

Researcher A (search: npm packages) ----\
Researcher B (search: GitHub repos) -----+--> Synthesizer --> Recommendation
Researcher C (search: blog posts) ------/
Researcher D (search: benchmarks) -----/

Best for: Technology evaluation, competitive analysis, dependency audits.

Bible-Optimized Workflows

Parallel Feature Build

Spawn 3 peers to build a feature simultaneously:

Flow:

1. Coordinator sends detailed specs to each peer with file boundaries
2. Each peer works on their branch independently
3. Peers send progress updates to coordinator every 10-15 minutes
4. Coordinator merges branches in order: backend, frontend, tests
5. Coordinator runs full E2E suite to verify integration

Multi-Perspective Review

Spawn 3 reviewer peers for thorough code review:

Coordinator sends PR diff to:
  1. Security Reviewer  --> checks OWASP, auth, injection, secrets
  2. Performance Reviewer --> checks N+1 queries, memory, caching
  3. Correctness Reviewer --> checks logic, edge cases, error handling

Each sends structured report:
  { severity: "critical|high|medium|low", findings: [...] }

Coordinator merges into unified review.

Overnight Build Swarm

5+ peers tackling independent features while you sleep:

1. Coordinator creates a work manifest with 5-10 independent tasks
2. Each peer gets one task with full context (no shared state needed)
3. Each peer commits to its own branch on completion
4. Each peer sends completion status to coordinator
5. Coordinator tracks progress, respawns failed peers
6. Morning: coordinator presents summary of all completed work

Combine with the overnight-runner skill for auto-checkpoint and cost controls.

Dialectic Review via Peers

Architecture decisions benefit from structured debate:

Protocol:

1. Coordinator sends the decision question to FOR and AGAINST simultaneously
2. FOR and AGAINST work independently (no communication between them)
3. Both send their arguments to Referee
4. Referee evaluates and sends verdict to Coordinator
5. Coordinator presents the decision with full reasoning chain

Message Format Best Practices

Always use structured messages for machine-readable communication between peers:

TYPE: status_update | request | result | error | question
FROM_ROLE: coordinator | frontend | backend | tester | reviewer
TASK_ID: optional task identifier
---
[Message body with full context]

Rules:

1. Always set_summary when starting work and when focus changes
2. Respond immediately to peer messages — pause current work, reply, then resume
3. Include full context in every message — peers do not share your session state
4. Never assume shared knowledge — each peer has its own context window
5. Use structured formats so peers can parse messages programmatically
6. Checkpoint before sending large outputs — if your message includes code, save it to a file and send the path instead
7. Handle disconnects — if list_peers shows a peer disappeared, reassign their work or flag the issue

Integration with Task Commander

For complex tasks (P6+ in CC Commander priority system), Task Commander can leverage peers:

1. Task Commander evaluates the task scope
2. If parallelizable, it creates a work breakdown with independent units
3. Each unit becomes a peer prompt — self-contained with all context
4. Coordinator peer tracks status and estimated cost per peer
5. Circuit breaker: if a peer stops responding after 3 polls, mark as failed and reassign
6. Cost ceiling: if total peer spend exceeds threshold, kill non-essential peers
7. On completion, coordinator synthesizes all results and runs verification

Troubleshooting

Cost Awareness

Each Claude Code peer consumes its own context window and API tokens:

• Estimate before spawning: Roughly gauge how many tokens each peer's task will need
• Set a ceiling: Coordinator should track total estimated spend across all peers
• Kill early if stuck: A peer spinning without progress is burning money
• Prefer fewer, focused peers over many unfocused ones
• Reuse context: If multiple peers need the same reference material, have the coordinator summarize it rather than each peer reading the full source

Quick Start Checklist

Starting a multi-peer workflow:

• Plan work breakdown — identify independent units
• Determine peer count (2-8, usually 3-4)
• Write self-contained prompts for each peer (no context bleeding)
• Define file boundaries so peers do not edit the same files
• Define branch strategy (one branch per peer, coordinator merges)
• Set your own summary as coordinator
• Spawn peers and send initial instructions
• Poll list_peers every few minutes to track health
• Collect results via check_messages
• Run full verification after merging all peer work
• Clean up — ensure all peers have exited

Source: KevinZai/commander — distributed by TomeVault.