Multi-agent orchestration: running parallel agents on real projects

TLDR; Multi-agent orchestration means decomposing a task into independent pieces and running several Claude Code agents on them at once, each in its own context and often its own git worktree, instead of one agent working through every step in sequence. On a real client build it cut a feature from about three hours of sequential work to about 20 minutes.

I used to work with Claude Code the way most people do: one conversation, one task at a time. Ask it to write the model, wait, then ask it to write the test, wait, then ask it to update the docs. Sequential. Linear.

It worked fine for small changes. But on a client’s new onboarding flow, touching models, controllers, system tests, mailer templates, and API docs, the sequential approach took about three hours. Most of that time, I was waiting. Claude was working on one file while six others sat untouched.

Multi-agent orchestration changed how I structure complex work. Instead of one Claude instance doing everything in sequence, I decompose the task and run multiple agents in parallel, each focused on a specific piece in its own isolated context. That same onboarding feature now takes about 20 minutes of wall-clock time.

This guide covers how I do it: the agent types, the parallel execution mechanics, the worktree isolation that prevents agents from stepping on each other, and the cost modelling that determines when parallel execution is worth the spend.

Why single-agent hits a ceiling

The fundamental constraint is not a literal one-tool limit: Claude can issue independent tool calls in parallel. The constraint is that one conversation still has one reasoning thread, one context window, and a dependency chain for decisions that must happen in order. It can read several files together, but it cannot independently pursue six implementation concerns with six isolated contexts inside that one thread.

For a focused task (fix a specific bug, write a single model), this is fine. The bottleneck isn’t Claude’s speed; it’s the complexity of the work.

For a feature that spans multiple concerns, the sequential nature compounds. A typical feature build for one of my Rails clients:

1. Research the existing codebase to understand the domain
2. Plan the implementation: models, controllers, routes, views
3. Write the backend code
4. Write the system tests
5. Update the API serialisers
6. Write the documentation

Steps 3 through 6 are largely independent. The backend code doesn’t depend on the docs. The tests don’t depend on the serialisers. Yet in a single-agent conversation, Claude does them one at a time, spending tokens on each step while the others wait.

The second issue is context pollution. By the time Claude gets to step 6, the conversation is loaded with hundreds of file reads, test outputs, and implementation details from earlier steps. Signal-to-noise degrades. Claude sometimes loses track of earlier decisions or contradicts its own plan.

Anthropic’s Code Review for Claude Code dispatches a team of agents on each PR: they look for bugs in parallel, verify findings to filter out false positives, and rank them by severity. The share of PRs getting substantive review comments rose from 16% to 54%, and under 1% of findings are marked incorrect. That is one team’s result on one workload, but the problem it answers is the one any single reviewer has: a lot of concerns competing for one pass of attention.

Parallel execution compresses wall-clock time. Context isolation keeps each agent focused on its piece of the work.

Agent types and when to reach for each

If you’ve read the extensibility guide, you know the basics: Explore agents for read-only research, Plan agents for architecture, general-purpose agents for work that needs file access. Here’s how those types map to real orchestration patterns.

Explore agents: fast, cheap recon

Explore agents can read files, search code, and grep, but can’t edit anything. I use these as the first step in almost every complex task. Two or three Explore agents into different parts of the codebase simultaneously build a picture of the current state quickly.

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."

Three agents, three answers, one round trip. Each returns a focused summary, typically 500 to 1,500 tokens, without polluting my main conversation with dozens of file reads.

By default, agents inherit the model from your parent session, so if you’re on Opus, your Explore agents run on Opus too. That’s overkill for codebase searches. I route Explore agents to Haiku with the model parameter, which keeps them fast and cheap: at October 2026 API rates Haiku 5.5 costs a fortieth of Opus 5.5 for prompts under 100,000 tokens, and it matched Sonnet 5.5 on every code-search run I tested. Check the API pricing table before using those ratios in a budget. The model selection guide covers the full routing pattern.

Plan agents: architecture before code

Plan agents can read and analyse but can’t write. They return implementation plans, identify risks, and suggest approaches.

I almost always run a Plan agent before any multi-agent implementation. The plan becomes the brief for the implementation agents. Without it, you’re sending agents into the codebase with vague instructions and hoping they converge on a coherent design. It’s the same discipline behind the tech-lead pattern: decompose before you delegate, whether the delegate is one agent or 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."

The Plan agent returns a structured implementation plan. I review it, adjust if needed, then use it as source material for the implementation briefs.

General-purpose agents: the workers

General-purpose agents have full tool access: they can read, write, edit, run tests, use Bash. These are the agents that build things.

One concern per agent. Don’t send a general-purpose agent to “build the backend and write the tests.” Send one agent to build the backend and a separate agent to write the tests. Each agent should have a clear, bounded deliverable.

Custom agents: model and tool control

For recurring orchestration patterns, I define custom agents with constrained toolsets and model overrides. My code-reviewer agent runs on Opus but only has read access. My rails-tester agent can run Bash (for the test suite) and read files, but can’t edit production code.

These constraints aren’t just about safety; they’re about focus. An agent that can’t edit files won’t try to fix a bug it finds during review. It’ll report the issue and let you decide.

One briefing rule for review agents specifically: require the report to open with the verdict line, APPROVED or REQUEST-CHANGES, before any findings. Agent reports can truncate on tool or context limits, and a verdict-first report still delivers its conclusion when it cuts off; a findings-first report that truncates leaves you severity-sorted fragments and no answer.

Subagents vs agent teams

Everything above describes subagents: workers that report back to the orchestrating session. Subagents Claude names when it spawns them can message each other, but they share no task list or team lead. Claude Code also ships agent teams, an experimental peer model where teammates run as full sessions with a shared task list, dependency tracking, and direct agent-to-agent messaging under a team lead. The useful split, straight from the official docs’ own framing: teams suit work where cross-talk matters, parallel research, review from competing angles, debugging rival hypotheses; subagents suit bounded work with one clear deliverable. Team cost scales with the number of active teammates, their models, and how long they run, so I reach for subagents first and promote to a team only when direct peer communication earns that additional context spend.

Parallel execution: the mechanics

Claude Code supports launching multiple agents from a single message. You don’t launch one, wait, then launch the next. You launch them all at once.

Foreground vs background

In interactive sessions fork mode is on by default, so every subagent runs in the background. With fork mode off, subagents still default to the background, and Claude runs one in the foreground only when it needs the result before continuing. Custom agents can set background: true in frontmatter. When a research agent’s findings feed the next implementation decision, wait for its result before briefing the next agent.

Background agents return their result to the parent conversation and notify you when they finish. I still ask for a concise final report, and for longer research I sometimes have the agent write an artifact to disk, because reports can truncate at tool or context limits. Check that a report ends cleanly before acting on it, and verify the tree state yourself before trusting any claim that tests passed.

Briefing for parallel work

When subagents run in parallel, they cannot see each other’s live conversation or unmerged worktree changes. They may inherit the same project instructions and memory, but your task-specific briefs still need to be self-contained.

The mistake I made early on was briefing implementation agents with references to each other’s work: “The User model that Agent 1 is creating will have a full_name method you can use in the view.” Agent 2 can’t see Agent 1’s code. If Agent 2 needs to know about the model’s interface, that interface needs to be in Agent 2’s brief.

I’ve settled on a pattern: the Plan agent’s output becomes a shared contract. Each implementation agent gets the full plan (or the relevant section) plus any interface definitions they need to code 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]"

Both agents know the interface contract and can work independently.

Dependency chains

Not everything can run in parallel. Sometimes Agent B needs Agent A’s output before it can start. Handle this with sequential launches:

1. Launch Agent A and wait for its result
2. Review Agent A’s output, incorporate into Agent B’s brief
3. Launch Agent B (possibly with others in parallel)

I’ve tried pre-planning the entire dependency graph and automating the chain. It’s fragile. Plans change when agents find unexpected code. A manual checkpoint between phases, where you review what was produced and adjust the next brief, produces better results than a fully automated pipeline.

Worktree isolation: the pattern that makes this work

Running multiple agents that edit files in the same working directory is asking for trouble. Agent 1 modifies app/models/user.rb while Agent 2 is reading it. Git status becomes a mess of overlapping changes.

Worktree isolation solves this cleanly. Each agent operates in its own git worktree, a separate checkout of the repository on its own branch. The worktrees are temporary. If the agent makes no changes, the worktree is cleaned up automatically. If it does make changes, you get the branch name and worktree path in the result.

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

Each agent has a full copy of the repo, so no two agents write to the same working tree and nothing races. Conflicts move to merge time instead of disappearing. When they’re done, you merge the branches in the order that makes sense: model first, then tests, then docs.

The merge strategy

I merge agent worktree branches sequentially, testing after each merge:

1. Merge the foundational branch first (usually the model/migration)
2. Run the test suite
3. Merge the next branch
4. If conflicts arise, resolve them; agents occasionally touch the same file (routes, for instance)
5. Continue until all branches are merged

Most of the time, there are zero conflicts. When agents work on separate concerns, and you’ve briefed them clearly about their scope, their changes don’t overlap. The occasional routes file conflict takes 30 seconds to resolve.

Background agent sessions now commit and push their work when they finish in a worktree, and open a draft PR when the task calls for one, which turns the manual merge queue into PR review. I still merge by hand when the branches are tightly coupled, because there the merge order is part of the design.

When worktrees aren’t needed

For read-only agents (Explore, Plan), worktrees add overhead without benefit. These agents don’t change files, so there’s nothing to isolate. Use worktree isolation only for agents that write code.

Cost modelling for agent teams

Running parallel agents is faster, but it’s not free. Each agent loads the full system prompt, any CLAUDE.md files, and whatever context it reads from the codebase, independently. Five agents don’t share a context pool; they each maintain their own.

How agent costs accumulate

A typical agent session on my Rails projects:

The exact cost depends on current API pricing, which shifts; check Anthropic’s API pricing table for the latest rates. At October 2026 rates, Sonnet 5.5 runs at 50% of Opus 5.5 per token, with Haiku 5.5 at 2.5% for prompts under 100,000 tokens. The routing discipline still pays, but the ratios are dated inputs rather than permanent product facts.

Run five agents in parallel and the total adds up, but it’s still modest compared to the alternative: three hours of sequential work at your billing rate.

Model selection as cost control

Not every agent needs Opus:

• Explore agents: Haiku. They’re locating and summarising, not reasoning about architecture.
• Plan agents: Opus. Architecture decisions benefit from the strongest model.
• Implementation agents (routine): Sonnet. Writing a standard Rails model or test doesn’t need Opus.
• Implementation agents (complex): Opus. Novel patterns, tricky integrations, performance-sensitive code.
• Review agents: Opus. Catching subtle bugs requires strong reasoning.

There’s published data backing this. Anthropic’s advisor pattern benchmarks show that pairing a Sonnet executor with an Opus advisor (called only at decision points) gained 2.7 percentage points over Sonnet alone on SWE-bench Multilingual while cutting cost per task by 11.9%. On BrowseComp, Haiku with an Opus advisor scored 41.2% versus 19.7% for Haiku solo, more than double the performance. The principle scales: use the strongest model where reasoning matters, and a lighter model where it doesn’t. The model selection guide has the model and effort I give each kind of work, with my own eval results.

My typical five-agent orchestration mixes models: one Opus Plan agent, two Sonnet implementation agents, one Sonnet test agent, one Opus review agent. The blend costs less than an all-Opus run and gives up nothing on the routine work.

Model is only half of it. Each agent also carries an effort level, set in its frontmatter, and since effort governs every output token including tool calls, it moves the bill on agentic work further than the model choice does. Claude Code defaults to medium on Opus 5.5, Sonnet 5.5 and Haiku 5.5, xhigh on Opus 4.7, and high on other models (unless your organisation sets a default), and an agent without its own effort setting inherits the session’s level. The routing table in the model selection guide pairs both dials against work type.

When parallel execution is worth it

Parallel agents pay off when:

• The task has three or more independent work streams. Fewer than three and the overhead of briefing and merging outweighs the time saved.
• Wall-clock time matters. If you’re context-switching to other work anyway, sequential is fine. If you’re blocked waiting for the build, parallel pays off.
• Context pollution is a real risk, and long, complex features degrade single-conversation quality. Fresh agent contexts produce cleaner output.

For my client work, the threshold is roughly: if a feature would take more than 45 minutes sequentially and has at least three separable concerns, I orchestrate it.

Case study: onboarding flow build

Here’s a real feature build from a client project (details anonymised), orchestrated across multiple agents.

The feature: User invitation system. Admin sends invite by email, recipient clicks link, creates account, gets assigned to a team.

The decomposition:

Phase 1: Research (2 minutes): Launched Agent A in the foreground, because I needed the results for the plan. It read 8 files and returned a 900-token summary of the existing patterns.

Phase 2: Planning (3 minutes): Launched Agent B with Agent A’s findings. It returned a file-by-file implementation plan with interface definitions: the contract for the implementation agents.

Phase 3: Implementation (8 minutes wall clock): Launched Agents C, D, and E in parallel, all in worktrees, all in the background. Each got the relevant section of the plan plus the interface contract. I reviewed the plan while they worked.

Phase 4: Review (4 minutes): Launched Agent F to review each branch. This step isn’t optional. In CodeRabbit’s 470-PR observational sample, AI-co-authored PRs had 75% more logic and correctness findings than the PRs classified as human-only. A separate Veracode benchmark found that 45% of generated samples failed its security tests; that is a failure rate, not a human-versus-AI uplift. Agent F found one issue: Agent D had hardcoded a URL instead of using the route helper. Fixed in 30 seconds.

Phase 5: Merge (3 minutes): Merged branches in order: C (model), D (mailer), E (tests). One conflict in config/routes.rb where C and D both added routes, resolved in one edit. Tests passed on first run.

Total wall-clock time: ~20 minutes.

Scroll sideways →

Token breakdown:

This run used Sonnet for the Explore agent; I route Explore to Haiku now.

Scroll sideways →

The Opus agents (B and F) account for about a third of the input tokens and an outsized share of the cost. Recomputing this table at Opus 5.5 pricing, running everything on Opus would have cost about 1.5x the mixed-model total, with no improvement in output quality for 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 approach used more total tokens than the equivalent sequential build would have, since each agent independently loads the system prompt and reads its slice of the codebase. But it compressed about three hours of wall-clock time into 20 minutes. For client work billed by the hour, that’s a clear win.

What I’d do differently

The mailer agent (D) didn’t need its own worktree; the changes were small enough to merge directly. I also over-briefed the test agent with implementation details it didn’t need; it would have been faster with just the interface contract and the test requirements.

Both lessons now live in my briefing templates: worktrees only for agents whose edits can actually collide, and briefs that carry the interface contract rather than the implementation story. That’s how orchestration improves, one documented miss at a time.

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

---

Related reading

• Skills, hooks, agents, and commands, the definitive guide, the extensibility primitives that agents build on
• Token economics, what Claude Code actually costs, the full cost model, including agent spend
• The tech-lead pattern, planning before coding, the planning methodology that produces good agent briefs

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
• State of AI vs Human Code Generation, CodeRabbit. Observational source for the 470-PR comparison and 75% increase in logic and correctness findings; includes authorship-classification limitations. Company research
• 2025 GenAI Code Security Report, Veracode. Separate benchmark source for the 45% generated-sample security-test failure rate. Company research

Common questions

When should you use multiple AI agents instead of one?

When the work decomposes into independent parts that a single agent would otherwise do serially. Parallel agents help with breadth and isolation; they add coordination cost, so I reach for them on complex, separable work, not on a single linear task.

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

Worktree isolation. Each agent works in its own git worktree so parallel changes do not collide, then results are merged deliberately. Without that isolation, concurrent agents overwrite each other and the speed gain disappears.

Is running multiple agents worth the cost?

Only when the work decomposes into independent streams. More agents mean more tokens, so I model the cost against the time saved: for a separable feature the parallelism pays off, for a small linear task one agent is cheaper and clearer.