Claude agent teams are an experimental Claude Code feature that lets one session act as a lead and spawn several other Claude Code instances that work in parallel, claim tasks off a shared list, and message each other directly. Anthropic shipped it disabled by default, behind an environment variable, and it needs Claude Code v2.1.32 or later. A lot of people saw the phrase in a release thread and filed it as a rebrand of subagents. It isn't one. A subagent reports back to its parent and then goes quiet, while a teammate on a Claude agent team stays alive as a full, independent session that can argue with the others.
That distinction is the whole point, and it is where most of the confusion lives. So this is what an agent team in Claude Code actually is, how to use Claude agent teams day to day, and when the thing earns its token cost.
What a Claude agent team actually is
The official docs describe four moving parts. The team lead is the session you started in. The teammates are separate Claude Code instances, and each one carries its own context window. The shared task list has pending, in-progress, and completed states, plus dependency tracking, so a blocked task cannot be claimed until its prerequisites finish. The mailbox is the messaging layer that delivers teammate-to-teammate notes automatically, without the lead having to poll for them.
The lead does not write all the code. It plans, breaks the work into tasks, spawns teammates, and pulls together what comes back. Teammates either get tasks assigned by the lead or self-claim the next unblocked one when they finish, and file locking keeps two of them from grabbing the same item at once.
Everything lives on disk under your home directory: team config at ~/.claude/teams/{team-name}/config.json, task list at ~/.claude/tasks/{team-name}/. Claude Code writes these itself. Do not hand-edit the config; it holds live runtime state like session IDs and tmux pane IDs, and your edits get overwritten.
How to activate Claude agent teams
It stays off until you flip one switch. Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Check your version first with claude --version. Anything older than v2.1.32 will not have it. That is the entire Claude agent team config you need. There is no project-level team file you author by hand, and a .claude/teams/teams.json in your repo is treated as an ordinary file rather than configuration.
After that, you ask in plain language. Tell Claude to create a team and describe the task and the roles, something like "create an agent team to review PR #142, one teammate on security, one on performance, one on test coverage." Claude spawns the teammates, runs the work, and cleans up when it is done. It can also propose a team on its own, and it always asks before spawning anything.
To watch and steer, the lead's terminal lists every teammate and what each is doing. Press Shift+Down to cycle through teammates and type to message one directly; after the last teammate it wraps back to the lead. Ctrl+T toggles the task list. For one pane per teammate, set teammateMode to tmux in ~/.claude/settings.json, or pass claude --teammate-mode in-process for the simpler view. Split panes need tmux or iTerm2 and do not work in VS Code's integrated terminal, Windows Terminal, or Ghostty.
A note on the "Claude agent team delegate mode" phrasing floating around. The official docs treat delegation as a behavior of the lead, but I could not find an officially named "delegate mode" toggled by Shift+Tab in Anthropic's documentation as of June 2026. Several third-party guides describe it that way. In the actual docs, Shift+Tab is the standard permission-mode cycle (default, acceptEdits, plan), and you keep the lead coordinating rather than coding by telling it to in words or by giving teammates explicit file boundaries. Treat any Shift+Tab delegate-mode claim you read elsewhere as unconfirmed until it shows up on code.claude.com.
Claude agent teams vs subagents
Both let you parallelize. What separates them is whether your workers ever need to talk to each other.
A subagent spawns inside your single session, does a focused job, and reports a summary back to the main agent. It never talks to another subagent, and your main context stays cheap because only that summary comes back. The subagent basics cover this model, and for most delegation it is still the right tool.
A teammate on an agent team is built differently. It is fully independent, keeps its own context for the whole run, and can message any other teammate by name. The coordination is decentralized, so teammates share a task list and self-organize instead of routing every decision through one main agent. Anthropic's own comparison table puts subagents at lower token cost with results summarized back, and agent teams at higher cost because each teammate is a separate Claude instance.
So here is the practical read. Reach for subagents when you want quick, disposable workers and only care about their output. A Claude agent team earns its keep when the workers need to share findings, challenge each other, and converge on an answer. The canonical example in the docs is a five-teammate debugging session, where each agent investigates a different hypothesis and tries to disprove the others. That beats one agent anchoring on the first plausible cause, and you cannot build it with subagents at all, because subagents have no way to disagree with each other.
The broader orchestration playbook (parallel sessions, git worktrees, and how to structure multi-agent runs) is its own subject in Claude Code multi-agent workflows.
When a team helps and when it is overkill
Teams shine on four shapes of work, per the docs: research and review, building separate new modules in parallel, debugging with competing hypotheses, and cross-layer changes where frontend, backend, and tests each get an owner. The common thread is that the pieces are independent and benefit from being explored at the same time.
They are a bad fit for sequential work, edits to the same file, or anything with a long dependency chain. Two teammates editing one file will produce overwrites, and a pipeline where step three needs step two's output gains nothing from five agents sitting idle. The cost is also real. Token usage scales linearly with active teammates, because each one is a separate Claude instance burning its own context, so for routine tasks a single session is cheaper and faster.
If you do reach for a team, the docs suggest 3 to 5 teammates and 5 to 6 tasks each. In my experience three focused teammates beat five scattered ones every time. Start with read-only work like a PR review or a library investigation before you let a team write code in parallel, since review work shows you the upside without the file-conflict headaches.
One thing the feature does not solve: each teammate still needs to know its job. The lead can spawn a security reviewer, but "review for security" only works if the agent already carries the standards, the threat model, and the file boundaries you care about. You can stuff that into a spawn prompt every time and hope you phrase it the same way, or define the role once and reuse it. Agent teams already let you point a teammate at a subagent definition. A more portable form is a packaged skill: a skill built with Knack is a SKILL.md folder you hand to any agent, lead or teammate, and it runs the same way in Claude Code, the Claude apps, Codex, Cursor, or Gemini CLI. A team is only as good as the job description each member carries in.
The honest caveat is that this is experimental, and Anthropic labels it so. Session resumption does not restore in-process teammates, task status sometimes lags behind reality, and you can run only one team at a time, with no nested teams and no way to transfer leadership. So treat a team as a powerful tool that you actively supervise. Watch the lead so it does not quietly start coding instead of delegating, and tell it to wait for teammates when it gets impatient.
Turn it on for your next big parallel review and message a single teammate mid-run. That one interaction, where you are talking to an agent that is not the one you started with, is the part no amount of documentation conveys.