Claude Code Agent Teams: when parallel agents pay off, what they cost, how to check them

Agent Teams arrived in Claude Code on 5 February 2026, together with Claude Opus 4.6 (TechCrunch). Nine months later the official documentation still calls it experimental. Turning it on takes one setting. The harder decisions are when a team is worth five times the tokens, and how you find out whether its work is right.

What Claude Code agent teams are

A normal Claude Code session is one agent with one context window. A Claude Code agent team is several full sessions working on the same project at the same time. The docs name four parts:

• The lead: your main session. It creates tasks, starts teammates and puts the results together.
• The teammates: separate Claude Code instances, each with its own context window.
• The task list: shared work items that are pending, in progress or completed. A task can wait for another one.
• The mailbox: any agent can message any other agent by name.

The difference from subagents is who talks to whom. A subagent does one job and reports back to the session that started it. Teammates message each other, challenge each other’s findings and claim the next open task on their own. Each one loads the project context (CLAUDE.md, MCP servers, skills) but not the lead’s conversation, so all it knows is the project and the brief the lead gave it.

Claude Code now has three ways to run agents in parallel, and the choice matters for cost:

Where parallel agents pay off

The docs name four strong cases.

Parallel review: one reviewer drifts toward one kind of problem. Three teammates with separate lenses, security, performance and test coverage, read the same change at once, and the lead merges their findings.

Competing hypotheses: when the cause of a bug is unclear, one agent finds a plausible story and stops looking. The docs call this anchoring. Giving three to five teammates one theory each, with the instruction to disprove each other, keeps the search open.

Features cut into modules: backend, frontend and tests, each owned by one teammate. This works only if the parts really are separate.

Research before code: a library comparison or a bug investigation writes no code, so nothing can collide. The docs recommend starting there.

For sequential work, many dependencies or changes concentrated in one file, the docs advise a single session.

What agent teams cost

Every teammate is a full Claude instance. Anthropic’s cost page says token use is roughly proportional to team size and grows with how long each teammate runs. On the API that is the bill. On a Team or Enterprise seat it is your usage limit, drawn down several times as fast.

Four settings decide most of the bill:

• Model per teammate: name it in the brief (“use Sonnet for each teammate”). The cost page recommends Sonnet for teammates and the stronger model for the lead.
• Team size: start with 3 to 5 teammates and 5 to 6 tasks each. Three focused teammates beat five scattered ones.
• Shutdown: an idle teammate keeps its context until it exits. Stop it when its work is done.
• Cache: a teammate’s prompt cache lasts five minutes by default. A teammate that waits longer pays to rebuild it. subagentPromptCacheTtl set to 1h keeps it longer, at a higher write price on the API.

The rule we use: a team is worth it when the work would otherwise wait in a queue. If one session can do it in an afternoon, a team only makes it more expensive. What tokens cost in a business, with worked examples, is in what running Claude costs.

How to check what a team built

A bigger team produces more output, and nothing in the setup makes that output more correct. The lead summarises, and a summary is the writer’s opinion of what mattered. What decides quality is who checks the result, and against what.

The first check is a grader that did not do the work. After the team finishes, a separate agent with a fresh context and read-only access scores the change against a short list of criteria: tests pass, the brief is met, no file outside the agreed scope changed. It can run on the same model with the same prompts; what makes it useful is that it has no work of its own to defend. I call this loop engineering, and it is how we run agents in client systems.

The second is hooks. Claude Code fires TaskCreated, TaskCompleted and TeammateIdle. A hook that returns exit code 2 stops the task and sends feedback. A test run, a lint or a check that the teammate only touched its own files belongs there. Plan mode is no substitute: Claude Code approves a teammate’s plan automatically unless you change its permission mode, so the plan makes the teammate think first without anyone reviewing it.

The third is permissions. Teammates inherit the lead’s permission mode. If the lead runs with all permission prompts skipped, so does every teammate. Decide the allowed commands before the team starts, not while five agents wait for approval.

Where agent teams break

Two agents, one file. The task list is locked so two teammates cannot claim the same task. Your source files are not. If two teammates edit one file, the later write wins. Teammates also do not get separate git worktrees. The fix is planning: each teammate owns a set of files, and a second edit to the same file waits for the first.

Resume. /resume and /rewind do not bring back in-process teammates. After a resume, the lead may message teammates that no longer exist. Tell it to start new ones.

Stale task status. Teammates sometimes forget to mark a task done, and everything that waits on it stays blocked. Check the work and update the status, or ask the lead to nudge.

A lead that codes instead of leading. Sometimes the lead starts doing tasks itself. The docs’ fix is one sentence in the brief: “Wait for your teammates to complete their tasks before proceeding.”

Fixed shape. A session has one team, teammates cannot start teams of their own, and the lead stays the lead until the session ends.

Swarms, and when one agent wins

Beyond teams are swarms. Since May 2026 Claude Code can run dynamic workflows: Claude writes a script, and a runtime starts many subagents from it. The keyword ultracode in a prompt starts one. Limits by default: 16 agents at once, 1,000 per run, with a warning above 25 agents or about 1.5 million tokens.

I ran one with about 200 subagents, each with its own idea for raising an eval score. I took two things from it. First, check the model: some subagents ran on Haiku instead of Opus, with no error, just weaker work. Name the model in the prompt. Second, the brief matters more than the count. A vague prompt returned 200 versions of the same idea, while a sharp role and one thesis per agent returned results worth reading. A precise run with 20 agents beats a vague one with 200.

Every handoff between agents is a summary, and a summary drops what its writer thought was minor. An agent that filters out cancelled orders before passing data on leaves the next agent blind to them. The final answer then looks right and is wrong. When the details connect, one agent that sees the raw data, the rules and the question at once beats a team passing notes.

Setup in two minutes

Agent teams stay hidden until one environment variable is set, best in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then describe the roles in plain language:

Create an agent team for the auth refactor: one teammate on the
backend JWT logic, one on the frontend session handling, one writing
integration tests. Use Sonnet for each teammate.

Two details catch people. While teams are on, a subagent that Claude names starts as a teammate, so a team can form without you asking; set the variable to 0 to switch back. And teams need an interactive session: claude -p and Agent SDK sessions do not start teammates. Teammates show in a panel below the prompt; the arrow keys select one, x stops it, Ctrl+T shows the task list. Split panes need tmux or iTerm2.

What this means for a business

Agent teams are a developer feature. They make a certain kind of work faster: a review with three angles, a bug hunt, a feature cut into clean pieces. An unclear task stays unclear, and a team with a vague brief spends five times the tokens on it.

Before anyone runs a team on your code, three answers should be clear. Which agent owns which files? What checks the result that did not produce it? Who decides when the team stops? With those answers, a team saves days on the right task. Without them, one well-briefed session is cheaper and safer.

That structure, agents with clear limits, a separate check and a stop condition, is what we build in AI agent development. If you first want to know which of your processes split cleanly enough for parallel agents, start with AI consulting.