Multi-Agent Setup
Multi-Agent Setup
Running multiple model instances simultaneously, with one orchestrator coordinating and subagents executing. Useful when tasks are large enough that a single agent loop becomes unwieldy, or when subtasks can run in parallel to save wall-clock time.
Orchestrator-Workers is one of six multi-agent patterns documented in Anthropic's "Building Effective Agents" (December 2024).
When to Use Multi-Agent
Single agent handles most tasks. Multi-agent adds coordination overhead — only worth it when:
- Task is too large for one context: Rewriting an entire codebase won't fit in one session. Split by module.
- Independent parallel subtasks: Running tests and writing docs simultaneously. No reason to serialize.
- Specialization: Different models for different roles. claude-opus-4-6 as orchestrator, claude-sonnet-4-6 as coding subagent, lighter/cheaper model for simple lookups.
- Fault isolation: If one subagent fails, others continue. Better than a monolithic session failing entirely.
Architecture Patterns
Orchestrator + Workers
Orchestrator (Opus/Sonnet)
├── Worker A (Sonnet) → subtask 1
├── Worker B (Sonnet) → subtask 2
└── Worker C (Sonnet) → subtask 3
Orchestrator breaks down the task, dispatches to workers, collects results, integrates. Workers operate independently, report back.
Pipeline
Agent 1 (analyze) → Agent 2 (implement) → Agent 3 (test) → Agent 4 (document)
Sequential: each stage passes output to the next. Good for tasks with clear dependency order.
Reviewer Pattern
Worker (implements) → Reviewer (critiques) → Worker (revises)
Two agents in dialogue. Catches errors that a single agent reviewing its own work misses.
Implementation with Claude Code
Claude Code can be orchestrated via its API mode or by using the hook system to coordinate processes. For parallel workers, run multiple claude processes with separate working directories and contexts.
Practical approach: use a shell script or Python orchestrator to manage worker processes, collect their outputs, and synthesize results.
# Rough pattern: parallel workers
claude --no-interactive "implement feature A in /project/module-a" &
claude --no-interactive "implement feature B in /project/module-b" &
wait
claude --no-interactive "integrate module-a and module-b, run tests"
Cost Considerations
Multi-agent multiplies token costs. Three Sonnet workers running simultaneously = 3x the token burn. Use the right model at each tier:
- Orchestrator: claude-opus-4-6 if coordination complexity is high, Sonnet if not
- Workers: claude-sonnet-4-6 for coding, cheaper models for simple tasks
- Set context limits per worker to avoid runaway costs
On exe-dev
Remote VMs make multi-agent practical for overnight-runs. Spawn multiple sessions on an exe-dev instance, let them run in parallel overnight, collect results in the morning. No need to keep your local machine on.
Failure Modes
- Orchestrator loses track of worker state — add explicit checkpointing/status files
- Workers make conflicting changes to shared files — coordinate via shared file locks or separate working areas
- One worker blocks and others are waiting — set per-worker timeouts
Related
claude-opus-4-6 · claude-sonnet-4-6 · overnight-runs · exe-dev · agentic-workflows