Claude Code Agent Teams Review: When Parallel Agents Pay Off

Claude Code agent teams are worth enabling only when the work graph is wider than it is deep. Give 3 teammates disjoint file ownership, deterministic task gates, and a human merge gate; otherwise use subagents or one session and avoid roughly 7x plan-mode token usage.

The verdict: parallelism must beat coordination

Use agent teams when workers must exchange findings while owning separate deliverables. Use a single session for dependent work, and use Claude Code subagents when isolated workers only need to return a result to the lead.

That line matters because agent teams are not a faster version of every Claude Code task. They are a concurrency system. Each teammate is a separate Claude Code instance with its own context window. The benefit comes from running independent work at the same time. The cost comes from repeated context, coordination, integration, and review.

Anthropic's agent teams documentation recommends teams for research, review, independent modules, competing debugging hypotheses, and cross-layer work with separate owners. It recommends one session or subagents for sequential tasks, same-file edits, and dependency-heavy work. That is the production decision rule, not a suggestion to add more agents whenever a task feels large.

Shared tasks and direct messages are the actual feature

The shared task list and direct teammate messaging justify the extra cost. If workers do not need either, a team is the wrong topology.

The lead session creates work, assigns or exposes it for self-claim, and synthesizes the result. Teammates see pending, in-progress, and completed tasks. Dependencies keep blocked work from being claimed, and file locking prevents two teammates from claiming the same task at once. That lock protects task ownership, not source files. Anthropic separately warns that two teammates editing the same file can overwrite each other's changes.

Each teammate loads CLAUDE.md, configured MCP servers, skills, and its spawn prompt. It does not inherit the lead's conversation history. A vague spawn prompt therefore creates a context gap at exactly the point where the team is supposed to move independently.

Consider an illustrative authentication change in a SaaS repository. A clean split looks like this:

The lead prompt should include the API contract, protected paths, test command, and definition of done. Teammates can then message one another when the contract changes without routing every detail through the lead. If all communication still flows through the lead, subagents provide the cleaner design.

Plan approval is useful but easy to over-trust. A teammate can remain read-only until the lead approves its plan, yet Anthropic states that the lead makes that decision autonomously. Treat that as an internal coordination gate. A human still needs to approve architecture, risky permissions, and the combined diff.

The cost is roughly 7x in plan mode

Budget an agent team as several concurrent sessions, not as a free orchestration switch. Anthropic's Claude Code cost guidance says plan-mode teams use approximately 7x more tokens than standard sessions because every teammate maintains a separate context window.

Usage also scales with how many teammates remain active and how long they run. Anthropic recommends Sonnet for teammates, focused spawn prompts, small teams, and explicit shutdown when work is complete. Its practical starting range is 3-5 teammates with 5-6 tasks per teammate. Start at the bottom of that range. Add a teammate only when another independent lane exists.

Current Claude pricing gives a concrete budget envelope:

The cost formula is simple: input tokens divided by one million times the input rate, plus output tokens divided by one million times the output rate. The difficult part is attribution. Record the lead session, teammate name, task ID, model, start and stop time, tokens, files changed, test result, and review outcome. Without that join, a team can appear fast while hiding review time and discarded work.

Use /usage during a pilot to inspect session tokens and the local cost estimate. For API billing, Anthropic identifies the Claude Console Usage page as authoritative. The rollout metric should be accepted, tested change per unit of usage, not agents spawned or wall-clock speed alone.

A production rollout in five gates

The safe rollout is a narrow pilot with explicit ownership, deterministic completion checks, and a human-controlled merge. The feature can coordinate the work, but your repository still owns the release policy.

1. 1

   Gate the task shape

   Start with review, research, or a change that separates cleanly by directory. Reject the team topology if two workers need the same file or if most tasks wait on a single upstream decision.

   A useful launch prompt names 3 teammates and makes the boundary testable:

   Spawn an agent team with api-owner, ui-owner, and test-owner.
   Each teammate must edit only its assigned paths.
   Use the acceptance criteria in docs/auth-change.md.
   Do not implement a dependent task until its prerequisite is complete.
   Wait for every teammate, run the repository checks, and present one combined diff for human review.

2. 2

   Enable it at project scope

   Turn the experiment on in the repository's Claude settings so the choice is visible and reviewable. Keep the default in-process mode unless split panes provide a specific operational benefit.

   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     },
     "teammateMode": "in-process"
   }

   In-process mode works in any terminal. Split panes require tmux or iTerm2, add terminal-specific failure modes, and do not improve the agent architecture.

3. 3

   Constrain ownership and permissions

   Write the file map before spawning. A teammate may read shared contracts, but only one owner should edit a given path. Put generated files, migrations, lockfiles, and shared schemas behind a named integration task instead of letting every teammate touch them.

   Teammates inherit the lead's permission settings at spawn. Permission prompts surface in the lead session, and teammates cannot approve consent for one another. Do not launch the lead with --dangerously-skip-permissions. Pre-approve only the commands and paths the pilot actually needs, then review any exception yourself.

4. 4

   Make completion deterministic

   Use a TaskCompleted hook to stop a task from closing before the repository gate passes. Anthropic's hook reference says the hook fires on every completion attempt, does not support matchers, and feeds stderr back to the model when the command exits with code 2.

   Wire a repository-owned script in .claude/settings.json:

   {
     "hooks": {
       "TaskCompleted": [
         {
           "hooks": [
             {
               "type": "command",
               "command": ".claude/hooks/task-completed.sh"
             }
           ]
         }
       ]
     }
   }

   For a Node service, the hook can keep the rule small and inspectable:

   #!/usr/bin/env bash
   set -u
   
   if ! npm test; then
     printf 'Tests failed. Fix the task before completion.\n' >&2
     exit 2
   fi
   
   exit 0

   Replace npm test with the smallest deterministic check for the owned path. Keep full integration and security suites in CI, where results are durable and reviewable.

5. 5

   Integrate, review, and stop

   Tell the lead to wait until every teammate finishes. Check the task list against the actual diff because task status can lag. Run the full CI gate, review cross-file contracts, inspect permission-sensitive changes, and require a human merge decision.

   Then shut teammates down. Active teammates continue consuming tokens, and shutdown can wait for a current request or tool call. A completed diff is not a reason to leave the team alive while the reviewer works.

What breaks first

Resumption and coordination state break before raw code generation does. Anthropic documents these current limitations; design the pilot so a lost teammate or stale task marker is recoverable without trusting conversational memory.

The most important recovery artifact is not the transcript. It is a small task contract with owned paths, acceptance criteria, dependencies, and the last passing commit. A replacement teammate can work from that state without inheriting the lead's conversation, which it would not receive anyway.

Who should and should not enable it

Enable agent teams for senior engineers who can decompose work and own the integration cost. Do not enable them as a default for every developer or every ticket.

For a platform team, the first pilot should be a parallel review or competing-hypothesis debugging session. Those workloads produce evidence without combining several simultaneous code edits. Move to cross-layer implementation only after the team can attribute usage, enforce path ownership, block incomplete tasks, and review one coherent diff.

FAQ

How do you set up Claude Code agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in settings.json or the environment, then explicitly ask Claude Code to spawn named teammates with separate ownership. Start in the default in-process mode and keep the first team small.

What is the difference between Claude Code agent teams and subagents?

Subagents return results to the main session and do not talk to one another. Agent-team teammates communicate directly, share tasks, and coordinate independently, which is useful for collaborative work but costs more tokens.

Do Claude Code agent teams work on Windows?

Yes in the default in-process mode, which works in any terminal. Split-pane mode is not supported in Windows Terminal, so use the agent panel rather than tmux-style panes there.

Do Claude Code agent teams require tmux?

No. Tmux or iTerm2 is required only for split panes. In-process mode is the default and carries the same team coordination model.

How much do Claude Code agent teams cost?

Anthropic does not give one fixed run price because usage depends on models, context, teammate count, and duration. Its current guidance says teams in plan mode use approximately 7x more tokens than standard sessions, so enforce spend limits and inspect actual usage during the pilot.

Start the AI Coding Rollout

Roll out Claude Code, Codex, or both with repository context, permissions, hooks, evals, cost controls, and team handover.