Parallel coding agents in separate git worktrees

Running several coding agents at once is easy to start and surprisingly easy to get wrong. The usual first step is to give each agent a separate worktree, so that one agent editing files does not disturb another. That step really does solve the file-editing problem. It does not solve the rest of the shared machine: the branch each agent commits to, the network port its dev server opens, the untracked files it needs, and every path outside the checkout that more than one process writes to. This guide explains what a worktree isolates, then goes through the five places where parallel agents still collide, and closes with a pre-launch comparison for your own launcher.

What a worktree isolates and what stays shared

According to the Git manual, one repository can have several working trees, so more than one branch can be checked out at the same time. The first one is the main worktree, and each extra one is a linked worktree (git-worktree manual). A linked worktree shares the repository with the others, with the exception of per-worktree files such as HEAD and the index. The manual adds that the refs under refs/ are shared, while pseudo refs such as HEAD belong to a single worktree (git-worktree manual).

Put plainly, each agent gets its own set of files and its own idea of the current commit, but the branches, tags and history are one common pool. Whatever one agent commits to a branch name, every other worktree can see. That is exactly what you want for merging results later, and it is also why the first two collisions below exist.

Nothing in that description says anything about processes, ports, environment variables, databases or caches. Git does not know about them. Everything outside the checkout is yours to separate.

Collision one: the same branch in two places

By default, git worktree add will not check out a branch if some other worktree is sitting on it. The refusal is a safeguard, and the force option overrides it (git-worktree manual). Scripts written in a hurry can reach for that option the first time they see the error, and from then on two agents commit to one branch, each one moving the branch under the other.

The same page describes the -B flag, which resets an existing branch to the commit you name. If a launcher uses it with a fixed branch name on every run, a rerun resets that branch to the starting commit, so commits the earlier agent made on it are no longer reachable from the branch. The manual describes a default refusal when the branch is already in use by a second worktree, and we did not test how it interacts with this flag, so try it on your git version; the risk is greatest when the earlier worktree is gone or the force option is added to get past a refusal.

The fix is boring. Give every agent a new branch of its own, named after the task, all created from one starting commit. Many different branch names pointing at a common ancestor are perfectly safe; the trouble is only ever one branch name used twice. When the work is throwaway, a detached checkout avoids the question completely, because it belongs to no branch.

Collision two: a fixed port

Each agent that runs the project usually starts something that listens: a dev server, a preview, a test harness with a built-in server. If the port number is written into the config file, and the config file is tracked by git, then every worktree carries the same number. The first agent starts normally. The second either crashes with an address-in-use error or, worse, talks to the first agent's server and reports results about the wrong code.

This one is not a git fact; it is general practice. Derive the port from the agent's index, or let the program pick a free one and report it back, or use a unix socket path that includes the agent's name. Then read the chosen address from the program's output rather than assuming it. Two servers that never run in the same minute can share a number; the rule only matters for processes that overlap in time.

Collision three: the file git does not carry over

Creating a worktree checks out a commit afresh, so the folder contains the tracked files and nothing else. Anything that you keep out of version control stays behind in the original folder. That typically means the local environment file, a private key, an editor-specific config, or a downloaded fixture. The agent starts, the app complains about a missing setting, and the agent then tries to be helpful by inventing one.

Two cases need attention. If the file is needed, the launch step has to copy or link it into each new worktree. And if the file is something the agents write, such as a local settings file they update, then linking one shared copy into all of them means two writers on one file. One copy that all agents merely consult is fine; one copy that they modify is not.

Also decide who may see secrets. A copied key in a worktree that an agent then pushes or logs is a leak of its own, so copy only what the task truly needs.

Collision four: writes outside the worktree

Inside a worktree an agent can write what it likes. The collisions come from paths that are not inside any worktree: a compiled-output directory in the home folder, a shared cache, a single database file in a temp location, a log file with a fixed name, a lock file that every run tries to create. Two agents writing the same database file will corrupt each other's test data in ways that look like flaky tests. Two builds into one output directory produce a mixture of both.

The cure is to put every writable thing under a path that contains the agent's name or lives inside its own worktree, and to pass that path in explicitly. A useful habit is to search the project's scripts and configuration for absolute paths and for temp-directory names, since those are the usual shared ground. Read-only shared folders, such as a downloaded dependency cache that nothing modifies, can stay shared.

Collision five: worktrees nobody removes

Every linked worktree is a full set of files on disk, plus administrative records inside the repository. The manual says to remove a linked worktree with git worktree remove when you are finished with it. The command refuses to remove one that holds untracked files or modifications unless forced, and it never removes the main worktree (git-worktree manual).

If somebody deletes the folder by hand instead, the manual says the leftover records are cleaned up eventually, or at once with git worktree prune (git-worktree manual). A launch script that creates worktrees and has no matching cleanup step leaves a growing pile of directories, stale branches and half-finished work. Add the cleanup to the same script that creates the worktrees, run it on failure as well as on success, and look at what the refusal to remove tells you: an unclean worktree usually holds work you have not looked at yet, so check it before forcing anything.

A pre-launch check

Before you start several agents, write down for each one: its worktree path, its branch, its start commit, the port or socket it will use, the files it needs that git does not track, and every path it will write outside its worktree. Then compare the rows against each other. Any value that appears twice in a column that should be unique is a collision. Finally, confirm that the script ends with a removal step for each worktree it created.

To see that your comparison can actually fail, feed it a deliberately bad plan with one branch name or one port repeated, and make sure it gets noticed.

When this does not apply

Worktree advice presumes one machine, one repository and several agents working in it together. Agents running in separate containers or virtual machines are out of scope, because ports, temp folders and environment files are already isolated there and only the branch question remains. Repositories with submodules are also left out: the Git manual itself calls multiple checkouts experimental and says submodule support is incomplete, and it advises against several checkouts of a superproject (git-worktree manual). We ran no experiments for this guide. The port, secret-file and shared-path advice is general engineering practice rather than a quotation from a source, and your tools may behave differently from the common case, for example by picking ports on their own or keeping caches inside the project. Git behaviour can also change between versions, so confirm details against the manual of your installed version.

Once the parallel agents finish, each one will report that it is done. Check those reports before you merge; a bare claim of success is not enough, as the article about reports that sound complete argues.

Reviewing a launch plan

When a launch plan deserves another pair of eyes before it runs, our git-worktree-parallel-agents skill takes a plan or a shell script that launches several agents in worktrees. It reports only the five collisions described above, every finding on its own line, that names a code, where the problem sits, why it breaks and how to fix it: a branch used twice, a shared fixed port, a missing or shared untracked file, a shared write location, and leftover worktrees. It leaves harmless look-alikes alone, for example two branches that share an ancestor, and a sound plan gets one short line saying nothing was found. The store itself is at https://aiskills402.com.