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