Claude Code Agent Teams: Advanced Multi-Agent Workflows in Practice

What Is Claude Code Agent Teams?

Claude Code Agent Teams is a multi-agent orchestration feature built into Claude Code's CLI. Instead of a single agent working through tasks sequentially, Agent Teams allows an orchestrator agent to break a large task into subtasks, spawn specialized sub-agents to work on each subtask in parallel, track dependencies between tasks to prevent conflicts, and synthesize results once subtasks complete.

The feature was introduced as part of Claude Code's broader push toward agentic software development — the idea that AI should be able to handle not just single-file edits or simple bug fixes, but large-scale software projects that would realistically take a human developer days to complete.

It operates entirely within the existing Claude Code CLI — no separate configuration or new tool to install. You invoke it by asking Claude Code to work on a sufficiently complex task with a prompt that implies parallelizable work, or by explicitly requesting team mode with /team.

How We Tested

We tested Agent Teams against single-agent mode on five real-world projects over two weeks in February–March 2026. Our primary metrics were wall-clock time to task completion, correctness of output (manual review), and token consumption.

Projects used:

• Next.js 16 app refactor (~50K lines): Migrating from Pages Router to App Router across 40+ page components
• API integration suite: Implementing 8 independent third-party API integrations (Stripe, SendGrid, Twilio, etc.) from scratch
• Python monorepo test coverage: Writing unit tests for 12 independent service modules (no shared state between modules)
• Documentation generation: Generating JSDoc/TSDoc for all exported functions in a 30K-line TypeScript SDK
• Bug triage and fix batch: Fixing 25 open GitHub issues from varying priority levels, some related, some independent

All tests run on Claude Code Max tier (20x) with Sonnet 4.6 as the default model. Agent Teams configured to use up to 5 simultaneous sub-agents (the practical sweet spot in our experience).

How Agent Teams Works: Orchestrator and Sub-Agents

The Agent Teams architecture has two layers:

The Orchestrator

When Agent Teams mode activates, the main Claude Code session becomes the orchestrator. It does not edit files directly — its job is planning, delegation, and synthesis. The orchestrator:

• Reads the project context and the task description
• Breaks the task into a list of subtasks with explicit dependency relationships (e.g., "Task B cannot start until Task A is complete")
• Writes the task list to a shared in-memory structure accessible by all agents
• Spawns sub-agents and assigns them tasks from the queue
• Monitors sub-agent progress and handles errors or blockers
• Reviews and validates completed subtasks before marking them done
• Synthesizes a final summary of what was changed

Sub-Agents

Sub-agents are lightweight Claude Code instances that receive a single well-scoped task from the orchestrator and execute it. Each sub-agent:

• Gets a task description and a set of files it is authorized to modify
• Reads only the files relevant to its task (not the full project)
• Executes its task, writes files, and can run shell commands within its authorized scope
• Reports completion status and a summary of changes to the orchestrator
• Can request help from the orchestrator if it encounters a dependency it cannot resolve

File-level locking prevents two sub-agents from writing to the same file simultaneously. If Sub-Agent A is modifying auth/middleware.ts and Sub-Agent B also needs to modify it, Sub-Agent B will wait until A finishes and then re-read the updated file before making its own changes.

Shared Task Lists and Dependency Tracking

The shared task list is the coordination backbone of Agent Teams. It is a structured list of tasks with the following properties for each:

The depends_on field is the key to correct multi-agent behavior. If your task involves implementing a new data model and then updating all API endpoints to use it, the orchestrator creates a "create data model" task and 5 "update endpoint X" tasks that all depends_on the model task. The endpoint tasks stay in pending until the model task reaches completed, then all 5 run in parallel.

In our testing, the orchestrator's dependency graph construction was accurate for well-structured tasks about 85% of the time. The remaining 15% involved subtle shared-state dependencies the orchestrator missed — for example, two tasks that both modify a shared configuration object but were not flagged as dependent. These cases caused merge conflicts that the orchestrator then had to resolve in a cleanup pass. Not a showstopper, but it means you should review the generated task list before approving it for execution on complex projects.

Message Passing Between Agents

Sub-agents communicate through structured messages written to the shared task list. When a sub-agent needs context from another agent's completed work, it reads the result field of the dependency task. When it needs something it cannot resolve on its own — a design decision or a missing requirement — it writes a blocker message to the orchestrator.

Direct sub-agent-to-sub-agent communication is not supported. All coordination goes through the orchestrator. This keeps the system simpler and prevents circular dependency deadlocks, but it means the orchestrator can become a bottleneck if many sub-agents hit blockers simultaneously.

In practice, well-scoped subtasks rarely need to message back to the orchestrator mid-execution. The blocker pattern is most useful when the orchestrator's initial task decomposition was imprecise and a sub-agent encounters an ambiguity. For example: "Task says to add pagination to the user list endpoint — but there are three user list endpoints, which one?" The sub-agent blocks, the orchestrator resolves the ambiguity, and all three sub-agents working on different endpoints get the clarification.

Real Use Cases: Where It Actually Helps

Agent Teams delivers the most value on tasks that are large and genuinely parallelizable — where subtasks are independent of each other or have clear, simple dependency relationships.

1. Implementing Multiple Independent Features

In our API integration test, we asked Agent Teams to implement 8 third-party API integrations (Stripe, SendGrid, Twilio, Slack, GitHub, Linear, PagerDuty, Datadog). Each integration was a self-contained module with no dependencies on the others. Agent Teams spawned 5 sub-agents and processed all 8 integrations in two waves of parallel execution, completing in 22 minutes. Single-agent mode took 1 hour 41 minutes on the same task.

The 4.6x speedup on this task was the best we saw across all tests — it was the ideal scenario for Agent Teams because the subtasks were truly independent.

2. Large-Scale Refactors With Isolated Components

Our Next.js Pages-to-App Router migration involved 40+ page components. The orchestrator analyzed the component dependency graph, identified which components could be migrated independently, and assigned groups of 4–5 components to each sub-agent. Components with shared utility imports were handled last, after all dependencies were migrated.

Agent Teams completed this migration in 47 minutes vs 3 hours 20 minutes for single-agent mode (4.3x faster). The orchestrator's dependency analysis was accurate for 37/40 components; three required manual intervention because they shared non-obvious state through a global context provider.

3. Test Suite Generation Across Independent Modules

Generating unit tests for 12 independent service modules (no shared state) is a perfect Agent Teams use case. Each module is a self-contained subtask. Sub-agents generated tests in parallel, the orchestrator reviewed coverage summaries, and the full suite was complete in 18 minutes vs 1 hour 22 minutes for single-agent mode.

4. Documentation Generation at Scale

Documentation is highly parallelizable because each function's documentation can be generated independently. Agent Teams assigned batches of exported functions to sub-agents (roughly 50 functions per sub-agent) and generated full JSDoc for a 30K-line TypeScript SDK in 31 minutes. Single-agent mode would have taken 2–3 hours.

Speed and Performance: Single Agent vs Team

The speedup is consistently 4–5x on highly parallelizable tasks. The bug fix batch showed a lower 2.4x speedup because many bugs had inter-dependencies — fixing one bug required understanding the context of another — which forced the orchestrator to run more tasks sequentially than in parallel.

Important: speedup is in wall-clock time, not cost. Token consumption scales nearly linearly with agents spawned. You are not getting work done cheaper — you are getting it done faster at the same or higher token cost.

Cost: What Agent Teams Actually Costs

Agent Teams is a Max-tier feature in practical terms. The token consumption in 5-agent team mode runs roughly 4.5x higher per minute than single-agent mode. Pro tier ($20/month) limits are consumed very quickly — a two-hour Agent Teams session on a large task can exhaust a significant fraction of your monthly Pro allocation.

For most developers, the practical path is: use single-agent mode for daily work, activate Agent Teams for the occasional large batch job (migrating a codebase, generating tests for a new module, implementing a new feature set) on Max tier.

Agent Teams vs Single Agent: When to Use Each

The decision comes down to task structure, not task size.

Honest Limitations

Agent Teams is genuinely impressive on the right tasks, but it has real limitations that are worth knowing before you rely on it.

• Dependency graph accuracy is not perfect. The orchestrator correctly identifies task dependencies about 85% of the time on complex projects. The 15% misses require human review and intervention. On large migrations, always review the generated task list before approving execution.
• File locking can create bottlenecks. If many sub-agents all need to write to a shared configuration file (like a central router or a types declaration file), they queue up waiting for locks. In our Next.js migration, the app/layout.tsx file became a bottleneck because every component migration needed to reference it.
• Orchestrator context grows large on long sessions. The orchestrator tracks all sub-agent results in its context. On very long sessions with many completed tasks, the orchestrator's context can approach limits, causing it to compact task history. This occasionally loses nuance from early task results.
• Hard limit of 10 simultaneous sub-agents. For very large tasks (100+ file migrations), you need multiple sequential team sessions rather than one massive parallel run. The 200-task limit on the shared task list also applies.
• Sub-agents cannot spawn their own sub-agents. The hierarchy is flat: one orchestrator, N sub-agents. If a sub-agent encounters a large sub-task, it must complete it sequentially or report back to the orchestrator for further decomposition. This limits the depth of parallelism available.
• No cross-repository coordination. Agent Teams operates within a single repository. If your task involves coordinated changes across multiple repos (a monorepo with separate packages, or a microservices system with separate repos), you need separate sessions per repo with manual coordination between them.

Verdict

Claude Code Agent Teams delivers on its core promise: it dramatically reduces wall-clock time on large, parallelizable development tasks. The 4–5x speedup on genuinely independent subtasks is real and reproducible. For teams or individual developers who work on large codebases with regular batch work — feature sprints, codebase migrations, coverage improvements — Agent Teams is a meaningful productivity multiplier.

The caveats are equally real. Agent Teams is a Max-tier feature in practice, not Pro. The orchestrator's dependency analysis requires human review on complex tasks. And the 8-point sequential reasoning advantage of single-agent mode means Agent Teams should not replace single-agent for tasks that are fundamentally sequential — deep debugging, architectural decisions, complex refactors that touch cross-cutting concerns.

The clearest signal for when to use it: if you can describe your task as "do X for each of these N independent things," Agent Teams is the right choice. If your task is more like "figure out why this complex bug happens," stay with single-agent mode.

For context on how single-agent Claude Code performs and how it compares to other terminal AI tools, see our Claude Code vs Cursor comparison and our Claude Code vs Copilot CLI guide.

FAQ

How many sub-agents can Claude Code Agent Teams run simultaneously?

The hard limit is 10 simultaneous sub-agents. In practice, 3–5 agents is the sweet spot — beyond that, coordination overhead and context management complexity can offset the parallelism gains. The orchestrator manages spawning and will queue tasks if the limit is reached.

How much does Agent Teams cost vs single-agent mode?

Token consumption scales proportionally with active sub-agents — a 5-agent team uses roughly 4.5x the tokens per minute vs single-agent mode. This makes Agent Teams practical on Max tier ($100–200/month) rather than Pro ($20/month). On a per-task basis, you get 4–5x faster completion for roughly the same total token cost as a slower single-agent session.

What is the difference between Agent Teams and single-agent mode?

Single-agent: one Claude instance executes everything sequentially. Agent Teams: an orchestrator plans the work, spawns specialized sub-agents for parallel execution, tracks dependencies, and synthesizes results. Agent Teams wins on speed for parallelizable tasks. Single-agent wins on reliability for tasks requiring tight sequential reasoning.

What models can sub-agents use?

Sub-agents run Anthropic models only — Claude Code is locked to Anthropic's model family. The orchestrator defaults to Sonnet 4.6 or Opus 4.6 based on your tier. Sub-agents can be assigned different models per task type (e.g., Haiku 4.5 for simple read-only analysis, Sonnet 4.6 for write operations) to optimize cost.

What are the team size limits?

10 simultaneous sub-agents maximum. The shared task list supports up to 200 active tasks. There is no limit on total agents spawned across a session — the orchestrator can spawn, retire, and spawn new agents continuously. For very large operations (hundreds of files), break work into multiple sequential Agent Teams sessions.