| name | orchestration |
| description | Multi-agent orchestration patterns for Claude Code team mode. Use when coordinating teammates, decomposing complex tasks, or managing shared task lists. |
Orchestration
Patterns for coordinating multi-agent work in Claude Code using team mode.
Source: code.claude.com/docs/en/agent-teams
Quick Start
Tell the lead what team you want in natural language:
Create an agent team to refactor the auth module. Spawn three teammates:
- One focused on extracting shared utilities
- One migrating tests to the new structure
- One updating documentation
Use Sonnet for each teammate.
The lead creates the team, spawns teammates, distributes work via a shared task list, and synthesizes results.
How It Works
| Component | Role |
|---|
| Team lead | Your main session — creates team, spawns teammates, coordinates |
| Teammates | Separate Claude Code instances working on assigned tasks |
| Task list | Shared work items teammates claim and complete |
| Messaging | SendMessage for DMs, broadcasts, and shutdown requests |
Teammates are persistent — they go idle between turns and can be woken up with messages. They can message each other directly.
Key Behaviours
- Lead spawns teammates based on your prompt — you describe the team, the lead creates it
- Teammates self-claim tasks from the shared list after finishing work
- No nested teams — teammates cannot spawn their own teams or teammates
- File partitioning — never assign the same file to multiple teammates
- 3-5 teammates is the sweet spot for most workflows
- 5-6 tasks per teammate keeps everyone productive
When Teams vs Subagents
| Subagents | Teams |
|---|
| Communication | Report back to caller only | Message each other directly |
| Coordination | Main agent manages all work | Shared task list, self-coordination |
| Best for | Focused tasks, only result matters | Complex work needing collaboration |
| Token cost | Lower | Higher (each teammate = separate instance) |
References
- patterns.md - 6 orchestration patterns (fan-out, pipeline, map-reduce, speculative, background, task-graph)
- domains.md - 8 domain-specific decomposition guides
- task-management.md - Task dependencies, graph walking, file partitioning
