Agent Teams
Coordinate multiple Claude Code instances with a team lead, teammates, shared tasks, direct messages, and worktree isolation.
What Agent Teams Are
Agent teams coordinate multiple Claude Code instances. One session acts as the team lead. It creates tasks, spawns teammates, monitors progress, and synthesizes results. Each teammate is a full Claude Code instance with its own context window.
Unlike subagents, teammates can communicate directly with each other and coordinate through a shared task list.
Experimental feature
Agent teams are experimental and disabled by default. Enable them only when the task benefits from real multi-agent coordination, and expect rough edges around resumption, task coordination, and shutdown behavior.
Enable Agent Teams
Set the environment variable or put it in Claude Code settings:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Then start Claude Code normally and ask for teammates in natural language.
How a Team Works
| Component | Role |
|---|---|
| Team lead | The main Claude Code session that decomposes work and coordinates |
| Teammates | Independent Claude Code instances working on assigned tasks |
| Task list | Shared local task state with pending, in progress, and completed tasks |
| Mailbox | Direct messaging between agents |
| Display mode | In-process panel or split panes through tmux/iTerm2 |
The lead can assign tasks. Teammates can also claim available work from the shared task list. Task claiming uses locking so two teammates do not claim the same task at once.
Start a Team
Use agent teams for tasks that split cleanly:
I am designing a CLI that tracks TODO comments.
Spawn three teammates:
- one for UX and command design
- one for technical architecture
- one to challenge failure modes
Have them compare findings, then synthesize a final plan.Good teams have independent lanes. Bad teams put several agents in the same file with vague ownership.
Subagents vs Agent Teams
| Aspect | Subagents | Agent teams |
|---|---|---|
| Context | Separate context; result returns to caller | Separate context; each teammate is independent |
| Communication | Parent-child only | Direct teammate messaging |
| Coordination | Main agent manages all work | Shared task list and self-claiming |
| Best for | Focused tasks where only the result matters | Complex work requiring discussion or cross-checking |
| Cost | Lower | Higher |
Start with subagents. Move to agent teams only when workers need to talk to each other or challenge each other's findings.
Dynamic workflows are a separate option. Use them when the task needs many agents in scripted phases, not a small group of peers negotiating live.
Good Use Cases
- Parallel code review where each teammate audits a different risk category.
- Debugging with competing hypotheses.
- New feature design split across frontend, backend, and tests.
- Architecture research where one teammate proposes, another critiques, and another validates against the codebase.
Avoid agent teams for sequential refactors, same-file edits, small bug fixes, or tasks with tight dependencies.
Quality Gates with Hooks
Agent teams expose lifecycle events that hooks can enforce:
| Hook event | Use case |
|---|---|
TaskCreated | Reject tasks that are too vague or too large |
TaskCompleted | Require tests, summaries, or changed-file lists before completion |
TeammateIdle | Send feedback before a teammate stops |
This keeps team coordination from turning into an unchecked background process.
Worktree Strategy
Agent teams and worktrees solve different parts of parallelism:
- The team system coordinates work.
- Worktrees isolate file edits.
- Hooks enforce quality gates.
For multi-file implementation work, give teammates clear ownership boundaries and prefer worktree isolation. For research-only teams, worktrees matter less.
Practical Prompt Pattern
Use an agent team for research only.
Teammates:
1. API reviewer: inspect route handlers and validation.
2. DB reviewer: inspect migrations and RLS.
3. Test reviewer: inspect coverage gaps.
Rules:
- Do not edit files.
- Each teammate returns file paths and evidence.
- The lead should synthesize disagreements and recommend next actions.Official References
- Orchestrate teams of Claude Code sessions
- Run agents in parallel
- Dynamic workflows
- Run parallel sessions with worktrees
- Automate actions with hooks
Continue with practice
You have finished the core ideas of Agent Teams.
If you want to turn the idea into something reusable, continue practicing on AgentWay.