Agent Teams
Overview
⚠️ Experimental — Enable with
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Agent Teams allow multiple Claude Code instances to collaborate: one team lead coordinates work, teammates work independently, and teammates can communicate directly with each other.
Agent Teams vs Subagents
| Subagents | Agent Teams | |
|---|---|---|
| Context | Own context, results return to caller | Own context, fully independent |
| Communication | Report back to main agent only | Teammates message each other directly |
| Coordination | Main agent manages all work | Shared task list + self-coordination |
| Best for | Focused tasks | Complex collaborative work |
| Token cost | Lower | Higher |
Architecture Components
| Component | Role |
|---|---|
| Team lead | Main session that creates team, spawns teammates, coordinates |
| Teammates | Separate Claude Code instances |
| Task list | Shared work items that teammates claim/complete |
| Mailbox | Messaging system for inter-agent communication |
Display Modes
- In-process: All teammates in main terminal; press
Shift+Downto cycle - Split panes: Each teammate in own pane (requires tmux or iTerm2)
Task States
Three states: pending, in_progress, completed.
Tasks can have dependencies. File locking prevents race conditions on claiming.
Key Hooks
| Hook | Purpose |
|---|---|
TeammateIdle |
Fires when teammate about to go idle; exit 2 keeps them working |
TaskCompleted |
Fires when task being marked complete; exit 2 prevents completion (quality gate) |
Best Practices
Team Size
- Start with 3-5 teammates
- 5-6 tasks per teammate
- Task granularity should be fine enough to avoid inter-teammate conflicts
Good Use Cases
- Research/review: Multiple teammates reviewing different modules in parallel
- New module development: Each teammate responsible for an independent module
- Competing hypothesis debugging: Multiple teammates trying different fix approaches
- Cross-layer coordination: Frontend + backend + database teammates each with their domain
Poor Use Cases
- Highly sequential tasks (subagents are better)
- Dense edits to the same file (causes conflicts)
- Complex dependency chains
Limitations
- No session resumption with in-process teammates
- One team per session
- No nested teams
- Lead role is fixed
- Permissions set at spawn time
Example Usage
Create an Agent Team to refactor this project's auth module:
Teammate 1 (Backend): Refactor auth middleware to use JWT
Teammate 2 (Database): Design new sessions table schema
Teammate 3 (Frontend): Update login/register pages for new API
Teammate 4 (Testing): Write E2E tests for new auth flow
Teammate 2 finishes first, then 1 and 3 can start in parallel. Teammate 4 runs last.