claude-code-agent-teams
Claude Code Agent Teams
Agent teams coordinate multiple Claude Code sessions working together. One session acts as the team lead, spawning teammates that work independently in their own context windows and communicate directly with each other through a shared task list and mailbox messaging system.
Agent teams are experimental and disabled by default. Enable with
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. See Setup and Configuration for details.
When to Use Agent Teams
Agent teams add coordination overhead and consume significantly more tokens than a single session. Use them when parallel exploration adds real value:
- Research and review — teammates investigate different aspects simultaneously, share and challenge findings
- New modules or features — teammates each own a separate piece without stepping on each other
- Debugging with competing hypotheses — teammates test different theories in parallel, converge on answers faster
- Cross-layer coordination — changes spanning frontend, backend, and tests, each owned by a different teammate
Avoid agent teams for sequential tasks, same-file edits, work with many dependencies, or tasks a single session handles efficiently. For focused workers that only report results back, use subagents instead.