Skip to content
Mia Automation
NLEN Sign in Put Mia to workGet started

Claude Code Agent Teams: Setup, a Real Test, and When They're Worth It

Agent teams let one Claude Code session act as a lead that spawns teammates, each in its own context, who share a task list and message each other. They're experimental: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and ask for a team in an interactive session. We ran two tests. Three reviewers found 24 issues in an invoice module where one session found 12, at seven times the token cost. Two builders, each owning one file, fixed the rounding without a single collision.

Claude in practiceUpdated 6 min read

Tested by us on 11 November 2026.

Animated diagram: a team lead sends one invoice module to three teammates in turn, vat-math, dates-reminders and tests-review, whose findings are merged into one list of 24 items

Turn agent teams on

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

In ~/.claude/settings.json, or export the variable in your shell.

  • Interactive only. With claude -p, Claude doesn't spawn teammates; named helpers run as ordinary subagents.
  • Teams can form on their own. While the setting is on, a helper Claude names launches as a teammate, even if you didn't ask for a team.
  • Display. By default teammates run inside your terminal; arrow keys pick one in the agent panel, Enter opens it. Split panes need tmux or iTerm2.
  • Limits. One team per session, no nested teams, and /resume doesn't bring in-process teammates back.

Our test: three reviewers on one invoice module

We wrote a 15-line Python module with four functions (invoice number, due date, total with VAT, reminder check) and two passing tests. Then we started Claude Code 2.1.321 interactively with agent teams on, in auto mode, and sent this prompt:

text
Create an agent team to review factuur.py before we use it for real invoices. Spawn three teammates: one checks the VAT and rounding math, one checks dates and reminders, one checks the tests. Each reports problems with a severity. Don't edit any files. When all three are done, give me one combined list.

The lead created three teammates named vat-math, dates-reminders and tests-review, waited for all three and merged their reports into one list: 2 critical, 6 high, 9 medium and 7 low. All three reviewers ran small pieces of code to prove their points, and nobody edited a file. /usage reported 1 minute 18 seconds of model time and $0.35 in token cost.

Team versus one session

We then gave one ordinary session the same review in one prompt, without a team.

Same module and the same question in one prompt, November 11, 2026. One run each.
Agent team (lead + 3)One session
SetupInteractive session, auto mode, Sonnet 5.5 for lead and teammatesclaude -p, auto mode, Sonnet 5.5
Findings24: 2 critical, 6 high, 9 medium, 7 low12: 3 high, 5 medium, 4 low
Model time1 min 18 s17 s
Token cost (from /usage and the JSON result)$0.35$0.05
Found the date/datetime crashYes, by running itNo
Found the float rounding bugYes, with two examplesYes, with one example

Count the findings by weight and the gap shrinks. Both found the rounding bug, the missing per-line VAT rates and the thin tests. The team rated the missing tests as critical; the single session called them medium. Most of the team's extra items were real but small: test hygiene, a shadowed parameter name, the invoice year around New Year. One finding separated the two on substance: give the reminder check a due date with a time in it and it crashes with a TypeError. We checked that one and the rounding bug with Python on a Windows PC, and both held.

PowerShell window checking two team findings: the invoice total for five items at 0.50 with 21% VAT returns 3.02 instead of 3.03, and the reminder check crashes with a TypeError when the due date has a time (opens at full size)

Second test: two builders, one file each

Review is the easy case, because nobody writes. So we also had a team change code, with the rule that prevents collisions: one owner per file. The prompt named two teammates. code could change only factuur.py, to switch the total to Decimal with half-up rounding. tests could change only test_factuur.py, adding tests including 5 × €0.50 at 21% giving 3.03.

Both finished in 52 seconds of model time and $0.18 in tokens. Neither touched the other's file, and the lead ran the suite afterwards: 10 tests, all passing. The lead also caught what ownership can't prevent. The total now returns a Decimal instead of a float, so every caller has to change. Splitting files stops overwrites; it doesn't stop one teammate from changing what the other depends on. Put the shared interface in the spawn prompt.

When a team is worth it

  • Yes: reviews and research where separate angles find different things, like our three reviewers. Anthropic recommends starting there, because nobody edits files.
  • Yes: new features with clearly separate parts, such as front end, back end and tests, each owned by one teammate.
  • No: sequential work, small fixes, or two people editing the same file. A single session or a subagent is cheaper and avoids overwrites.
  • Size: we tested teams of two and three; both stayed easy to follow. Anthropic suggests three to five teammates with five or six tasks each. We haven't tested five, so we'd start with two or three and add one only when a separate angle is missing.

How we split parallel work

We run many agents side by side outside Claude Code's team feature, as separate workers with a coordinator. In five weeks that came to 441 groups of parallel workers. Three rules carry most of the weight. Every worker writes only in its own folder; changes elsewhere arrive as a patch with a note. Workers never deploy, restart or send anything; the coordinator does that after checking. And when the last worker in a group finishes, the coordinator gets a fresh turn with a task written down in advance: merge, test, deliver.

text
Goal: <one sentence>
You write ONLY in: <folder>. Changes elsewhere: deliver a patch in your folder, with a note.
Don't: deploy, restart, email, publish.
Done = <measurable check>. Final report: first line "Done." or "Not done: <reason>".

The first lines of every task we hand to a parallel worker. They work as a spawn prompt for a teammate too.

We also cap how many agents run at once and check free memory before each new one starts. On one server in October 2026, too many agents at once got processes killed. Since then new agents wait in a queue instead.

Questions

How do I enable agent teams in Claude Code?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your settings or shell, start an interactive session and ask Claude to create a team with the teammates you want.

What's the difference between agent teams and subagents?

Subagents report back to the main session and don't talk to each other. Teammates share a task list, message each other directly and can be addressed by you one by one. Teams use more tokens.

How much do agent teams cost?

Each teammate is a full session with its own context, so cost grows with team size. In our test, a lead with three reviewers used about seven times the tokens of one session doing the same review.

Do agent teams work with claude -p?

No. Teammates only spawn in interactive sessions. In -p mode, named helpers run as regular subagents.

Sources