Coordinate multiple Claude Code instances working together on complex tasks
Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work and assigning tasks. Teammates work independently, each in their own context window, and can communicate directly with each other.
| Feature | Subagents | Agent Teams |
|---|---|---|
| Communication | Report back to parent only | Teammates message each other |
| Coordination | Parent manages everything | Shared task list, self-coordination |
| Interaction | Can't talk to them directly | Can message any teammate |
| Cost | Lower (results summarized) | Higher (each is a full instance) |
Full access
Unlock all 14 lessons, templates, and resources for Claude Code Mastery. Free.
Q: What's the key architectural difference between subagents and agent teams?
Communication model. Subagents can only report back to the parent session (one-way). Agent team teammates can message each other directly and coordinate through a shared task list. Each teammate is a fully independent Claude Code session. This makes teams better for collaborative work but significantly more expensive.
Agent teams are disabled by default. Enable them:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Just describe what you need in natural language:
I'm designing a CLI tool for tracking TODOs. Create an agent team:
- One teammate on UX design
- One on technical architecture
- One playing devil's advocate
Claude creates the team, spawns teammates, coordinates work, and synthesizes findings.
All teammates run inside your main terminal:
| Shortcut | Action |
|---|---|
Shift+Up/Down | Select a teammate |
Enter | View a teammate's session |
Escape | Interrupt their current turn |
Ctrl+T | Toggle the task list |
Each teammate gets its own terminal pane. Requires tmux or iTerm2.
{
"teammateMode": "tmux"
}
| Mode | Behavior |
|---|---|
auto (default) | Split panes if in tmux, otherwise in-process |
in-process | Always in main terminal |
tmux | Auto-detect tmux or iTerm2 |
Q: How do you interact with individual teammates in the in-process display mode?
Use Shift+Up/Down to select a teammate, then type to message them directly. Press Enter to view their full session, Escape to interrupt their turn, and Ctrl+T to toggle the shared task list. Each teammate is a full Claude Code session you can interact with independently.
The shared task list coordinates work across the team:
Pending → In Progress → Completed
Tasks can have dependencies — a pending task with unresolved dependencies can't be claimed until those dependencies are completed.
Task claiming uses file locking to prevent race conditions.
Prevents the lead from implementing tasks itself — restricts it to coordination-only tools:
Press Shift+Tab to cycle into delegate mode during a session.
Pro Tip: Delegate mode forces better architecture. When the lead can't implement, it focuses on clear task decomposition and quality review.
Fill in the blanks:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=___Ctrl+___1Ctrl+TcoordinationRuns when a teammate is about to go idle. Exit 2 to send them back to work:
{
"hooks": {
"TeammateIdle": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "./scripts/check-teammate-quality.sh"
}]
}]
}
}
Runs when a task is marked complete — validate the work:
{
"hooks": {
"TaskCompleted": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "./scripts/validate-task.sh"
}]
}]
}
}
Q: A TeammateIdle hook exits with code 2. What happens?
The teammate is sent back to work instead of going idle. Exit code 2 blocks the idle action and feeds the stderr message back as feedback. This is how you enforce quality gates — if a teammate hasn't run tests or their code doesn't lint, the hook sends them back to fix it.
Ask the researcher teammate to shut down.
The teammate can approve (exits gracefully) or reject with an explanation.
Clean up the team.
This removes shared team resources. Active teammates must be shut down first.
Agent teams are expensive — each teammate is a separate Claude instance:
Fill in the blanks:
Shift+___/DownShift+Up/DownIn Progresstmux (or iTerm2)export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Create a team of 2 to analyze this project:
- Teammate 1: analyze the architecture and suggest improvements
- Teammate 2: find potential bugs or security issues
Use Sonnet for both teammates.
Shift+Up/Down to switch between teammatesCtrl+T to view the task listReflection: How does the team's output compare to asking a single session to do both tasks?
Scenario: You need to build a new feature with a React frontend, Express API, and database migration. The components are somewhat interdependent (the frontend needs to know the API contract, the API needs to know the schema).
Use agent teams with plan approval:
Create a team to build the user dashboard:
1. Backend teammate: Design the API endpoints and database schema FIRST
- Require plan approval before implementation
- Output API contract as a shared document
2. Frontend teammate: Build React components AFTER backend plan is approved
- Reference the API contract from teammate 1
3. Test teammate: Write tests AFTER both plans are approved
- Unit tests for components, integration tests for API
Use delegate mode so I can review plans before implementation.
Sonnet for all teammates.
The key is using plan approval and task dependencies to handle the interdependencies. The backend designs first, frontend references the design, tests cover both.
| Concept | One-Liner |
|---|---|
| What they are | Multiple Claude Code instances coordinating together |
| Enable | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| Navigation | Shift+Up/Down select; Ctrl+T task list |
| Display modes | in-process (default) or split panes (tmux/iTerm2) |
| Delegate mode | Lead can only coordinate, not implement |
| Task list | Pending → In Progress → Completed, with dependencies |
| Quality gates | TeammateIdle and TaskCompleted hooks |
| Cost tip | Use Sonnet, keep teams small (2-3), clean up when done |
Next up: Headless / SDK Mode & CI/CD → — Run Claude Code non-interactively in scripts and GitHub Actions.