Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.
Unlike subagents, which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.
This page covers:
- When to use agent teams, including best use cases and how they compare with subagents
- Starting a team
- Controlling teammates, including display modes, task assignment, and delegation
- Best practices for parallel work
When to use agent teams
Agent teams are most effective for tasks where parallel exploration adds real value. See use case examples for full scenarios. The strongest use cases are:
- Research and review: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other’s findings
- New modules or features: teammates can each own a separate piece without stepping on each other
- Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster
- Cross-layer coordination: changes that span frontend, backend, and tests, each owned by a different teammate
Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.
Enabling Agent Teams
Set the following environment variable to enable Agent Team functionality:
"HAWA_CODE_EXPERIMENTAL_AGENT_TEAMS":"1", |
Comparison with Subagents
| Feature | Subagents | Agent teams |
|---|---|---|
| Context | Separate context window; results returned to caller | Separate context window; fully independent |
| Communication | Report results only to main agent | Teammates communicate directly with each other |
| Coordination | Main agent manages all work | Shared task list, self-coordinating |
| Best for | Targeted tasks where only results matter | Complex work requiring discussion and collaboration |
| Token cost | Lower: results fold into main context | Higher: each teammate is a separate Claude Code instance |
Use subagents when you need fast, targeted workers that report back. Use agent teams when teammates need to share findings, challenge each other, and self-coordinate.