Explainer
AI agent orchestration for coding: the words, the patterns and a worked example
Updated November 17, 20268 min read
Agent orchestration means one goal, many AI agents: something splits a coding job into parts, gives each part to an agent, decides what runs together and what waits, and then joins the results. In multi agent coding that "something" can be you, a lead Claude Code session, or an app. This page explains the words first, then three patterns that work, then walks through one real feature split across four agents.
Agent orchestration words in plain English
Most guides on AI agent orchestration and multi agent orchestration lose people in the first paragraph because of the words. Here they are, one line each.
- Agent
- An AI that does more than chat. It reads files, runs commands and edits code in a loop until a job is done. Claude Code, Codex and Gemini CLI are agents.
- Orchestrator
- Whatever decides who does what and in which order. It can be a person, a lead agent, or an app.
- Worker
- An agent that takes one piece of the job and does only that piece.
- Subagent
- A helper that one Claude session sends off for a focused task. It works in its own memory and hands back a short summary.
- Agent team
- Claude Code's experimental feature where a lead session starts teammates that share a task list and message each other.
- Swarm
- A loose name for a lead plus a group of workers attacking one task together.
- Context window
- How much text an agent can hold in mind at once. Each agent has its own, which is why splitting work helps.
- Worktree
- A second copy of your project folder that git keeps linked to the original, on its own branch. One per worker stops agents overwriting each other.
- Merge
- Bringing a worker's finished branch back into the main project.
- Merge conflict
- When two branches changed the same lines and git can't decide which to keep. Someone has to pick.
Pattern one: a lead with workers
This is the most common shape. One agent reads the request, writes a plan, splits it into tasks, and hands each task to a worker. The workers run at the same time. The lead checks the results and joins them.
You: "Add a password reset feature"
|
Lead agent
(plans, splits, checks)
/ | \
Worker A Worker B Worker C
(API, own copy) (page, own copy) (tests, own copy)
\ | /
Lead merges three branchesIt works well when the pieces touch different files: a backend part, a page, and tests. It works badly for one tangled change in a single file, because the workers would fight over it. Anthropic's agent teams docs list the strong cases as research and review, new features with separate parts, debugging with competing ideas, and changes that cross the frontend, backend and tests.
Pattern two: a pipeline that runs in batches
Some jobs have an order. You can't build the page that shows orders until the database table for orders exists. A pipeline groups tasks into batches. Everything in one batch runs at once. The next batch waits until the batch it depends on is done.
Batch 1: [database table] [email template] run together
|
Batch 2: [API endpoints] waits for batch 1
|
Batch 3: [reset page] [tests] waits for batch 2The skill here is drawing the lines between batches. Too many batches and you lose the speed of parallel work. Too few and a worker starts before the thing it needs exists, then guesses. Claude Code agent teams handle this with task dependencies: a task stays blocked in the shared list until the tasks it depends on are completed, and finishing one unblocks the next automatically.
Pattern three: the review loop
Here the agents don't build different parts. They look at the same work through different lenses, then a lead combines what they found, and a builder fixes it. Then the loop runs again until the reviewers come back clean.
Builder writes the change
|
+-----+------+------------+
| | |
Security Speed Test coverage
reviewer reviewer reviewer
| | |
+-----+------+------------+
|
Lead merges findings, builder fixes, repeatAnthropic's docs use this exact example: three teammates review one pull request, one for security, one for performance and one for test coverage. A single reviewer tends to focus on one kind of problem at a time. Splitting the lenses means each gets full attention. A close cousin is the debate pattern, where several agents each test a different theory about a bug and try to disprove the others. The theory that survives is more likely to be right.
Claude Code orchestrator tools you already have
If you only use Claude, you can do all three patterns without extra software. As of November 2026, Claude Code includes:
- Subagents: the main session sends focused jobs to helpers and gets a summary back. Cheapest option. See Claude Code subagents.
- Worktree isolation for subagents: add
isolation: worktreeto a subagent's file and it always works in its own copy. - Agent teams (experimental): a lead with teammates, a shared task list with dependencies, and direct messages between agents. Turn on with
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Not available in the desktop app. - Cross-session messaging: lets Claude pass findings between separate sessions you started yourself, with no team needed.
- Background sessions:
claude --bgstarts sessions with no terminal attached, andclaude agentslists them all.
“Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.”
On size, the same page recommends starting with 3 to 5 teammates for most work, and about 5 or 6 tasks per teammate. Token use grows with every teammate, because each one carries its own context window. For anything routine, Anthropic says one session is cheaper. The practical side of running sessions in parallel is on running multiple Claude Code agents.
Worked example: one password reset feature, four agents
Here is how you would split a real feature. The app already has logins. You want a "Forgot password?" link that emails a reset link. Four agents: one lead and three workers. The table is the plan the lead should produce before anyone writes code.
| Agent | Job | Files it owns | Waits for |
|---|---|---|---|
| Lead | Write the plan, assign tasks, review and merge | docs/reset-plan.md | Nothing |
| Worker A | Reset tokens table and the two API routes | db/migrations, src/api/reset | Nothing (batch 1) |
| Worker B | The "Forgot password" page and the new-password page | src/pages/reset | Worker A's route names (batch 2) |
| Worker C | Tests for the routes and pages | tests/reset | Workers A and B (batch 3) |
- Ask the lead for the plan only, in plan mode, so nothing changes yet. Check the file ownership column. If two workers share a file, change the plan now.
- Start Worker A in its own worktree. While it runs, Worker B can already sketch the page layout, but it must not wire up the API until A's route names are fixed.
- When A finishes, review its diff and merge it. Then let B finish the page against the real routes.
- Start Worker C once A and B are merged. Tests written against finished code catch real bugs instead of guessing.
- Run a review pass: one agent checks security (does the token expire? can it be reused?), one checks the pages work on a phone.
- The lead merges the last branch, runs the full test suite, and writes a short summary of what changed.
With Claude Code agent teams, the opening prompt could look like this:
Read docs/reset-plan.md. Create a team of three teammates.
Teammate "api" owns db/migrations and src/api/reset only.
Teammate "pages" owns src/pages/reset only and waits for api's route names.
Teammate "tests" owns tests/reset only and starts after api and pages finish.
No teammate edits files outside its folder. Wait for all three before merging.This split holds up because every worker owns separate folders, the order is written down, and nothing depends on a guess. When one of your own runs goes wrong, check those three points first.
Orchestrating coding agents from different companies
Claude Code's own tools only orchestrate Claude. You may want to mix models, for example Claude to plan and Codex for a second opinion on the result. To orchestrate coding agents from different makers by hand means one terminal per agent, copying the plan between them, and merging every branch yourself. Our Claude Code vs Codex vs Gemini comparison covers what each is good at.
VibeCodingDeck, a desktop app for Windows 10/11 and Apple silicon Macs, builds two of the patterns above into buttons:
- Swarms follow the lead-with-workers pattern: one task, a lead plus 2 to 5 workers, each on its own copy of the project. You choose which AI runs each role, such as a Claude lead with Codex and Grok workers. Swarm types include decision, action plan and research brief, and boosts add extra instructions for a harder pass. The team's work merges back in one action. See swarms.
- Plans in batches follow the pipeline pattern: drop in a plan, get one agent per batch, batches wait for the ones they depend on, you choose how many run at once, and every summary lands in one Results view.
- The pre-launch audit is a review loop at scale: 15 reviews, one agent per risk, with a Safety check that runs the 9 that block launch and ranks findings worst first. See the audit.
Signs your multi agent setup is going wrong
- The lead starts doing the work itself. Anthropic lists this as a known habit. Tell it to wait for its teammates to finish.
- A task looks stuck. Teammates sometimes forget to mark tasks done, which blocks the tasks after them. Check whether the work is finished and update the status.
- Two branches won't merge cleanly. Your file ownership plan had a gap. Fix the plan before the next run.
- Approvals pile up. In agent teams, every teammate's permission request goes to the lead. Pre-approve safe commands in your permission settings first.
- Usage disappears fast. Each agent has its own context window. Cut the team size, use a cheaper model for workers, and shut teammates down when they finish.
- A worker went quiet after an error. Open its view, give it more instructions, or start a replacement.
For the broader idea of letting AI run multi-step tasks on its own, see agentic coding.
Orchestration questions from builders
What is AI agent orchestration in simple terms?
+
It is managing several AI agents on one goal: splitting the work, giving each piece to an agent, deciding what runs at the same time and what waits, and joining the results at the end.
Does Claude Code have a built-in orchestrator?
+
Yes. Subagents handle focused jobs inside one session, and experimental agent teams let a lead session coordinate teammates through a shared task list with dependencies. Teams are off by default and are not available in the desktop app.
How many agents should work on one coding task?
+
Fewer than you think. Anthropic suggests 3 to 5 teammates for most work and notes that three focused teammates often beat five scattered ones. Add agents only when tasks can truly run side by side.
Can I orchestrate Claude Code, Codex and Gemini together?
+
Not with Claude Code's own tools, which only start Claude. You can run them by hand in separate terminals, or use VibeCodingDeck swarms, where you pick which AI runs each role.
How do I stop orchestrated agents from overwriting each other?
+
Give every worker its own worktree or copy of the project, and give each one a separate set of files in its first prompt. Merge each branch only after reviewing its diff.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Parallel agents
How to run multiple Claude Code agents at once: four ways, easiest last
Hands-on Claude Code guide
Claude Code subagents: build a custom agent step by step
Explainer
Agentic coding, explained in plain English
Three-way comparison
Claude Code vs Codex vs Gemini: the three CLI coding agents compared
Agent manager
Claude Code dashboard: the six things you need to see at a glance