AI agent orchestration is the practice of running several coding agents at once and deciding, deliberately, who works on what, who may instruct whom, where each one writes, and what the whole thing costs. A guide to the four common topologies, the five problems they all have to solve, and how to choose between them.
the short version
AI agent orchestration is the practice of running several AI agents at the same time and deciding, deliberately, who does what, who may instruct whom, where each one is allowed to write, and what the whole thing costs. It is not a single technology. It is the set of decisions you are forced to make the moment a second agent starts working on the same problem as the first.
You can do it with nothing but a terminal multiplexer and some discipline. You can do it with a framework. What you cannot do is skip it: two agents sharing one working directory will overwrite each other, and three agents billing against one account will spend money you did not watch them spend. The rest of this post is the vocabulary, the four topologies people actually use, and how to pick between them.
what AI agent orchestration actually means
The word arrives from two directions and they do not mean the same thing, which is most of why the term is muddy.
The first is framework orchestration: a program that calls models in a graph. One node summarises, the next classifies, a third writes a database query, and control flow between them is code you wrote. Here the agents are functions and orchestration is a scheduling problem inside one process.
The second, and the one most developers now mean, is workspace orchestration: several long-lived agent sessions running against one codebase, each of them a real process with a real shell, editing real files. Claude Code in one pane, Codex in another, Gemini or Grok in a third. Nobody wrote a graph. The graph is you, deciding what to paste where.
This post is about the second kind, because it is the kind that has no default answer. Framework orchestration has an obvious home: the framework. Workspace orchestration currently lives in tmux panes, browser tabs, and a person's memory of which agent was doing which half of the refactor.
A useful definition, then. Orchestration is answering four questions about a set of concurrent agents, and answering them on purpose rather than by accident:
why it emerged now
Two things changed and they changed in the wrong order.
Agents got good enough to be left alone
A model that needs correcting every thirty seconds cannot be parallelised, because the supervision cost is the whole cost. Once a coding agent can take a scoped task, read the files it needs, write a patch and run the tests without a human in the loop for several minutes at a time, running two of them stops being a novelty and starts being obviously correct. Two agents that each work unattended for ten minutes give you twenty minutes of work in ten. That arithmetic is the entire reason this category exists.
The human became the bottleneck
And then the arithmetic stops being free. The agents parallelise. Review does not. Every agent you add produces another diff that one person has to read, another set of questions that one person has to answer, and another moment where it stops and waits. Past a small number of concurrent agents the limiting resource is not tokens or CPU, it is your attention, and the single most valuable thing orchestration tooling can do is tell you which agent is waiting on you right now.
This is why orchestration is a workflow problem rather than an infrastructure problem. Nothing about running four processes is hard. Knowing which of the four needs you, and being able to answer it without reading four scrollbacks, is the hard part.
the five problems every orchestration setup has to solve
1. Context isolation
Each agent has its own context window and none of them can see each other's. Agent A discovering that the auth middleware is generated code does not stop agent B editing it by hand. Context does not flow between sessions unless you make it flow, usually by writing it down: a shared plan file, a design doc committed to the branch, a handoff note. The naive alternative, pasting one agent's output into another's prompt, works and is what most people do, but it is manual and it is lossy.
2. Authority and permission
Once agents can talk to each other, "can" is the wrong default. If any agent may instruct any other, a confused supervisor can send a worker off to rewrite something nobody asked about, and a prompt-injected agent can do it deliberately. Real orchestration needs an explicit answer to who may command whom, and it needs that answer to be visible and revocable rather than implied by configuration you wrote a week ago. The same applies to tools: an agent that may run tests is a different thing from an agent that may run migrations.
3. Cost visibility
One agent in a terminal gives you no running total. Four agents give you four times no running total. Costs concentrate in unintuitive places too: for a long coding session most tokens are cache reads rather than fresh input, so summing raw token counts against a single rate produces a number that is wrong by a large multiple. We wrote that up separately in what Claude Code actually costs. The orchestration-specific point is narrower: parallelism multiplies burn rate, and burn rate is the one variable that a person watching four terminals genuinely cannot estimate.
4. Merge conflicts and file collisions
Two agents in the same directory are two processes writing the same inodes with no lock between them. Agent A reads a file, thinks for forty seconds, and writes back a version that silently discards agent B's edit. This is not a merge conflict, which git would at least tell you about. It is a lost update, and it is invisible.
The fix is well understood and it is older than agents: give each worker its own checkout. In git that is a worktree, which is cheap because it shares one object database, so several checkouts of a large repository cost far less disk than several clones. Real conflicts then surface at merge time, where they belong and where a human can see them.
5. Knowing which agent needs you
The last one is the one people underestimate until they have run four agents for an afternoon. An agent that has finished, an agent that is mid-thought, and an agent that has been sitting on a permission prompt for eleven minutes look nearly identical in a terminal you are not currently looking at. Any orchestration setup worth the name has to surface blocked agents without you polling them.
the four patterns
Nearly every multi-agent setup in practice is one of four topologies, or a composition of them. They differ in where the plan lives and where the coordination cost lands.
Single orchestrator, or supervisor
One agent holds the plan. It decomposes the task, hands subtasks to workers, and integrates what comes back. Workers do not talk to each other and do not know the whole plan. This is the diagram above.
Good when the task decomposes cleanly and the pieces are similar in shape: apply one refactor across four packages, write tests for six modules, port a component library file by file. Bad when the subtasks are genuinely interdependent, because the supervisor becomes a context bottleneck. It has to hold enough of every subtask to integrate them, and its context window is the same size as everyone else's.
Peer-to-peer delegation
No fixed hierarchy. Any agent may hand work to another agent it is connected to, and connections are the thing you configure. The agent that discovers a schema problem while writing the API layer can hand that discovery straight to the agent that owns the database, without a round trip through a supervisor or through you.
Good when the work is exploratory and the dependencies are not knowable in advance. Bad when the connections are unconstrained, which is when it becomes impossible to say afterwards why a given file changed. Peer-to-peer only stays sane if the edges are explicit: agent A may command agent B, and that is a fact you can point at and delete.
Pipeline, or hand-off
Work moves in one direction through stages. One agent writes the implementation, passes the branch to a second that writes tests, which passes it to a third that reviews and tightens types. Each stage has a narrow job and a clean input.
Good when the stages are genuinely different skills, and especially good when you want a second model looking at the first model's work, since a reviewer that shares no context with the author catches things a reviewer that wrote the code will not. Bad when latency matters: a pipeline is serial by construction, so its wall-clock time is the sum of its stages and you get none of the parallel speed-up.
Fan-out, fan-in
The same task goes to several agents at once and the results are compared. Three agents each attempt the same tricky bug fix in three worktrees; you read three diffs and keep one, or take the best parts of each.
Good when the task is hard, the approach is genuinely uncertain, and you have more budget than patience. Different models fail differently, so three attempts from three vendors is a real sample rather than three rolls of the same die. Bad in the obvious way: you pay N times for one result, and you have to read N diffs to pick. Reserve it for problems where a wrong approach costs more than the extra tokens.
A concrete composition
These compose, and the composition is usually what a real afternoon looks like. Say you are adding a payments provider to an existing app:
plan -> one agent, alone, writing PLAN.md into the repo
implement -> fan out: 3 agents, 3 worktrees
a: provider client + webhooks
b: database schema + migrations
c: the checkout UI
test -> pipeline: a second model writes tests against each branch
review -> fan in: you, reading three diffs in dependency order
merge -> b first (schema), then a (client), then c (UI)Note what the merge order encodes: the schema branch lands first because the other two depend on it. Deciding that order up front, before the agents start, is decomposition done properly. Discovering it at merge time is the thing that costs you the afternoon.
how to choose a pattern
The choice falls out of two questions, and you can usually answer both in a minute.
Two pieces of advice that are not in the table. First, start with one agent. A second agent is worth adding when you can name the file boundary between them. If you cannot, you are about to create a lost-update bug and blame the model for it.
Second, let the number of agents be set by your review bandwidth, not by your CPU count. Machines will happily run a dozen. The binding constraint is how many diffs you can meaningfully read before you start approving them by pattern-matching, which is the failure mode that makes multi-agent work produce worse code than a single careful session.
what orchestration tooling has to provide
Whatever you use, and it can be a shell script, four things are not optional. This is the shopping list.
Durable sessions
An agent that dies when you close the lid, restart the terminal or lose the SSH connection is not something you can leave running. Session continuity, whether that is tmux underneath or something else, is the difference between an agent you delegate to and an agent you babysit. It also has to survive the tool itself restarting, which is a harder promise than it sounds.
Isolation, which in practice means worktrees
One checkout per agent, one branch per agent, created before the agent starts rather than after it has already written to the wrong place. The commands are ordinary:
git worktree add ../wt-auth -b agent/auth
git worktree add ../wt-schema -b agent/schema
git worktree list
# later, once merged
git worktree remove ../wt-authIf your tooling does not do this for you, do it by hand. It is the single highest-value habit in multi-agent work and it costs two commands.
An authority model
An explicit, inspectable answer to which agent may instruct which other agent, and a way to revoke it that takes one action. "Explicit" is doing the work in that sentence. A setup where any agent can invoke any other because they all share a shell is not an authority model, it is the absence of one.
A spend meter
A running total you can see without asking for it, kept per agent so you can tell which one is expensive, and with a stop that can actually stop something. The meter matters most exactly when you are least likely to check it: several agents running unattended while you do something else.
one implementation, and its limits
Skribbl is our attempt at the workspace kind of AI agent orchestration, and it is worth being plain about what it is and is not.
It is a macOS desktop app that puts real terminals on an infinite canvas. Each agent, Claude Code, Codex, Gemini or Grok, is a node running a real shell, so anything you can do in a terminal works. Sessions survive restarts. You can spawn a fleet of agents in one action, each in its own git worktree. Authority is drawn: a line from one agent to another is what lets the first command the second, and rubbing the line out revokes it, so the topology diagram and the permission model are the same object rather than two things that drift apart. A meter in the top bar shows combined spend while the agents are still running.
What it is not: it is not a framework, it does not include a model or a subscription, and it does not decide your decomposition for you. Every pattern above is a pattern you still have to choose. The app makes the choice visible and cheap to change, which is a real thing but a smaller thing than the category's marketing usually implies.