Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, then ask Claude to create a team for work that splits into independent tasks. Your session becomes the lead. Teammates are separate Claude Code instances with their own context windows, coordinating through shared tasks and direct messages, displayed either in one terminal or in split panes. Agent view is a different feature for independently dispatched, worktree-isolated sessions.
- Agent teams are experimental and off by default. One environment variable turns them on.
- The lead owns the plan, the task list, and the final answer. Every teammate has its own context window and never sees the lead's conversation.
- Claude has to ask your approval before it spawns a team.
- In-process is the default display mode. Split panes need tmux or iTerm2.
- Agent view is a different feature. It manages worktree-isolated dispatched sessions and never lists team teammates as rows.
- Teammates get no worktree isolation. Two of them editing one file will overwrite each other.
Enable Claude Code agent teams
Agent teams ship disabled. One environment variable turns them on, either for a single shell or permanently through a settings file. The variable name below is the exact string in Anthropic's current documentation.
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claudeFor a persistent setting, add the variable under env in a Claude Code settings file. Put it in your personal settings if this is your own experiment. Commit it to the project only after the team has agreed to run an experimental feature.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}What an agent team actually creates
The session where you ask for the team becomes the lead. It creates and assigns work, watches task status, reconciles results, and writes the final response. Teammates are full Claude Code instances, each with its own context window, and they can message the lead and one another directly.
Everyone shares one task list. Tasks move through pending, in progress, and completed, can depend on other tasks, and use claiming so two teammates never take the same item. The lead assigns work explicitly; an idle teammate can also claim any unblocked task.
Teammates inherit project context: CLAUDE.md, MCP servers, skills, plus the spawn prompt the lead wrote. They do not inherit the lead's conversation. Anything you decided in that conversation is invisible to them, so put the decisions, the file boundaries, and the expected deliverable in the spawn prompt or in a file both can read.
The four coordination pieces
| Piece | Responsibility | What it shares |
|---|---|---|
| Team lead | Creates the plan, delegates work, and synthesizes the outcome | Task status and messages |
| Teammate | Executes one or more assigned or claimed tasks | Its own context, plus team tasks and mailbox messages |
| Task list | Tracks pending, in-progress, completed, and dependent work | Visible to lead and teammates |
| Mailbox | Carries direct peer and lead messages | Targeted updates without routing every exchange through the lead |
There are no TeamCreate or TeamDelete commands to call. The team forms when Claude spawns the first teammate and cleans itself up when the lead session exits.
Start a useful team with a precise prompt
There is no swarm command to memorize. Describe the goal, ask for an agent team in those words, hand each teammate an independent responsibility, and say what evidence it must return. Claude can propose a team on its own, but Anthropic documents that it has to ask your approval before spawning anyone.
Create an agent team for this migration.
Use one teammate to inventory API callers, one to map database changes,
and one to design the verification matrix. Keep all work read-only.
Each teammate must report file and line evidence. Synthesize one plan only
after all three reports arrive.If Claude delegates to ordinary subagents instead, say it again and say it literally: an agent team, with shared tasks and peer messaging. Claude sizes the team and assigns the tasks from what you wrote, so a crisp decomposition steers it far better than telling it to use lots of agents.
Choose parallel work
Pick tasks that can progress independently, such as researching separate modules, testing competing hypotheses, or reviewing distinct layers.
Set ownership boundaries
Give each teammate a distinct file set, subsystem, or evidence question. Agent teams do not isolate teammates in worktrees, so overlapping edits can overwrite one another.
Define return evidence
Ask for test output, file paths, decision tables, or exact findings so the lead can reconcile results.
Let the lead synthesize
Wait for teammate reports before accepting the final answer. A fast lead response is not proof that every task completed.
Agent teams vs subagents
Both keep delegated work out of your main context. They solve different coordination problems. A subagent does its task and reports back to whoever called it. Teammates talk to each other and coordinate through a shared task list, so not every exchange has to route through the lead.
Choose the lighter coordination model that fits
| Question | Agent team | Subagent |
|---|---|---|
| Can workers message peers? | Yes, teammates can message one another directly | No, results return to the main caller |
| Is there a shared task list? | Yes | No team-wide shared list |
| Best fit | Several independent tasks that still need cross-worker coordination | A focused lookup, review, or implementation delegated from one conversation |
| Token cost | Higher because each teammate is a full Claude Code instance | Usually lower for bounded delegation |
| Lifecycle | Lead plus a managed team | One caller and one or more delegated workers |
Do not reach for a team because a subagent sounds less impressive. A team costs coordination overhead and a full context window per member. Use one when peer messaging or a shared dependency graph genuinely improves the result. For focused delegation, read Claude Code subagents.
Use in-process mode, tmux, or iTerm2 panes
In-process mode is the default. Teammates run inside the lead terminal and the agent panel appears below the main prompt. Use the arrow keys to select a teammate, Enter to view its session and send a message, and Escape to interrupt the current turn. Press x to stop a selected teammate and Ctrl+T to toggle the shared task list.
Split-pane mode gives each teammate its own visible terminal pane through tmux or iTerm2. The automatic mode picks panes when Claude Code detects a supported environment and drops back to in-process when it does not.
{
"teammateMode": "in-process"
}For one launch, use the experimental --teammate-mode flag. Anthropic notes that this flag does not appear in claude --help.
claude --teammate-mode auto| Mode | Use it when | Requirement |
|---|---|---|
| in-process | You want one terminal and keyboard switching between teammates | No multiplexer required |
| tmux | You want split panes through the multiplexer pathway | tmux, or supported iTerm2 detection through this mode |
| iterm2 | You use iTerm2 and want native panes | iTerm2 with the it2 CLI |
| auto | You want Claude Code to select panes when supported | Falls back to in-process when panes are unavailable |
Panes are a display choice, not a file-isolation mechanism. Four teammates in four panes still share one checkout. They need explicit ownership boundaries either way.
Agents view is not the agent teams view
Agent view is a separate research-preview dashboard for independent background sessions. It needs Claude Code v2.1.139 or later and opens with claude agents. It groups sessions by state (working, needs input, done), dispatches new work, and attaches you to whichever session you pick.
claude agentsAgent view puts every dispatched session in its own Git worktree so edits stay isolated. Team teammates belong to their lead and never appear as rows here. That distinction matters the moment a search result tells you to open agents view: it is not a hidden panel for watching your team.
| Feature | Agent teams | Agents view |
|---|---|---|
| Coordinator | A Claude team lead | You dispatch and attach from the dashboard |
| Isolation | No automatic worktree isolation | Automatic Git worktrees |
| Coordination | Shared tasks and peer messaging | Independent session queue |
| Visibility | In-process panel or split panes | Cross-session dashboard |
Watch parallel worktree sessions
Continuum covers the neighboring workflow: parallel coding-agent sessions spread across worktrees, including sessions that belong to no native Claude team. Each one stays visible with its own usage and rate-limit gauges. That helps when you deliberately want branch isolation, independent prompts, or a mix of agent tools.
A practical split: agent teams for tightly coordinated research inside one lead session, worktree-isolated sessions for implementation branches that must not overwrite each other. They complement each other. They are not interchangeable.
Know the current limits before you scale up
A team burns far more tokens than one session, because every teammate carries a full context. Start with the smallest team that produces real parallelism. When the work is sequential or lives in one file, coordination costs more than it saves.
Anthropic documents the rest of the rough edges. /resume and /rewind do not restore in-process teammates. Task status can lag, shutdown can be slow, a lead runs exactly one team, teammates cannot nest teams of their own, and the lead role cannot be handed over. Split panes do not work in every terminal.
The limitation that will actually bite you is simpler: no automatic worktrees. Two teammates editing one file overwrite each other, quietly. Give each a distinct file set, or keep the whole team read-only and move implementation into worktree-isolated sessions once collisions are plausible.
Questions people ask
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell environment or in the env object of Claude Code settings, then start Claude Code and explicitly ask it to create an agent team.
No. Anthropic currently labels agent teams experimental and disables them by default. You must opt in with the documented environment variable.
The team lead is the main Claude Code session. It creates or assigns tasks, coordinates teammates, receives updates, and synthesizes the final result.
Team teammates share a task list and can message peers directly. A subagent handles delegated work in its own context and returns the result to its caller without joining a peer-coordinated team.
Only if you ask for split panes. In-process mode is the default; split-pane display runs through tmux or iTerm2. Either way the display setting creates no source-control isolation.
Agents view is a separate dashboard opened with claude agents. It manages independently dispatched background sessions in automatic Git worktrees. Native agent-team teammates are not listed there as separate rows.
No. Anthropic explicitly says Agent Teams does not provide automatic worktree isolation. Assign non-overlapping files or use separate worktree sessions when edits could collide.
Not as a complete in-process team. Anthropic lists resumption as a current limitation: /resume and /rewind do not restore in-process teammates, so start new teammates after resuming the lead.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.
- Claude Code: orchestrate teams of sessions the experimental flag, display modes, and documented limitations
- Claude Code: run multiple agents how the parallelism options compare
- Claude Code: the agents view the separate worktree-isolated dashboard
- Claude Code: create custom subagents the lighter delegation model