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