Subagents and agent teams solve different problems. Subagents are for independent parallel work: spin up three agents to search three codebases, collect the results, move on. Agent teams are for collaborative work: a lead agent breaks a task into pieces and teammates work on their pieces while communicating about shared state.
If the work is truly parallel and the agents do not need to coordinate mid-task, subagents are simpler and have no experimental caveats. If coordination is the point, read on.
Enable agent teams
Agent teams are experimental. Set the environment variable before starting Claude Code:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claudeOr set it per-session in your shell’s rc file. Without this flag, the /team command and team-related frontmatter fields are not available.
Start a team
/team lead "You are the lead. Spawn a backend teammate and a frontend teammate. Assign the API changes to backend and the UI changes to frontend. Coordinate on the shared data model."The lead agent can spawn teammates with /spawn or by describing roles in natural language. Each teammate gets a name, a role description, and shared access to the task list.
Choose a display mode
Set teammateMode in your settings:
{
"teammateMode": "auto"
}| Mode | What you see |
|---|---|
in-process | All teammates in one terminal pane, tab through with Shift+Down |
tmux | Each teammate in a separate tmux window |
auto | In-process if one terminal, tmux if you have splits available |
tmux mode requires tmux in PATH. In-process mode is easier to monitor but harder to read when teammates are chatting fast.
Hooks for team quality gates
Three hooks fire on team events:
TeammateIdle: a teammate finished its current task and is waiting. Use this to run tests before the lead assigns the next task.TaskCreated: the lead assigned a new task. Log it or enforce naming conventions.TaskCompleted: a teammate marked a task done. A good place to run a linter or type checker before the lead picks up the result.
{
"hooks": {
"TeammateIdle": [{"matcher": "", "hooks": [{"type": "command", "command": "npm test --passWithNoTests"}]}]
}
}An exit code of 2 from any team hook blocks the event and feeds the reason back to Claude.
Subagents vs agent teams
| Subagents | Agent teams | |
|---|---|---|
| Experimental flag required | No | Yes |
| Coordination model | Parent polls | Shared mailbox + task list |
| Teammates message each other | No | Yes |
/resume works | Yes | No (in-process) |
/rewind works | Yes | No (in-process) |
| Nested teams | Yes (subagents in subagents) | No |
| Skills + MCP from frontmatter | Yes | No (not applied as teammate) |
| Token cost | Linear with agent count | Linear with agent count |
Footguns
Skills and MCP server frontmatter are not applied to teammates. If your skill frontmatter declares mcpServers or allowed-tools, those apply when the main agent invokes the skill, not when teammates run. Configure teammate tools explicitly in the team prompt.
In-process teams have no /resume or /rewind. If the session crashes mid-team, you start over. Use tmux mode if session recovery matters on a long-running task.
You can only run one team at a time. Starting a new /team ends the current one. For genuinely parallel multi-team work, run separate Claude Code sessions.
File conflicts happen when teammates edit the same file. Claude Code does not implement file locking. Two teammates editing the same file will produce merge conflicts. Assign territories by directory and let the lead handle merges explicitly.
Three to five teammates is the practical ceiling. The token cost of the shared task list and mailbox scales with team size. Beyond five teammates, coordination overhead starts to outweigh the benefits. Check /usage before scaling up.
When NOT to use agent teams
- The tasks are genuinely independent. Subagents are faster, cheaper, and do not require the experimental flag.
- You need
/resumeafter a crash. Use subagents or run the tmux display mode and restart the team session. - The agents need different MCP servers or skills. Agent teams share a tool set. Use subagents with isolated frontmatter instead.
- You are in a CI environment. Experimental features are not appropriate for automated pipelines. Use the Agent SDK for programmatic multi-agent orchestration in CI.