Agent Teams
Coordinate multiple Claude Code agents working together on complex tasks
Experimental FeatureWhat are Agent Teams?
ExperimentalAgent Teams is an experimental feature that allows multiple Claude Code agents to collaborate on complex tasks.
Agent Teams requires the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to be enabled.
Enabling Agent Teams
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claudeAgent Teams requires the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to be enabled.
Team Architecture
Lead Agent
The orchestrator that breaks down tasks, assigns work to teammates, and synthesizes results
Teammates
Independent agent instances that work on assigned subtasks in parallel
Task List
A shared list of tasks that the lead creates and teammates pick up
Mailbox
Communication channel between the lead and teammates for status updates and results
Setting Up Teams
Configure agent teams using the /teams command or programmatically through the SDK.
Define team composition
Configure communication patterns
Set task distribution strategy
Launch and monitor
Creating a Team
Define a team lead agent with teammate definitions. Each teammate has its own model, tools, and instructions.
Recommended team size: 3-5 agents
Aim for 5-6 tasks per teammate for optimal throughput
> I need to refactor the authentication module.
> Split the work into 3 tasks:
> 1. Update the login flow (agent 1)
> 2. Migrate session management (agent 2)
> 3. Add OAuth2 support (agent 3)
> Use tmux mode so I can watch each agent work.Controlling Teammates
The team lead assigns tasks, monitors progress, and can redirect teammates. Teammates report back via the mailbox when tasks are complete or when they need help.
Teammates inherit permission settings from the team lead by default
Display Modes
In-Process Mode
All agents run within a single terminal session. Best for simpler coordination tasks with fewer agents.
Tmux Mode
Each agent runs in a separate tmux pane, providing visual oversight of all agents working simultaneously.
# Install tmux (if not already installed)
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt install tmux
# Start Claude with Agent Teams + tmux mode
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claudeUse Cases
Large-Scale Refactoring
Coordinate agents to refactor different modules simultaneously
Parallel Testing
Run test suites across multiple environments in parallel
Comprehensive Code Review
Assign different reviewers for security, performance, style, and correctness
Multi-Service Development
Develop frontend and backend services simultaneously
Advanced Use Cases
Parallel Code Review
Multiple agents review different parts of a codebase simultaneously -- one checks security, another checks performance, another checks style.
Competing Hypotheses Debugging
Spawn multiple agents to investigate different theories about a bug in parallel. The first to find the root cause wins.
Large-Scale Refactoring
Split a large refactoring task across agents, each handling a different module or file group.
Best Practices
- Start with small teams (2-3 agents) and scale up as needed
- Give each teammate a clear, focused task with well-defined boundaries
- Use tmux mode for better visibility when running more than 2 agents
- Monitor the mailbox regularly for coordination issues
- Set appropriate timeouts for long-running tasks
- Use the lead agent to verify and integrate teammate outputs
Best Practices - Detailed Guide
Keep teams small (3-5 agents) -- larger teams have more coordination overhead
Make tasks independent -- agents work best when they don't need to coordinate frequently
Give each teammate clear, self-contained instructions
Use the task list to monitor progress and adjust assignments
Use git worktrees for isolation when agents modify the same files
Limitations
Feature is experimental and may change
Each agent has independent context -- no shared memory
Complex inter-agent coordination can be unreliable
Running multiple agents increases API costs proportionally