Multi-agent orchestration: running parallel agents on real projects

TLDR; Multi-agent orchestration in Claude Code means running several agents on independent parts of one task at once, each in its own context. The alternative is one agent working through every step in turn. Map the code with read-only agents, plan, give each worker a self-contained brief, run the writers in separate git worktrees, then review and merge in order.

When to use multi-agent orchestration

• The work splits into three or more independent streams, such as backend code, system tests and documentation. With fewer, briefing each agent and merging its changes back can take longer than the parallel run saves.
• You would otherwise sit waiting for the build. If you would switch to other work anyway, one agent working in sequence is fine.
• A long, complex feature would fill one conversation with file reads and test output, and quality would drop. Each agent starts clean.
• My threshold: in my client work, a feature that would take more than 45 minutes in sequence and has at least three separable concerns gets orchestrated.
• Skip it for a focused task, such as one bug fix or one model. One agent is cheaper and clearer.

How multi-agent orchestration works

One Claude Code conversation has one reasoning thread and one context window, the amount of text Claude can hold at once. Claude can issue independent tool calls in parallel, so it can read several files together. It cannot work on six parts of a build in six separate contexts. A sub-agent can. It is a helper session Claude starts for one job, with its own context window, and it reports back when it finishes. Several can run at once.

Take a typical feature build for one of my Rails clients. The first two steps, research and planning, happen in order. The last four are largely independent: the backend code doesn’t depend on the docs, and the tests don’t depend on the serialisers (the code that formats API responses). In a single-agent session, those four tasks still happen one after another.

// A TYPICAL RAILS FEATURE BUILD

1. First, in order

   • Research the existing codebase
   • Plan the implementation: models, controllers, routes, views

2. Then, largely independent

   • Write the backend code
   • Write the system tests
   • Update the API serialisers
   • Write the documentation

Clutter is the other problem. By the last step, one conversation holds hundreds of file reads, test outputs and implementation details. The useful detail gets buried, and Claude sometimes loses track of earlier decisions or contradicts its own plan.

Anthropic’s own Code Review runs a team of agents on each pull request (a proposed code change) for the same reason: one reviewer has too much to check in one pass. The quality gates guide has the figures.

This guide uses sub-agents: one main session starts and manages them, and named sub-agents can also message each other. Agent teams, an experimental feature, run full sessions that share a task list and coordinate among themselves. They suit work where agents must talk to each other throughout, and they cost more, so start with sub-agents.

How to orchestrate parallel agents in Claude Code

1. Map the code with read-only Explore agents

Explore agents can read files and search code, but can’t edit anything. Start two or three at once, each on a different part of the codebase:

Agent 1 (Explore): "Find all models related to user onboarding, 
  User, Account, Invitation. Map their associations and validations."

Agent 2 (Explore): "Search for all existing system tests in 
  test/system/ that test the signup flow. List what's covered."

Agent 3 (Explore): "Find the API serialiser pattern used in this 
  project, which gem, what the base class looks like, any shared 
  concerns."

You get three answers in one round trip. Each agent returns a focused summary, and the dozens of file reads stay out of your main conversation. In my work a summary runs 500 to 1,500 tokens (tokens are the units Claude counts and bills text in).

By default, agents inherit the model from your session. If you run Opus, your Explore agents run on Opus too. That’s overkill for a code search; step 4 routes them to Haiku, the cheapest.

Check: each agent returns a short summary, and your own conversation holds only those summaries; the files they read stay in their contexts.

2. Plan with a Plan agent, and treat the plan as the contract

Plan agents can read and analyse but can’t write. They return implementation plans, identify risks and suggest approaches. Without a plan, you send agents into the codebase with vague instructions and hope their work fits together. The tech-lead pattern applies the same discipline: break the work down before you hand it out, to one agent or to five.

Agent (Plan): "Based on these findings [paste Explore results], 
  design the implementation plan for the onboarding flow. 
  
  Requirements: Invitation model with token-based acceptance, 
  mailer for invite email, system test for the full flow.
  
  Return: file-by-file breakdown of what needs to be created 
  or modified, in dependency order."

Review the plan, adjust it if needed, then use it as source material for the implementation briefs.

Check: the plan lists every file to create or change, in dependency order, and names the methods of each interface the workers will code against.

3. Brief each worker on one concern

General-purpose agents have full tool access: they read, write, edit, run tests and use Bash (the command line). Give each one a bounded deliverable: one agent builds the backend, a separate agent writes the tests.

Agents running in parallel can’t see each other’s live conversation or unmerged changes. They can load the same project instructions, but each task brief must stand on its own. “The User model that Agent 1 is creating will have a full_name method” fails, because Agent 2 can’t see Agent 1’s code. Put the model’s interface (how other code calls it) in Agent 2’s brief. Give each worker its section of the plan plus the interfaces it codes against:

Agent 1 (worktree): "Implement the Invitation model and 
  InvitationsController per the plan below. The model needs 
  these methods: #accept!, #expired?, #pending?. The controller 
  needs create and update actions.
  
  [paste relevant section of plan]"

Agent 2 (worktree): "Write system tests for the invitation 
  flow. The Invitation model will have #accept!, #expired?, 
  #pending? methods. The controller routes are:
  POST /invitations → create
  PATCH /invitations/:token → update (acceptance)
  
  [paste test requirements from plan]"

Check: no brief mentions another agent’s work, and each one contains every interface its agent needs.

4. Choose a model and effort level for each sub-agent

Each agent’s cost depends on three things: its model, its effort level (how much it reasons and writes) and what it reads. Every worker loads its own agent instructions, your CLAUDE.md project instructions (Explore and Plan agents skip these) and the code it opens. Five agents pay for that five times. On my Rails projects, a typical agent uses this much:

Prices shift, so check Anthropic’s API pricing table before you put a ratio in a budget. For prompts under 100,000 tokens at October 2026 rates, Sonnet 5.5 costs 50% of Opus 5.5 per token and Haiku 5.5 costs 2.5% (a fortieth). Not every agent needs Opus:

• Explore agents: Haiku. They locate and summarise. Haiku 5.5 matched Sonnet 5.5 on every code-search run I tested.
• Plan and review agents: Opus. I use it for architecture decisions and subtle bugs.
• Implementation agents: Sonnet for routine work such as a standard Rails model or test; Opus for novel patterns, tricky integrations and performance-sensitive code.

Set the model with the agent’s model parameter. For recurring patterns, define custom agents: agent files with their own model, effort level and a limited set of tools (the skills, hooks, agents and commands guide shows one).

Anthropic tested a related setup, its advisor pattern: Sonnet did the work and consulted an Opus advisor only at decision points. The pairing scored 2.7 percentage points higher than Sonnet alone on SWE-bench Multilingual, a coding benchmark, and cut the cost per task by 11.9%. That differs from parallel workers, but it shows a cheaper model carrying most of the work.

// BROWSECOMP, WITH AN OPUS ADVISOR

• Haiku solo19.7%
• Haiku with an Opus advisor41.2%More than double the performance

A custom agent can set its effort in its frontmatter (the settings block at the top of the agent file). Effort affects every token the model writes, tool calls included, so on agent work it can move the bill as much as the choice of model. Claude Code defaults to medium on Opus 5.5, Sonnet 5.5 and Haiku 5.5, unless your organisation sets a default. An agent without its own effort setting inherits the session’s level. The routing table in the model selection guide sets both for each type of work.

Check: every custom agent sets model and effort in its frontmatter, and no Explore agent runs on Opus.

5. Run parallel Claude Code agents in separate git worktrees

Claude Code can launch multiple agents from a single message, so launch the independent ones together.

Agents that edit files in the same folder collide. Agent 1 edits app/models/user.rb while Agent 2 edits it too, and git status fills with overlapping changes. Give each writing agent a git worktree: a separate copy of the code on its own branch. A branch is a line of changes git keeps apart until you merge it. If the agent makes no changes, Claude Code deletes its worktree; if it does, the worktree stays on disk for you to review.

A sub-agent’s worktree branches from your default branch, not your current one, unless you set worktree.baseRef to "head". Without that setting, workers don’t see plan or foundation commits on a feature branch that you haven’t merged yet.

Illustrative layout (Claude Code picks the names):

Agent 1 (worktree): works in .claude/worktrees/invitation-model/ on its own branch
Agent 2 (worktree): works in .claude/worktrees/invitation-tests/ on its own branch
Agent 3 (worktree): works in .claude/worktrees/invitation-docs/ on its own branch

No two agents write to the same copy, so no agent overwrites another’s edits; any conflicts wait until you merge (step 6). Read-only agents (Explore, Plan) change no files and need no worktree. To run whole sessions side by side instead of sub-agents, see step 7 of the session craft guide.

Sub-agents run in the background by default: Claude carries on while they work, and each one returns its result to your conversation and notifies you when it finishes. In interactive sessions fork mode is also on, so Claude can start forks (sub-agents that inherit your whole conversation) and doesn’t pause for any sub-agent. To make Claude wait for an agent, set CLAUDE_CODE_FORK_SUBAGENT=0, restart Claude Code, then ask it to run the agent and wait for its report. A custom agent with background: true in its frontmatter stays in the background even then.

When Agent B needs Agent A’s output, launch A and wait, add its result to B’s brief, then launch B (with others in parallel if they’re ready). Automating the whole dependency chain is fragile, because plans change when agents find unexpected code. Put a manual checkpoint between phases instead: review what came back and adjust the next brief.

Reports can stop short at a turn limit or an API error. Ask each agent for a concise final report, and for longer research have it write a file to disk. Check that a report ends cleanly before you act on it, and check the code yourself before you trust any claim that tests passed.

Check: git worktree list shows a worktree under .claude/worktrees/ for each writing agent that made changes.

6. Review every branch, then merge in order

Don’t skip review: the quality gates guide has the evidence.

Give the reviewer read access only. An agent that can’t edit files won’t try to fix a bug it finds during review; it reports the issue and lets you decide. Ask for the verdict first:

Review each branch against the plan. Open your report with one line,
APPROVED or REQUEST-CHANGES, before any findings.

A verdict-first report that gets cut off still delivers its conclusion. If a findings-first report is cut off, you get a partial list sorted by severity and no answer.

Merge the foundational branch first (usually the model and migration), run the test suite, then merge the next branch and test again until all are in. Agents occasionally touch the same file (routes, for instance); resolve the conflict before the next merge. In my builds, with each agent briefed on a separate concern, most merges have zero conflicts, and the occasional routes conflict takes 30 seconds.

Check: the reviewer’s report opens with its verdict, and the full test suite passes after the last merge.

Pitfalls

In practice

I used to work in one conversation, one task at a time: ask for the model, wait, then the test, wait, then the docs. A client’s new onboarding flow touched models, controllers, system tests, mailer templates and API docs, and the sequential approach took about three hours. Most of that time, I was waiting: Claude worked on one file while six others sat untouched. Orchestrated, the same feature now takes about 20 minutes of wall-clock time.

// ONBOARDING FEATURE, WALL-CLOCK TIME

• Sequentialthree hrs
• In parallel, now~20 minSplit up, each agent in its own context

The feature was a user invitation system (details anonymised). An admin sends an invite by email; the recipient clicks the link, creates an account and is assigned to a team.

I ran Agent A in the foreground, because the plan needed its results. It read 8 files and returned a 900-token summary of the existing patterns. Agent B turned that into a file-by-file plan with interface definitions. C, D and E ran in parallel worktrees in the background, each with its section of the plan plus the interface contract. Agent F found one issue: Agent D had hardcoded a URL instead of using the route helper, and I fixed it in 30 seconds. I merged C (model), then D (mailer), then E (tests). C and D had both added routes, and the one conflict in config/routes.rb took one edit. Tests passed on the first run.

// SIX-AGENT BUILD, WALL-CLOCK MINUTES

1. 0–2 minExplore agentAgent A
2. 2–5 minOpus plan agentAgent B
3. 5–13 minThree Sonnet implementation agentsAgents C, D and E
4. 13–17 minOpus review agentAgent F
5. 17–20 minMergeThree branches, one at a time

This run used Sonnet for the Explore agent; I route Explore to Haiku now. The reviewer read the most, because it reviewed every branch, and every agent read at least six times what it wrote. The Opus agents (B and F) account for about a third of the input tokens and an outsized share of the cost. Recomputed at Opus 5.5 pricing, an all-Opus run would have cost about 1.5x the mixed-model total, with no better output on the routine implementation work. On the older price list, when Opus ran 5x Sonnet, the gap was closer to 2x. The multiple moves with pricing; the direction doesn’t.

The parallel run used more tokens in total than a sequential build would have, but it compressed about three hours into 20 minutes. For a client paying by the hour, that saving is theirs.

For review and testing I use custom agents: my code-reviewer runs on Opus with read access only, and my rails-tester can run Bash (for the test suite) and read files but can’t edit production code.

Two things I’d do differently. The mailer agent (D) didn’t need its own worktree; its changes were small enough to merge directly. And I over-briefed the test agent with implementation details; the interface contract and the test requirements alone would have been faster. Both lessons now live in my briefing templates: worktrees only for agents whose edits can collide, and briefs that carry the interface contract rather than the implementation story.

When a team wants this running in production rather than in a session, that is Applied AI work.

---

Related reading

• Claude Code skills, hooks, subagents and commands: when to use each, the extensibility primitives that agents build on
• Claude Code pricing: what plans, tokens and models cost, the full cost model, including agent spend
• The tech-lead pattern, planning before coding, the planning methodology that produces good agent briefs
• Claude Code for the full stack: marketing, DevOps, and beyond code, the same orchestration running a marketing pipeline

Sources

• Code Review for Claude Code, Anthropic. Multi-agent PR review system; substantive review rates jumped from 16% to 54%, with <1% of findings marked incorrect. Product announcement
• The advisor strategy, Anthropic, Sonnet+Opus advisor pattern: +2.7pp on SWE-bench Multilingual at -11.9% cost; Haiku+Opus advisor scored 41.2% vs 19.7% solo on BrowseComp. Product announcement

Common questions

When should you use multiple AI agents instead of one?

When the work splits into independent parts that one agent would do one after another, such as backend code, tests and documentation. Briefing and merging add cost, so parallel agents pay off on larger work with at least three separate parts. For a single, linear task, one agent is cheaper and clearer.

How do you keep parallel agents from interfering with each other?

Give each agent that writes code its own git worktree: a separate copy of the code on its own branch, so no agent overwrites another’s files. Then merge the branches one at a time, foundation first, and run the tests after each merge.

Is running multiple agents worth the cost?

Only when the work splits into independent streams. Each agent loads its own instructions and reads its own files, so a parallel run uses more tokens (the units Claude bills by) in total. Send code searches to the cheapest model and routine coding to a mid-priced one. Weigh the time saved against the extra model spend and review time.