Claude Code Agent Teams vs Parallel Worktree Sessions

Published July 24, 2026 · by the AQ team

Agent teams are Claude Code's experimental built-in way to run several Claude sessions as one coordinated unit: a lead session spawns teammates, work flows through a shared task list, and agents message each other directly. The feature is disabled by default and enabled with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable. The alternative most engineers already use is simpler: several independent Claude Code sessions, each in its own git worktree. As of July 2026 the practical split is this: agent teams win when the work benefits from agents talking to each other (parallel research, multi-lens review, competing debugging hypotheses), while independent worktree sessions win on cost, predictability, and recoverability for work you can cleanly divide up front.

What agent teams actually is

Anthropic shipped agent teams in early February 2026 alongside Claude Opus 4.6, and the feature remains marked experimental as of July 2026. One Claude Code session acts as the team lead: it breaks the job into tasks, spawns teammates, assigns or lets them claim work, and synthesizes the results. Each teammate is a full, independent Claude Code instance with its own context window. Teammates load your project context (CLAUDE.md, MCP servers, skills) like any fresh session, but they do not inherit the lead's conversation history: everything task-specific has to travel in the spawn prompt.

The difference from Claude Code's older subagents feature is communication. Subagents only report results back to the session that spawned them. Agent team members message each other peer to peer through a mailbox system, and you can open any teammate's session and talk to it directly without going through the lead. That is the entire value proposition.

Enabling it and starting a team

Turn the feature on in your settings.json or shell environment:

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

There is no team configuration file to write. You describe the team you want in natural language and the lead spawns it:

Spawn three teammates to review PR #142:
- one focused on security implications
- one checking performance impact
- one validating test coverage
Have them each review and report findings.

Claude sometimes spawns subagents instead of a team, so ask for an agent team explicitly if coordination matters. There is no hard limit on team size, but the docs recommend starting with 3 to 5 teammates and sizing work at roughly 5 or 6 tasks per teammate. You can pin teammate models ("use Sonnet for each teammate"), require plan approval before a teammate edits anything, and enforce quality gates with the TeammateIdle, TaskCreated, and TaskCompleted hooks.

How the coordination works

Three mechanisms hold a team together, all local files under your home directory:

• The shared task list (stored under ~/.claude/tasks/) holds work items with three states: pending, in progress, completed. Tasks can depend on other tasks, and a task with unresolved dependencies cannot be claimed. Claiming uses file locking so two teammates cannot grab the same task.
• Mailboxes (JSON files under ~/.claude/teams/) carry messages between agents. Delivery is automatic, and an idle teammate notifies the lead when it finishes.
• The team config tracks members and runtime state. It is removed when the session ends; the task list persists locally so a resumed session keeps its tasks.

By default all teammates run in-process inside your one terminal, with an agent panel for selecting and messaging them. A split-pane mode gives every teammate its own pane instead, but it requires tmux or iTerm2 and is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty as of July 2026.

The token cost profile

Every teammate is a separate Claude instance with its own context window, so cost scales roughly linearly with team size, and Anthropic's cost documentation states that agent teams use approximately 7x more tokens than a standard session when teammates run in plan mode. The same docs suggest Sonnet for teammates, small teams, lean spawn prompts, and shutting teammates down promptly, because each active teammate keeps consuming tokens until it exits.

The ceiling is real but expensive. Anthropic's own engineering team demonstrated the extreme: 16 parallel Claude agents built a 100,000-line C compiler in Rust, capable of compiling the Linux 6.9 kernel, across nearly 2,000 sessions and roughly $20,000 in API costs. Impressive, and also a useful calibration: coordinated agent swarms buy wall-clock speed with tokens, not efficiency. For routine tasks, one session is more cost-effective, and Anthropic says so directly.

The alternative: independent sessions in git worktrees

Before agent teams existed, engineers parallelized Claude Code the manual way, and it still covers most real workloads: run several ordinary sessions at once, each in its own git worktree so file edits never collide. Claude Code has this built in now:

# Terminal 1: an isolated worktree and branch for the auth feature
claude --worktree feature-auth

# Terminal 2: a second session that cannot touch the first one's files
claude --worktree payment-bug

Each command creates a worktree under .claude/worktrees/ on its own branch; Claude offers cleanup on exit. Nothing coordinates the sessions: you are the task list. That is a feature as much as a limitation. Each session is independently resumable, independently priced, and independently disposable; a confused session gets killed without taking anything else down. Our guide to running multiple Claude Code sessions in parallel covers this workflow in depth.

When each approach wins

Agent teams earn their overhead when the agents need to talk: research where findings should be challenged, review where several lenses examine one diff, debugging where competing hypotheses race to disprove each other. Worktree sessions win when tasks are separable and results just need merging: unrelated bug fixes, a mechanical refactor swept across modules. They also win when token budget is tight or you cannot afford experimental rough edges. The two compose, too: nothing stops you from directing teammates into worktrees, and the docs recommend splitting file ownership so teammates never edit the same file.

Limitations to know before relying on it

Anthropic's documentation is candid about the rough edges, as of July 2026: /resume and /rewind do not restore in-process teammates, so a resumed lead may message teammates that no longer exist. Task status can lag when a teammate fails to mark work complete, blocking dependent tasks. There is exactly one team per session, teammates cannot spawn their own teammates, the lead cannot be changed, and teammates start with the lead's permission mode, permissive flags included. Teammates can also stop on errors rather than recovering, so the docs advise against letting a team run unattended for long.

None of that makes the feature bad. It makes it experimental, which is exactly what the flag says.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ sits on the parallel-sessions side of this guide, and turns the manual pattern into something a whole team can see. Every workspace gets its own isolated git worktree (branch ai/{id}-{slug}, dependencies installed automatically, one-click rebase onto main), so the isolation discipline this guide describes is the default rather than a habit. Agents run as real CLIs, Claude Code included, in persistent tmux sessions on your team's VM, streamed live to the browser: sessions keep running when your laptop closes, resume from any device, and teammates can open the same workspace to watch and steer the same live session.

The coordination layer that agent teams handles with a task list, AQ handles with humans in the loop: each parallel effort is a visible workspace, agents commit and open PRs with per-user GitHub auth, PRs are tracked per workspace, and a Linear issue labeled ai-task becomes a workspace with status syncing both ways. Each engineer signs into Claude Code with their own account, and AQ never marks up model usage, which matters when you are deliberately multiplying token spend across parallel sessions.

Plainly: if one engineer wants five Claudes debating a root cause inside one terminal, agent teams is the tool. AQ is for the durable version of parallel agent work: long-running sessions on your own infrastructure that a whole team can observe, share, and pick up from anywhere. The Free plan is the full product on a VM you bring (you pay only your cloud provider); the Team plan is $100 per user per month (promotional, standard $200, billed monthly) with a dedicated always-on AQ-managed VM in its own isolated network and your rate locked for your first 12 months.