What are parallel coding agents?

What are parallel coding agents?

Parallel coding agents are two or more coding agents that work in the same codebase at the same time, each on a separate task. Developers also call this running multiple coding agents. Each agent usually gets its own branch and copy of the files, e.g. in a Git worktree. A person usually reviews each branch before it merges.

The agents can be several sessions of one tool, e.g. Claude Code in separate terminals. One agent can also start several subagents at once, each with one part of a larger task. Subagents usually share the parent's checkout unless each runs in its own worktree.

Separate copies keep the agents out of each other's files. In one shared checkout, one agent can overwrite another agent's edits, and each agent's test run includes the other's unfinished changes. With separate copies, the changes meet only at the merge.

How do git worktrees isolate parallel agents?

A Git worktree is an extra working directory linked to the same repository, usually with its own branch checked out. Git's documentation says one repository can support several working trees, "allowing you to check out more than one branch at a time." A parallel setup usually works in these steps:

1. A developer runs git worktree add once for each task, with a path and a branch name.
2. Git creates the directory and checks out the branch in it.
3. The developer starts one agent in each directory, and each agent edits the files there.
4. Each agent commits to its own branch. The branches live in the shared repository, so the main checkout can merge them without a push or a fetch.
5. After the merge, the developer deletes the worktree with git worktree remove.

Each worktree has its own working files, its own HEAD, and its own index, which holds the staged changes. The worktrees share the history, the branches, and by default the repository settings. Git normally refuses to check out one branch in two worktrees at once. A second clone also gives an agent its own files, but its branches reach the main checkout only through a push or a fetch.

A worktree starts with only the files that Git tracks. Untracked files, e.g. a local .env file, are not copied, so each worktree needs its own setup and installed dependencies. Claude Code's documentation describes a --worktree flag that gives each parallel session its own worktree. Claude Code also copies ignored files listed in a .worktreeinclude file into each worktree it creates.

A worktree on its own does not stop an agent's commands from writing outside its directory. A sandbox for each agent limits which files and network hosts its commands can reach. A container or virtual machine sandbox also separates processes and ports.

What is an example of parallel coding agents?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme gives two coding agents one task each and starts them in separate worktrees:

git worktree add -b address-edit ../acme-address
git worktree add -b clear-cart ../acme-orders

The work then runs in this order:

1. Agent A, in ../acme-address, gets the request "Let customers edit their delivery address during checkout." It adds an address form that calls checkout.save() to store the edited address.
2. Agent B, in ../acme-orders, gets the request "Empty the cart after a customer places an order." It adds cart.clear() inside checkout.save(), because on its branch that function runs only when a customer places an order.
3. Each agent runs npm install and then npm test in its own worktree, and both test runs pass.
4. The developer merges clear-cart into main, then address-edit. Git reports no conflict, because the two branches changed different files.
5. On the merged code, the developer adds 2 items to the cart and changes the address. The address saved, but the cart emptied.

Neither branch had the bug on its own. Agent A's form calls a function whose job Agent B changed, and no test ran the two changes together. This example is simplified. A real project would also need a test that changes the address and then checks the cart.

What conflicts do parallel agents create?

Parallel agents create three kinds of conflict:

• Merge conflicts. Two branches change the same part of a file, and Git stops the merge until a person or an agent picks the result. Files that many tasks touch, e.g. a dependency lock file, conflict often. Worktrees move these conflicts to merge time but do not prevent them.
• Intent conflicts. Two changes merge with no text conflict, but together they make the software do something neither task asked for. This is also called a semantic conflict, and the Acme merge is one. The tests on each branch can pass, because neither branch contains the other change.
• Shared state conflicts. Agents on one machine can share a local database and development server ports, even when their files are separate. One agent's test run can then change data that another agent's run depends on, which test isolation addresses.

Intent conflicts are the hardest to find, because the merge looks clean. They usually appear as a regression, a feature that worked before the merge and fails after it. An agent that changes a shared function without checking its callers is one reason coding agents break working features, even with no second agent involved. Giving each agent separate files reduces merge conflicts, but the Acme merge shows it does not prevent intent conflicts.

What are the limits of running agents in parallel?

Running agents in parallel has these limits:

• A worktree separates files, not the machine. Each worktree needs its own installed dependencies, so disk space and memory cap how many agents one laptop can run. A dev container for each worktree separates more, and each agent can get its own database from one test data seeding script.
• Review does not run in parallel. Each agent's pull request still needs a person to read it, one at a time. More agents add to the review bottleneck, and smaller tasks keep pull request size down.
• Attention is shared. Several agents can pause for approval at once, and answering many prompts in a row can lead to approval fatigue. Approving safe commands in advance keeps human-in-the-loop prompts for the risky actions.
• Later branches go stale. Each merge changes the main branch under the agents that are still working, so their branches need an update and a fresh test run before they merge. A merge queue tests each approved pull request with the main branch and the changes ahead of it.

How are parallel agents different from background agents?

A background coding agent works on a task without a person watching, often on a remote machine, and returns a branch or pull request. "Parallel" describes how many agents run at once, and "background" describes whether anyone watches them.

The two often overlap. A developer who starts several background agents on separate tasks is running parallel agents, and each remote agent usually gets its own environment instead of a worktree.

How do you check each agent's change on its own?

Test each branch in its own worktree, with its own database and port. After each merge, run the tests again on the merged code. Also use the changed features there, because an intent conflict can pass the tests on each branch.

RunStory runs your software in a separate environment, tries relevant workflows, and checks the results. You keep working. It is in private alpha for CLIs and web apps, and the alpha tests your software in isolated sandboxes.

Join the RunStory alpha →

FAQs

What is the difference between a git worktree and a branch?

A Git worktree is a directory where Git checks out files, and a branch is a named line of history. A branch can exist without being checked out anywhere. Each worktree usually has one branch checked out, and by default Git refuses to check out the same branch in two worktrees at once.

Can two agents edit the same file at once?

Two agents can edit the same file at once, but only separate copies keep both edits. In one shared checkout, the agent that writes last can overwrite the other agent's edits. In separate worktrees, both edits survive until the merge, where Git reports a conflict if they changed the same part of the file.

Do parallel agents need separate databases?

Parallel agents need separate databases when their tests or development servers write data. A worktree separates only files, so agents on one machine share a local database unless each agent gets its own. Loading each database from the same seed script gives every agent the same starting data.

How do you merge work from several agents?

Work from several agents goes into the main branch one branch at a time. Before each merge, the next branch is updated and tested again, and a merge queue can run those checks in order. Tests find only the clashes they cover, so using the changed features on the merged code can also catch an intent conflict.