Spawn Manager

Spawn Manager — Multi-Agent Parallel Development

Spawn Manager helps you launch, coordinate, and manage multiple Claude Code instances (peers) working in parallel on the same machine. It builds on Claude Peers MCP (the built-in peer discovery and messaging layer) and adds structured spawning patterns, team templates, cost tracking, and safety controls.

Use this when your task benefits from parallelism: independent workstreams, multi-perspective review, research fanout, or any scenario where 2-8 Claude Code instances working simultaneously outperform one instance working sequentially.

Prerequisites

Claude Peers MCP ships with Claude Code. No configuration needed. Every Claude Code instance on the same machine can discover and message other instances automatically.

Four MCP tools are available to every instance:

Spawning Patterns

1. Quick Spawn

Fire-and-forget single peer for a focused, self-contained task. Zero coordination overhead.

When to use: You need one thing done in the background while you continue your own work. The task is independent and does not require back-and-forth.

How to spawn:

# Non-interactive — peer runs the task, prints output, and exits:
claude --print "Your focused task here" --allowedTools "Edit,Write,Read,Bash,Grep,Glob"

# Interactive — peer stays open for follow-up:
claude
# Then paste: set_summary("Quick spawn: [task description]") and begin

Examples:

# Write tests while you implement the feature
claude --print "Write comprehensive unit tests for src/auth/jwt.ts. Cover all exported functions, edge cases, and error paths. Use Vitest. Output to src/auth/__tests__/jwt.test.ts"

# Generate API docs while you build endpoints
claude --print "Generate OpenAPI 3.1 spec for all routes in src/api/. Output to docs/openapi.yaml"

# Security audit while you code
claude --print "Audit src/ for OWASP top 10 vulnerabilities. Report as markdown with severity, file:line, issue, and fix. Output to reports/security-audit.md"

2. Team Spawn

Spawn N peers with explicitly assigned roles, file boundaries, and tasks. You remain the coordinator.

When to use: A feature decomposes into 2-5 independent workstreams that can run simultaneously. Each peer owns a clear slice of the codebase.

How to spawn:

1. Define the work breakdown: roles, tasks, file boundaries, branch names
2. Open N terminal tabs or panes (iTerm2 split panes, tmux, etc.)
3. Launch a Claude Code instance in each with role-specific instructions
4. Set your own summary: set_summary("Coordinator: managing N peers for [goal]")
5. Monitor with list_peers and check_messages
6. Merge branches when all peers complete

Peer launch template:

claude --print "
ROLE: [role name — e.g., Frontend Developer]
TASK: [specific deliverable — e.g., Build the settings page with form validation]
BRANCH: spawn/[goal]/[role]
FILE BOUNDARIES: [explicit list of files/directories this peer owns]
WHEN DONE: Commit your work, then send a message to the coordinator peer:
  'DONE: [summary of what was built, any issues, files changed]'
Call set_summary('[Role]: [status]') immediately on startup and whenever your focus changes.

CONTEXT:
[Paste all relevant context: specs, API contracts, schemas, type definitions, examples.
The peer does NOT share your session. Include everything it needs.]
"

Example — Auth feature team of 3:

# Terminal 1 — Backend
claude --print "ROLE: Backend Developer
TASK: Implement JWT auth — signup, login, refresh, logout endpoints
BRANCH: spawn/auth/backend
FILE BOUNDARIES: src/api/auth/, src/services/auth/, src/db/migrations/
..."

# Terminal 2 — Frontend
claude --print "ROLE: Frontend Developer
TASK: Build login page, signup page, forgot-password flow
BRANCH: spawn/auth/frontend
FILE BOUNDARIES: src/pages/auth/, src/components/auth/, src/hooks/useAuth.ts
..."

# Terminal 3 — Tests
claude --print "ROLE: Test Engineer
TASK: Write unit + integration tests for auth endpoints and pages
BRANCH: spawn/auth/tests
FILE BOUNDARIES: tests/auth/, src/__tests__/auth/
..."

3. Swarm Spawn

Describe a goal and let the coordinator auto-determine the optimal peer count and role distribution.

When to use: You have a large goal but are not sure how to decompose it. The coordinator analyzes the goal and spawns the right team.

Decomposition process:

1. State the goal
2. Coordinator analyzes: How many independent units of work? What specializations? What file boundaries?
3. Coordinator applies these heuristics:
   • 1 independent unit = 1 peer (never over-parallelize)
   • Cap at 8 peers (resource limit on a single machine)
   • Each peer must have non-overlapping file ownership
   • If two units share state or files, merge them into one peer
   • Estimate total cost before spawning
4. Coordinator presents the plan: peer count, roles, estimated cost
5. On approval, coordinator spawns the team
6. Swarm works in parallel
7. Coordinator collects, merges, and verifies

Example:

/spawn swarm "Migrate the entire auth system from NextAuth to Better Auth.
Update all API routes, middleware, session handling, and client-side hooks.
Write migration tests. Update documentation."

Coordinator might decompose this into:

• Peer 1: Backend migration (API routes, middleware, session)
• Peer 2: Frontend migration (hooks, components, pages)
• Peer 3: Test writer (migration tests, regression tests)
• Peer 4: Documentation updater (README, API docs, migration guide)

4. Expert Spawn

Spawn a single domain-specialist peer pre-configured with domain-specific analysis instructions.

When to use: You need specialized analysis (security audit, performance review, design critique, accessibility check) without context-switching from your current task.

Available expert domains:

Launch template:

claude --print "
You are a [domain] expert. Call set_summary('[Domain] expert: reviewing [target]').

REVIEW TARGET: [file paths, module names, or description of what to review]

Analyze from a [domain] perspective. Structure your findings as:

CRITICAL: [must fix before shipping — security holes, data loss risks, crashes]
HIGH: [should fix soon — performance regressions, accessibility failures]
MEDIUM: [fix when convenient — code quality, minor UX issues]
LOW: [nice to have — optimization opportunities, polish]

For each finding include:
- File and line number
- Description of the issue
- Why it matters
- Recommended fix with code example

Send results to the coordinator peer when done.
"

Spawn Templates

Pre-configured team compositions for common scenarios. Use as starting points and customize.

Feature Team (4 peers)

Review Board (4 peers)

Research Squad (5 peers)

Bug Hunt (4 peers)

Migration Crew (4 peers)

Content Factory (5 peers)

Coordinator Protocol

When you are the coordinator (the instance that spawns and manages peers), follow this six-step protocol.

Step 1: Plan the Breakdown

Before spawning anything, define:

• Peer count: 2-8 (fewer is better — each peer costs money and adds coordination overhead)
• Roles: What each peer is responsible for
• File boundaries: Which peer owns which files (non-overlapping)
• Branch strategy: One branch per peer (spawn/{goal}/{role})
• Communication protocol: How peers report progress and completion
• Cost ceiling: Maximum total spend across all peers
• Exit criteria: What "done" looks like for each peer

Step 2: Spawn with Self-Contained Prompts

Each peer prompt MUST be fully self-contained. Include:

• Role and task description
• All relevant context (specs, schemas, API contracts, type definitions)
• Explicit file boundaries
• Branch name to work on
• Output format and completion signal
• Instruction to call set_summary immediately on startup

Peers do NOT share your context window. They start with a blank slate. If a peer needs information from a file, either paste the content or instruct the peer to read it.

Step 3: Monitor Progress

Every 5-10 minutes while peers are active:

1. Call list_peers — verify all spawned peers still appear
2. Call check_messages — read any status updates or questions
3. Update your own summary: "Coordinator: 2/4 peers complete, merging frontend"
4. If a peer disappears from list_peers → mark as failed (see Step 5)
5. If a peer asks a question → respond immediately with send_message

Step 4: Collect Results

As peers complete their work:

1. Read their completion message via check_messages
2. Verify their branch has commits: git log spawn/{goal}/{role} --oneline
3. Review the diff for quality: git diff main...spawn/{goal}/{role}
4. Merge into your integration branch: git merge spawn/{goal}/{role}
5. Run tests after each merge to catch integration issues early
6. Acknowledge receipt to the peer via send_message

Step 5: Handle Failures

Step 6: Synthesize and Verify

After all peers complete:

1. Merge all branches in dependency order (typically: database, backend, frontend, tests)
2. Run the full test suite
3. Run type checking: npx tsc --noEmit
4. Run linters
5. Review the combined diff for coherence
6. Create a summary of what each peer delivered
7. Commit the merged result with a conventional commit message
8. Delete spawn branches: git branch -d spawn/{goal}/*

Cost Management

Multi-peer workflows multiply your API spend. Track aggressively.

Estimation Table

Multiply per-peer cost by peer count. Add 20% for coordinator overhead. Set a ceiling before starting.

Budget Controls

• Per-peer ceiling: Include in the peer's prompt: "This task should take no more than ~X tokens. If you find yourself exceeding that, summarize progress and stop."
• Total ceiling: Sum of all per-peer ceilings + coordinator overhead. If the total would exceed your daily budget, reduce peer count or simplify tasks.
• Kill trigger: If any peer appears to exceed 2x its estimated cost (based on output length and complexity), investigate immediately.
• Post-mortem: After completion, log actual cost per peer. Use this data to calibrate future estimates.

Cost-Saving Tips

1. Use --print mode for peers that do not need interaction — cheaper (no back-and-forth overhead)
2. Send file paths, not file contents — let peers read files themselves instead of pasting 500-line files into prompts
3. Summarize shared context — if 4 peers all need the same reference doc, summarize it once and send the summary
4. Kill idle peers — peers should exit when done. Periodically check list_peers and send exit signals to peers that should have finished
5. Batch related tasks — two small tasks for one peer is cheaper than two peers with startup overhead each
6. Use the right model — if a peer's task is simple (formatting, file copying), consider whether it even needs an LLM

Safety Rules

1. Maximum 8 simultaneous peers. Mac Mini M4 with 16GB RAM imposes real resource limits. Each Claude Code instance consumes memory and CPU. Beyond 8, performance degrades for all instances.

2. Checkpoint before spawning. Run /checkpoint or git stash so you can recover if the spawn operation produces unexpected results. Name the checkpoint: pre-spawn-[goal].

3. Separate branches per peer. Never allow multiple peers to commit to the same branch. The coordinator is the only one who merges. Branch naming convention:

   spawn/{goal}/{role}
   # Examples:
   spawn/auth-feature/frontend
   spawn/auth-feature/backend
   spawn/auth-feature/tests
   

4. Explicit file boundaries. If two peers edit the same file, you will get merge conflicts. Prevent this by assigning clear file ownership in every peer prompt.

5. Auto-cleanup. Peers should exit when their task is complete. Do not leave idle instances running. Periodically call list_peers and send termination messages to peers that should have finished but are still alive.

6. No recursive spawning. Peers must NOT spawn their own sub-peers unless the coordinator explicitly instructs them to. Keep the hierarchy flat: coordinator -> peers. One level only.

7. Commit message convention for peers:

   feat(frontend): add login page components [spawn: auth-feature]
   feat(backend): add JWT auth endpoints [spawn: auth-feature]
   test: add auth integration tests [spawn: auth-feature]
   

8. Rollback plan. Before spawning, know how you would undo the entire operation. At minimum: git branch -D spawn/{goal}/* to delete all spawn branches.

Integration with Task Commander

For complex tasks (P6+ in CC Commander's priority system), Task Commander can leverage Spawn Manager:

1. Task Commander evaluates scope and determines parallelizability
2. If parallelizable, it creates a work breakdown with independent units
3. Each unit becomes a peer prompt — fully 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 (~15 minutes), mark as failed and reassign
6. Cost ceiling: if total peer spend exceeds the threshold, kill non-essential peers first (tests, docs) and preserve core work (backend, frontend)
7. On completion, coordinator synthesizes all results and runs the verification loop

claude-squad Compatibility

claude-squad is a complementary open-source tool for managing multiple Claude Code instances with a terminal UI. It provides:

• Visual dashboard showing all running instances
• Session management and naming
• Easy instance creation and termination
• Output monitoring across all instances

Spawn Manager and claude-squad serve different needs:

• Spawn Manager: Structured patterns, templates, cost tracking, coordinator protocol — the "how to think about multi-agent"
• claude-squad: Terminal UI for visual monitoring and session management — the "how to see what is happening"

Use both together for the best experience: design your spawn with Spawn Manager's patterns, monitor execution with claude-squad's dashboard.

Real-Time Monitoring Dashboard

Track your spawn operation in real time using the peers MCP tools:

# Check who is alive and what they are doing
list_peers(scope="repo")

# Expected output per peer:
# - instance_id: unique ID
# - summary: what the peer set via set_summary
# - cwd: working directory
# - status: active/idle

# Read incoming messages
check_messages()

# Update your own status
set_summary("Coordinator: 3/4 peers complete, merging backend branch")

For a visual dashboard, use claude-squad or build a simple watcher:

# Poll peer status every 30 seconds (run in a separate terminal)
watch -n 30 'claude --print "Call list_peers(scope=\"repo\") and format as a table showing: ID, Summary, CWD"'

Integration with CC Commander Skills

Quick Reference

SPAWNING PATTERNS:
  /spawn quick <task>           — Fire-and-forget single peer
  /spawn team <n> <tasks...>    — N peers with explicitly assigned roles
  /spawn swarm <goal>           — Auto-decompose goal and spawn optimal team
  /spawn expert <domain>        — Spawn domain-specialist peer
  /spawn status                 — Show all active peers via list_peers

EXPERT DOMAINS:
  security, performance, design, testing, devops, database, api, accessibility

TEAM TEMPLATES:
  feature-team     — Frontend + Backend + Tests + Coordinator
  review-board     — Security + Performance + Correctness + Synthesizer
  research-squad   — NPM + GitHub + Docs + Community + Synthesizer
  bug-hunt         — Reproducer A + Reproducer B + Fixer + Regression
  migration-crew   — Schema + Data + Rollback + Verifier
  content-factory  — Writer A + Writer B + Writer C + Editor + SEO

LIMITS:
  Max peers: 8 simultaneous
  Branch pattern: spawn/{goal}/{role}
  Cost: estimate before, track during, report after
  Safety: checkpoint before spawn, one branch per peer, explicit file boundaries

COORDINATOR PROTOCOL:
  Plan → Spawn → Monitor → Collect → Handle failures → Synthesize → Verify