Agent Teams in Claude Code: several Claude sessions working like a real team
TL;DR
Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. The main session becomes team lead, spawns independent teammates, splits work through a shared task list (with dependencies), and teammates message each other. Great for parallel review, competing-hypothesis debugging and layer-split features. Start with 3–5 teammates.
Enable it
// settings.json
{
"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}Subagents vs Agent Teams
| Subagents | Agent Teams | |
|---|---|---|
| Communication | Return results to the main agent | Teammates message each other |
| Coordination | Main agent manages everything | Shared task list, self-claiming |
| Token cost | Lower | High — each teammate is its own Claude session |
| Best for | Focused work where only the result matters | Work needing discussion and challenge |
Sample prompt
Spawn three teammates to review PR #142:
- one focused on security
- one checking performance
- one validating test coverage
Have them report findings, then summarize.Lessons
- Avoid shared files: split work so each teammate owns its own set of files.
- Rich spawn prompts: teammates don't inherit the lead's chat history.
- 5–6 tasks per teammate so the lead can reassign when someone gets stuck.
- Quality hooks: exit 2 in
TaskCompletedto block completion when tests fail. - Limits: no resuming in-process teammates, one team per session, no nested teams.