Orchestrating Multiple Subagents in Claude Code: Building Complex Workflows (2026)

- the agent-orchestration surface moves fast (agent teams, depth limits), so the numbers here were checked against the Claude Code docs and Anthropic's own research post at the time of writing.

What does orchestrating subagents mean?

Once you are comfortable creating and running a single subagent, the next step is orchestrating subagents in Claude Code: letting one main agent coordinate several worker subagents at the same time, or chaining them together. This is the classic orchestrator-worker pattern (sometimes called a lead agent coordinating workers).

The short definition to remember: orchestrating subagents means one coordinating agent (the orchestrator) spawns multiple subagents, each doing a slice of the work in its own separate context window, then returning a tight summary for the main agent to combine.

The whole trick lives in those two words, "separate context." Each subagent gets an independent context window, so it can read dozens of files, run many commands, and produce long output without bloating the context of your main session. The main agent only gets back the distilled part. That is how you tackle a large, multi-branch task while the original session's context stays clean.

This is an advanced capability. If you are not yet clear on what a subagent is and how to declare a basic one, read the subagents guide for beginners first, then come back here. This article assumes you have already created at least one subagent and now want to direct several at once - something almost no hands-on tutorial covers end to end.

When you SHOULD and SHOULD NOT orchestrate multiple subagents

Coordinating multiple agents is not always a win. It is token-hungry and adds latency, so it only pays off when the task genuinely splits into branches. This is the most valuable decision point, and it is the part docs and blogs usually skip past.

The 15x token figure and the shared-state warning both come from Anthropic's Multi-Agent Research System post (June 13, 2025). That same post notes that most of the performance variance (around 80%) comes from how many tokens are consumed - meaning tokens are both the cost and the lever. Pragmatic rule: if you cannot phrase the task as clear, separate branches, do not orchestrate - just use one linear session. To see where subagents sit relative to skills, hooks, and MCP, read the difference between skills, subagents, hooks, and MCP.

The two orchestration patterns: parallel vs pipeline

There are exactly two foundational patterns. Knowing when to reach for each already puts you ahead of most developers.

Parallel (fan-out / fan-in): the main agent spawns several subagents at the same time, each handling an independent branch, then the main agent gathers (fans in) the summaries into one result.

 ┌─→ subagent: auth ────┐
main agent ├─→ subagent: database ─┤─→ synthesize
 └─→ subagent: API ─────┘
 (parallel fan-out) (fan-in)

Pipeline (chain / sequential): the subagents run in order, where the output of one step becomes the input of the next. The main agent passes context between the links.

main → subagent: reviewer → subagent: optimizer → result
 (find issues) (fix based on issues)

The one-sentence test: if the branches do NOT need to know each other's results, go parallel; if step B needs the result of step A, go pipeline. Many real workflows are hybrids: fan out in parallel during a gathering phase, then chain one final synthesis step.

Example 1 - Running subagents IN PARALLEL (from scratch)

A real task: you want to quickly audit a backend repo, checking three independent areas at once - auth, database, and API. These three areas do not depend on each other, which makes them a textbook fit for parallel execution.

1. Type the coordinating prompt. Ask Claude to fan out explicitly, name the three branches, and tell each subagent to return only a summary:

   Audit this repo in parallel using 3 independent subagents:
   1) auth: check login flow, sessions, permission holes
   2) database: check schema, N+1 queries, missing indexes
   3) API: check input validation, rate limiting, error handling
   Each subagent should return only a short summary (~10 bullets max),
   NOT a full log dump. Then combine into one report.

2. Watch Claude fan out. Claude Code spawns the three subagents to run in parallel, each reading the code in its own context. You will see three work streams running at the same time in the session.
3. Read the merged summary. When all three finish (fan-in), the main agent combines them into a single report. Because each subagent only returned tight bullets, the main session's context stays light.

The condensed output of the synthesis step looks roughly like this (illustrating the format, not real numbers from your repo):

Audit report (merged from 3 subagents):
[auth] - Sessions not setting HttpOnly/Secure flags
 - Missing permission check on /admin/* endpoints
[database] - Order list query has N+1 (findOne in loop)
 - users table missing index on email column
[API] - 4 endpoints not validating the request body
 - No rate limit on the login route

Why parallel fits here: the three branches do not need each other's data, so running them concurrently cuts wall-clock time and isolates each long report in its own context. Forcing this to run sequentially would only be slower, not more correct.

Example 2 - A sequential pipeline (chain): reviewer to optimizer

A real task: you suspect a module has performance problems. Step 1, a code-reviewer subagent finds the bottlenecks. Step 2, an optimizer subagent fixes them based on that list. This is a clear dependency - the optimizer needs to know what the reviewer found - so it has to be sequential, not parallel.

1. Run the reviewer first. Coordinating prompt:

   Use the code-reviewer subagent to find performance bottlenecks
   in the src/services/ directory and return a prioritized list.

2. Pass the result to the optimizer. The main agent takes the reviewer's list as input for the next step:

   Hand the list above to the optimizer subagent:
   fix in priority order, add one line explaining each change,
   and do NOT change any public API behavior.

3. Get the final result. The optimizer works on exactly what the reviewer flagged. Claude acts as the relay, passing context between the two links.

[reviewer] Found 3 bottlenecks:
 P1 - parseAll() re-reads the file inside a loop
 P2 - sequential API calls that could be batched
 P3 - JSON.parse repeated on the same payload
[optimizer] Fixed:
 P1 → cache file contents outside the loop
 P2 → merge into a single batch request
 P3 → parse once, reuse the object

The core point: use a pipeline when a later step needs the output of an earlier one. If you tried to parallelize these two dependent steps, the optimizer would be fixing blind because the reviewer's list would not exist yet. Orchestration does not live in isolation - it is one piece of the brainstorm to plan to cook to ship workflow; usually you plan first, then unleash subagents to cook the branches.

Advanced - Orchestrator agents, nested subagents, and depth limits

Instead of typing a coordinating prompt every time, you can declare a dedicated orchestrator agent whose only job is coordination. Create a file at .claude/agents/coordinator.md:

---
name: coordinator
description: Coordinates worker subagents for large, multi-branch tasks.
 Only splits work, spawns workers, and merges summaries - does NOT write code itself.
---

You are a coordinating agent. Your job:
1. Decompose the request into independent branches (if any).
2. Independent branches → dispatch in parallel; dependent branches → chain.
3. Require each worker to return ONLY a tight summary.
4. Merge everything into a single result for the user.
Do not do the detailed work yourself; always delegate to workers.

The name and description in the frontmatter help Claude know when to call this agent. The "coordinate only" constraint keeps it from jumping in to do the work itself and blowing up its own context.

Nested subagents: a subagent can spawn its own child subagents. This is powerful but easy to lose control of, so Claude Code caps the depth. Per the Claude Code docs on sub-agents (checked 2026-08), the default spawn depth is 3 levels and it is adjustable via the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable. Setting it too high easily leads to an explosion in agent count and burned tokens; most real workflows never need to exceed the default.

For durable parallel tasks or ones that outgrow a single context window, the docs also mention an agent teams feature - letting multiple agents coordinate at a larger scale. This is a new and fast-changing surface, so before you rely on it in production, re-check the live docs.

Optimizing tokens and cost when you orchestrate

Because multi-agent runs cost roughly 15x the tokens of a plain chat session (per Anthropic), token optimization is not optional - it is the condition that makes orchestration worth the money. A few pragmatic moves:

• Cap the number of subagents at 3-5 per fan-out. Adding more agents rarely improves quality proportionally but increases tokens linearly.
• Route workers to a cheaper model. Simple branches (reading files, listing things) can go to a cheap model like Haiku, saving the strong model for the synthesis step.
• Force subagents to return only summaries, not full log/diff dumps back to the main agent. This is the single biggest source of wasted tokens, and everyone falls into it.
• Avoid many subagents each returning long output to main - fanning in several long outputs stuffs the main context and defeats the whole point of isolation.

To go deeper on token budgets for multi-agent sessions, see the guide on optimizing tokens when running many agents.

Do not want to build it yourself? A ready-made orchestrator agent kit (AgentKit)

Writing a decent coordinator and a squad of workers takes time. If you would rather have something ready to use, there is a kit that packages this up. One line to avoid confusion: the AgentKit here is a kit for Claude Code (agentkit.best, the ak CLI) - NOT OpenAI's AgentKit (Agent Builder/ChatKit, launched October 6, 2025).

AgentKit's Engineer Kit ships with 17 engineer agents (out of the platform's 45 total = 17 engineer + 28 marketing) plus orchestration workflows - such as the ak-orchestrate skill - so you do not have to write a coordinator from scratch. The listed Engineer Kit price is $99, and the page does not state a recurring fee. To be blunt: you can absolutely build an orchestrator yourself following the sections above; the kit is only worth it if you want to save setup time and use pre-tuned agents. To see exactly what is inside, read the Engineer Kit review, or look straight at AgentKit's ready-made orchestrator agents.

Common mistakes when orchestrating multiple subagents

• Spawning too many subagents. When they all return results at once, the main context burns up. Avoid it: keep 3-5 agents per round and force summaries.
• Using parallel for dependent work. Wrong results or data races. Avoid it: ask "does the later step need the earlier step's output?" - if yes, use a pipeline.
• Subagents returning long logs instead of summaries. Wasted tokens and a stuffed context. Avoid it: state output limits explicitly in the prompt or agent definition.
• Forgetting the depth limit. Nested subagents overflow the levels and the agent count explodes. Avoid it: keep CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH at the default unless you have a clear reason.
• Disproportionate token spend. Using multi-agent for a small change. Avoid it: for small or quick tasks, run a single linear session instead of orchestrating.

Frequently asked questions (FAQ)

How many subagents can run in parallel?

In practice, keep 3-5 subagents per fan-out. It is not a hard limit, but more than that usually does not improve quality proportionally while tokens climb fast and the merged context is easy to overload. Several small fan-out rounds beat one giant round.

Does parallel or pipeline cost more tokens?

Parallel usually spikes tokens harder because many agents run at once, each with its own context. A pipeline consumes tokens more moderately at any single moment but accumulates across steps and is slower. Choose based on the task's dependencies, not tokens alone.

Can a subagent spawn its own child subagents (nested)?

Yes. A subagent can spawn child subagents (nested subagents). Claude Code caps the depth - 3 levels by default - and it is adjustable via the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH variable. Most workflows never need to exceed the default.

Do you need agent teams to orchestrate?

No, it is not required. You can orchestrate with just a coordinating prompt or a self-declared orchestrator agent. Agent teams is a surface for durable, large-scale parallelism that outgrows a single context window; check the live docs since the feature is new and changing fast.

Is orchestrating multiple agents worth it for a small project?

Usually not. For small or quick changes, the coordination and token cost (multi-agent runs cost roughly 15x the tokens per Anthropic) outweigh the benefit. Only orchestrate when the task genuinely splits into independent branches or spans many areas.

Is there a ready-made coordinating agent kit?

Yes. AgentKit's Engineer Kit (agentkit.best, the ak CLI - different from OpenAI AgentKit) packages 17 engineer agents plus orchestration workflows so you do not have to write a coordinator yourself. You can still build it all yourself as shown above; the kit just saves setup time.

Conclusion and next steps

Do not start with a ten-agent orchestra. Build a two-step pipeline first (like reviewer to optimizer), measure the tokens it burns, and only then expand to parallel fan-out when the task genuinely splits into independent branches. Nail the fundamentals in the subagents guide for beginners and put orchestration in its right place within the brainstorm to plan to cook to ship workflow. If you would rather not write a coordinator yourself, check out the Engineer Kit review.