Git worktrees are the missing piece for AI agents

Git worktrees existed long before anyone was running agents, and hardly anyone used them. Then a use case arrived that they fit exactly.

What a worktree is

A worktree is a second working directory attached to one repository. It has its own checked out branch, its own index and its own files on disk, and it shares the repository's object store and refs with every other worktree.

git worktree add ../parser-agent-a -b agent/a

That gives you a directory with your project in it, on a new branch, that is genuinely the same repository. Commits made there are visible from your main checkout immediately. No remote involved, no syncing, no second clone taking up space.

Why this is the right shape for agents

An agent needs three things from a workspace, and a worktree gives all three.

• Real files. Agents run builds, tests and formatters. They need a working tree those tools recognise, not a virtual filesystem or a diff to be applied later.
• Isolation from other agents. Its own working tree and its own index means another agent's edits, staged changes and branch switches are invisible to it.
• A shared history. Its work is already in your repository the moment it commits. Getting the result is a merge, not a transfer.

The alternatives all fail at least one of these. A full clone breaks the shared history. A container breaks the real-files property in practice, because now your toolchain lives somewhere else. A shared folder breaks isolation, which was the whole problem.

The parts that bite

Worktrees are simple until you automate them, and then a few things reliably go wrong.

Untracked files do not come with you

A new worktree is a clean checkout. Your .env, your local config, your build cache, anything gitignored: none of it is there. An agent lands in a directory where the project does not build, reports that the project does not build, and it is right.

Whatever your project needs that is not in git has to be placed in the worktree before an agent starts.

One branch, one worktree

Git will not check out the same branch in two worktrees. This is a good rule that saves you from a genuine mess, and it will still surprise you the first time automation tries it. Every agent needs its own branch name.

Cleanup is not automatic

Remove the directory and git still lists the worktree until you prune it. Do this a hundred times without cleanup and you have a repository full of stale entries and abandoned branches.

git worktree remove ../parser-agent-a
git worktree prune

Uncommitted work at the end

Agents stop for all sorts of reasons, and not always at a commit. If your only channel for getting work back is the branch, anything an agent left in its working tree is silently dropped.

The result you want is one branch that has everything, including what the last agent forgot to commit, with real conflicts reported rather than half applied.

Doing it per run

The loop for a run of parallel agents looks like this:

1. 01Create a worktree and a branch per agent.
2. 02Copy in the untracked files the project needs.
3. 03Start each agent in its own worktree.
4. 04Collect every branch, including uncommitted leftovers, onto one branch.
5. 05Remove the worktrees and prune.

None of these steps is hard. All of them are fiddly, and step five is the one that gets skipped.

Built in

Nuvoa does this per pane. Opening a pane gives that account a worktree and a branch of its own, so two agents can work on one project at the same time without overwriting each other. Your commits are still yours, your tools behave the way they do in your own terminal, and your main checkout is never touched.

At the end, every agent's work is brought together onto one branch for you to read, and a genuine conflict is reported as a conflict rather than quietly half applied. That claim ships with a check that proves it.

Each pane is also signed in as its own account, which is the other half of running several agents at once. Join the waitlist.