Running coding agents in parallel is a scheduling problem, not a prompting one. How to split work so two agents never need the same file, how to keep each one in its own worktree and its own terminal, how to hand context between them, and the honest ceiling on how many a single human can actually review.
parallelism is a scheduling problem
Running coding agents in parallel is a scheduling problem, not a prompting one. Almost everything that goes wrong when you start a second agent is a resource question: two processes wanting the same file, the same branch, the same port, or the same twenty minutes of your attention. None of those is fixed by a better system prompt, and reaching for prompt engineering first is why people conclude that multi-agent work does not work.
The whole procedure is four decisions, made in this order, before anything starts:
The fourth is the one people leave until the end, and it is the one that sets how many agents you should be running at all. It gets its own section below. If the vocabulary here is new, the concepts sit in what AI agent orchestration means; this page is the practical version.
splitting the work so nobody shares a file
The test for a good split is a sentence with no comma in it: "this agent touches only ___." A package, a directory, a layer and a named list of files all finish that sentence. "The refactor" does not. "The backend, plus a bit of the shared types" does not, and the "plus a bit" is where the lost update happens.
Some work splits cleanly by construction:
- A monorepo splits per package, because that boundary is already a file boundary somebody enforced.
- A layered application splits into schema, server and client, in that dependency order.
- Writing tests splits per module: every file is new and nothing else touches it.
- Porting or restyling a component library splits file by file, which is why everybody tries it first.
And some work does not split, no matter how it is phrased:
- A cross-cutting rename touches everything by definition.
- A change to a shared type with four call sites is one piece of work wearing four hats.
- Anything where the second agent must read what the first wrote is a pipeline, and pipelines run in sequence.
- Exploratory work. A decomposition invented before you understand the problem is one you will throw away.
Write the split into the repository rather than into three prompts. A short markdown file on the base branch, committed first, naming each slice, its directories, the files nobody may touch, and the merge order. Then every agent's first instruction is one line: read the plan file, do your section, stay inside your directories.
cat > PLAN.md <<'EOF'
## feat/schema (db/, migrations/) port 3001
## feat/api (server/) port 3002
## feat/checkout (app/checkout/) port 3003
## nobody edits
package-lock.json, *.generated.ts, migrations already applied
## merge order
schema -> api -> checkout
EOF
git add PLAN.md && git commit -m "plan: payments split"The failure this prevents: boundaries that exist in exactly one context window. No agent can see another agent's context. Rules you explained to the first agent are invisible to the second and third, and invisible to you in an hour when you have forgotten which half of the work you gave to whom.
one directory and one branch each
Two agents in one checkout overwrite each other. The mechanism is dull: an agent reads a file, thinks, and writes it back, and anything written in between is discarded. Git sees one commit, not a conflict, so nothing warns you. Each agent needs its own working directory, and the cheapest way to get one is a git worktree.
cd ~/code/myapp
git worktree add ../wt-schema -b feat/schema
git worktree add ../wt-api -b feat/api
git worktree add ../wt-checkout -b feat/checkout
git worktree listA worktree is a second checkout of the same repository on its own branch, sharing one object database. Unlike a clone, a commit made in one is immediately visible in all of them, so handing work between agents needs no remote. The full treatment, including cleanup and the places it still bites, is in git worktrees for AI coding agents.
Two rules matter more than the commands. Each worktree needs its own environment, because it carries tracked files only, so the gitignored .env.local and node_modules are absent. And assign ports when you assign directories: two dev servers on port 3000 presents as a page served from the wrong branch, not as an error.
cd ../wt-api
cp ../myapp/.env.local .
npm install
PORT=3002 npm run devLeave your original checkout on the base branch with no agent in it. That is where you read diffs, run the full suite and merge, and one always-clean directory is what tells you whether the repository is broken or merely mid-edit somewhere.
launching them, and keeping track
The agents themselves are ordinary terminal processes, so no orchestration layer is required to start three of them. Three terminal tabs is how most people begin:
cd ../wt-schema && claude
cd ../wt-api && codex
cd ../wt-checkout && geminiWhat tabs do badly is survive. Close the window and the agent dies with whatever it had in flight. If a run is long enough that you will not sit in front of it, put each one in a terminal multiplexer so the session outlives the window:
tmux new-session -A -s agent-api -c ../wt-api
# later, from any terminal
tmux attach -t agent-api
tmux lsnew-session -A attaches if the session exists and creates it if it does not, which makes the command safe to run twice. Name sessions after the slice, for the same reason you name branches after it.
Mixing agent vendors is fine and sometimes useful. It costs some uniformity: each brings its own approval prompts, its own configuration file, and its own idea of what it may do without asking. Where those differ concretely is set out in Claude Code vs Codex CLI and, for a three-way setup, in running Claude Code, Codex and Grok together.
The failure this prevents: losing an agent's work to a closed laptop lid, then not being sure how much of the task it had finished before it died.
handing context across
When the schema agent finishes, the API agent knows nothing about what it built. This part of parallel work has no clean solution, only a better and a worse habit. The worse one is copying the useful part of one transcript into another agent's prompt: it works, it is what everyone does first, and it is lossy, unversioned and impossible to repeat. Do it once when you are in a hurry. Do not build a workflow on it.
The better habit makes the handoff an artefact. Have the finishing agent write a short note, commit it with the work, and let git carry it:
# in ../wt-schema, when the agent says it is done
git add -A
git commit -m "schema: customers, subscriptions, invoices"
# in ../wt-api, pick it up
cd ../wt-api
git merge feat/schemaNow the API agent reads the actual type definitions rather than a description of them, which costs fewer tokens than pasting a summary and cannot go stale, because it is the code. Ask for the note under four explicit headings rather than as a summary: what exists now, what the names are, what was deliberately left undone, and what the next agent must not change. An agent asked to summarise writes prose about its own process. An agent given four headings writes something the next one can act on.
The failure this prevents: the second agent reinventing a decision the first one already made, under a different name. Two working implementations of the same thing is worse than one, because now a third agent has to choose and will choose badly.
what parallel actually costs
Parallelism multiplies burn rate and nothing about it makes any individual agent cheaper. Three agents working for an hour is roughly three agent-hours of tokens. That is the whole model, and it is worth stating plainly because the interface hides it: a terminal shows no running total, and three terminals show three times no running total. On a subscription the surprise is worse than a bill, because there is no invoice to watch. The first signal is a rate limit arriving mid-task, and it arrives for all three agents at once.
If you want to count, count properly. Do not sum raw token counts against one rate. Cache reads are a small fraction of the price of a fresh input token and they dominate a long coding session, so the naive sum is wrong by a multiple rather than a rounding error. The measurement behind that is in what Claude Code actually costs, and the worked arithmetic for a month sits in what coding agents cost per month.
Two habits keep the number down. Scope each prompt to its boundary, because an agent told to work in db/ reads far less of the repository than one told to "add payments", and reading the repository is where the tokens go. And stop finished agents, which are the most expensive idle processes on your machine. Deciding in advance what happens when spend crosses a line is its own subject, setting a token budget for coding agents.
the ceiling is review, not compute
The limit on how many agents you can run is how many diffs you can read carefully, and that number is smaller than you would like. This is the honest centre of the subject and most writing on it skips straight past.
The reasoning is arithmetic about which parts scale. Agents parallelise perfectly: each is a separate process talking to a separate session, and adding a fourth costs nothing anyone else was using. Review does not parallelise at all. There is one of you. Every agent you add produces another diff one person has to read, another set of decisions one person has to check, and another moment where something stops and waits for an answer only you can give. The work you added is parallel. The work you kept is serial, and the serial part decides throughput.
The failure mode is not a crash, which is what makes it dangerous. It is approving diffs by pattern-matching because there are four of them, they all look plausible, and you are tired. Plausible is exactly what these models are good at producing. Code that reads well and is subtly wrong passes a tired skim every time, and the result is worse output than one careful session would have given, while feeling like more.
There is a second, quieter cost. Switching between four unrelated diffs is expensive for a person in a way switching between four terminals is not. By the third you have stopped holding the first in your head, so you are not reviewing four changes, you are reviewing one change four times with progressively less information.
We do not have a measured number for where this breaks and we are not going to invent one. What we can say is what the constraint is made of, so you can find your own limit: your reading speed on unfamiliar code, the size of the diffs, and how much of the codebase you already hold in your head. Two agents is comfortable for most people. Three is work.
So let the number of agents be set by how many diffs you will genuinely read today, not by how many cores you have. One agent working well is a better setup than four you cannot check. The other three failure modes that show up alongside this one are in why multi-agent coding fails, and a second model reading the diff cold, described in using an agent to review an agent, raises the ceiling somewhat without removing it.
landing the branches
You now have three branches and a plan file saying the order they land in. Read the file lists first, all of them, before any code:
cd ~/code/myapp
git diff --stat main...feat/schema
git diff --stat main...feat/api
git diff --stat main...feat/checkoutGit enforces none of the scope rules you wrote, so this check is the enforcement. A branch that touched directories it was not assigned is something you want to see in one line rather than three hundred.
Then take the first branch in the order, rebase it onto the base, merge it, and run the tests. Rebase before merging, not after: once a merge commit exists, rebasing rewrites shared history and turns a tidy-up into a problem.
git -C ../wt-schema rebase main
git merge --no-ff feat/schema
npm test
git -C ../wt-api rebase main
git merge --no-ff feat/api
npm testOnly when one passes do you go to the next: the API branch then rebases onto a base that already contains the schema it depends on. --no-ff keeps each slice as one identifiable merge commit, because "which piece of work introduced this" is a question you will ask next week. Boundaries leak anyway, and when they do, resolve the conflict yourself rather than handing it back to one of the two agents that caused it. That agent has no context on the other branch, so it resolves in its own favour and sounds certain about it.
The failure this prevents: merging everything at once and finding the suite red without knowing which of three branches did it. One at a time turns an afternoon of bisecting into a single obvious culprit.
then take the worktrees down
git worktree remove ../wt-schema
git branch -d feat/schemaIf remove refuses, that worktree has uncommitted or untracked files in it. That refusal is the feature: what is in there is an agent's unfinished work and you cannot see it from outside. Look before you force it.
common questions
How do you run AI coding agents in parallel?
Split the work so no two agents need the same file, give each one its own git worktree and branch, launch each inside its own directory, and merge the branches back one at a time with tests between each. The hard part is the split. If you cannot finish the sentence "this agent touches only ___" for every slice, the work does not split and you should run one agent.
How many AI coding agents can you run at once?
As many diffs as you can read carefully, which for most people is two or three. The limiting resource is human review capacity, not compute. Machines and API rate limits will let you run far more than you can honestly check, and unchecked agent output is not finished work. Agents parallelise perfectly, review does not parallelise at all, and the serial half sets your throughput.
Is running multiple AI agents faster than running one?
Only when the work genuinely splits into pieces that touch different files. When it does not, the branches conflict and the merge costs more than doing the work in sequence would have. A single agent also carries context from one piece to the next for free. Parallel agents cannot: every handoff has to be written down and read again.
Do parallel AI agents cost more?
Yes, roughly in proportion to the number running. Three agents working for an hour is about three agent-hours of tokens. Nothing about parallelism makes each agent cheaper, and a finished agent left idling in a loop keeps costing money until it is stopped. On a subscription it shows up as a rate limit rather than a bill, with less warning.
How do agents share context when running in parallel?
Through committed files, not through prompts. No agent can see another agent's context window, so a decision explained in one session is invisible to the others. Write the shared plan into the repository before starting, and have each agent commit a short handoff note under four headings: what exists now, what the names are, what was left undone, and what must not be changed.
Can you run different AI coding agents at the same time?
Yes. Claude Code, Codex CLI, Gemini CLI and others are ordinary terminal processes, so they can run side by side as long as each has its own working directory. Mixing them means each brings its own approval model and its own configuration files, which is extra setup rather than a blocker. It also means no single tool shows what all of them are doing.
one implementation
Skribbl is our attempt at putting the bookkeeping in one place: a macOS app that holds every agent, its real terminal and what the whole set is spending on a single canvas, with sessions kept in tmux so closing the window does not kill a run. It does not decide your decomposition and it does not read your diffs, which are the two steps this post says are yours. Every command above works with nothing installed. The docs describe how it works, the comparison page puts it next to the other tools in this space, and the download page has the build.
If you are running one agent at a time and it is working, keep doing that. The setup here is overhead, and it only pays for itself when the work genuinely splits.