Using Git Worktrees to Isolate Agent Changes

A worktree is an extra working directory attached to the same repository. The official documentation describes it as a way to have more than one working tree attached to a single repository, each checked out to a different branch, all sharing the same object store and refs (git-worktree docs). Nothing is duplicated: commits made in any worktree are immediately visible to the others, and you merge between them exactly as you would merge branches (Nx).

That sharing is the point and the trap. Sharing the object database keeps disk use low and keeps history consistent. But two worktrees cannot check out the same branch at once. If your main checkout has feature/x checked out, git worktree add ../wt-x feature/x fails. Each agent needs its own branch, not just its own directory.

A minimal layout for three parallel agents looks like this:

parent-dir/
├─ repo/                 <<< main checkout, stays on your working branch
├─ wt-agent-1/           <<< worktree, branch feature/agent-1
├─ wt-agent-2/           <<< worktree, branch feature/agent-2
└─ wt-agent-3/           <<< worktree, branch feature/agent-3

Everything lives under one parent directory so a single ls .. shows the whole fleet, and cleanup is one command per directory.

Start from a known state. Before adding anything, fetch and confirm the main checkout is clean, because a worktree branched from a stale or dirty base inherits the confusion. The Espressif agent-coding workshop is blunt about this: check git status and git diff, understand or commit existing changes first, and never let a new task get mixed with unfinished work (the ESP-IDF workflow guide).

cd repo
git fetch origin
git status            # must be clean enough to reason about
git worktree list     # see what already exists

Then create one worktree per agent, branching from the freshly fetched base:

git worktree add ../wt-agent-1 -b feature/agent-1 origin/main
git worktree add ../wt-agent-2 -b feature/agent-2 origin/main
git worktree add ../wt-agent-3 -b feature/agent-3 origin/main

Three details matter here. First, -b creates the new branch in the same step; if the branch already exists locally, drop -b and pass the existing name. Second, basing on origin/main after a fetch means you do not need your local main to be up to date first. Third, --no-track keeps the new branch from tracking origin/main, which is what you want when each agent branch will get its own upstream on first push (socketbox worktree setup notes).

If you are branching from an existing remote branch rather than main, the same command shape works; the older Stack Overflow question on this is still the clearest reference for the error messages you will hit (Stack Overflow).

Naming that survives the review

Name the branch after the task, and the directory after the agent or the task ID. The Espressif guide uses short prefixes (feat/, fix/, refactor/, step/) that make the intent readable in git log and in a PR list (ESP-IDF workflow). The wt/ CLI follows the same idea with standardized folder names of {reponame}-{branch-name} (Nx). Pick one convention and write it down, because the whole review loop depends on mapping a directory back to a task in one glance.

Put worktrees as siblings of the repository, not nested inside it. A nested worktree under repo/ gets picked up by file watchers, glob searches and language servers, and the agent may start editing files in a directory it did not intend to touch. Keeping them as siblings means each agent's editor, build cache and dependencies are genuinely independent, which also removes the need to reinstall packages when switching branches (Nx).

Give each agent an explicit working directory when you start it, and say so in the prompt. Something like "you are working in ../wt-agent-1, branch feature/agent-1, base origin/main" is enough. An agent that does not know its root will happily cd into the main checkout and edit there, and the isolation silently disappears.

For teams that want a cleaner root, the bare-clone pattern keeps a hidden .bare directory holding all history, with every branch as its own sibling folder:

mkdir project && cd project
git clone --bare [email protected]:org/repo.git .bare
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin
git worktree add main

That fetch refspec is the step people miss. A bare clone only fetches the default branch by default, so adding a worktree for an existing remote branch silently creates an empty branch from main instead (Git worktree like a boss). The alternative, git init --bare plus a remote, writes the correct refspec automatically and leaves no local branch until you create a worktree for it (socketbox).

Because every worktree writes to the same repository, a machine can accumulate many short-lived branches as agents come and go. The same scripting that creates them should also prune them, or the branch list becomes noise. Tooling that hooks into the Git workflow to record what each agent session did, such as the Entire CLI, is useful here, but it complements the worktree rather than replacing it.

Because all worktrees share history, review is ordinary Git. Inside any worktree you can diff against the base, see the branch log, and compare two agent branches against each other:

cd ../wt-agent-1
git diff origin/main...HEAD        # full change for this agent
git diff --stat origin/main...HEAD # size at a glance

cd ../repo
git log --oneline main..feature/agent-1
git log --oneline main..feature/agent-2
git diff feature/agent-1 feature/agent-2   # compare two agents directly

To merge the winner, check out the base branch in the main checkout and merge the branch, exactly as the Nx walkthrough describes, then remove the losing worktrees:

cd repo
git switch main
git merge --no-ff feature/agent-1
git worktree remove ../wt-agent-1
git worktree remove ../wt-agent-2
git worktree remove ../wt-agent-3
git branch -d feature/agent-2 feature/agent-3
git worktree prune

Two cautions. git worktree remove refuses to delete a worktree with uncommitted changes or untracked files; that refusal is a feature, and you should investigate before forcing it. And stale administrative entries can linger after a directory is deleted manually, which is what git worktree prune cleans up. Keeping the list tidy is a documented best practice worth automating with aliases such as git worktrees and git prunetrees (ChristopherA's worktree notes).

A clean worktree guarantees that agent A cannot see agent B's uncommitted files. It guarantees nothing about what agent A does inside its own directory. An agent told to fix an off-by-one can still rename variables, convert a callback to async, and reformat the file, all within its private worktree. The diff is isolated but still bloated.

The decision rule that works in practice is a two-layer fence. Layer one is the worktree, which handles concurrent writers. Layer two is a per-task diff budget: allowed paths, a maximum file count and a maximum changed-line count, declared when the task is created. A pre-edit hook blocks writes outside the allowed paths and feeds the reason back to the model, and a post-run check enforces the size budget. Instructions describe intent; a mechanism enforces it (the diff budget write-up).

A ready-made plugin exists for that second layer if you do not want to write hooks, though the underlying idea is the same and worth understanding before installing it (scope-guard).

The budget numbers are a judgment call, not a science. The published example uses tight limits for bug fixes and wide ones for planned refactors, with refactors tracked as their own task type rather than smuggled into a fix (diff budget write-up). For a typical bug fix, a cap of a handful of files and under a hundred changed lines keeps review to about a minute.

It also helps to tell the agent, in its instructions, what surgical means in concrete terms: touch only what you must, match existing style, do not refactor things that are not broken, and mention unrelated dead code instead of deleting it. The widely shared Karpathy Guidelines skill states the test plainly: every changed line should trace directly to the user's request (skill source). A skill like that loads only when a request matches it, so it costs nothing on unrelated turns (TypingMind listing).

Suppose you want a fix to a pagination helper, and you are running three agents to compare approaches. The sequence, with realistic bookkeeping:

1. Fetch the base and confirm the main checkout is clean. Record the base commit SHA so every review diff uses the same anchor.
2. Create three worktrees, each on its own branch from origin/main: wt-0412-a, wt-0412-b, wt-0412-c.
3. Give each agent the same task, its working directory and a budget of 4 files and 80 changed lines.
4. Let all three run in parallel. Each worktree carries its own dependencies, build cache and test runner, so nothing contends for a lock.
5. Review with git diff --stat origin/main...HEAD in each directory. If one agent's diff touches twelve files, the budget check has failed and you review that reasoning first, not the code.
6. Merge the branch whose fix is smallest and correct, then remove the other worktrees and their branches.

The payoff is measurable in review attention, not in model quality. A five-line fix takes a minute to verify; a twelve-file diff where the real fix is buried in the middle takes real attention, and attention is the resource you cannot generate (diff budget write-up).

Three operational shifts follow from moving to worktrees for agents.

First, the base branch becomes a shared contract. Every agent branches from a fetched origin/main, so a merge of one agent's work does not silently invalidate another's assumptions until the next fetch. Rebase or re-fetch before merging.

Second, rollback gets cheap. If an agent's fix is wrong, you revert the fix without dragging an unrelated refactor with it, because the refactor was never in that worktree in the first place (diff budget write-up).

Third, the boundary between temporary working state and durable history needs a policy. Agents make lots of changes while investigating, and only the final state usually matters for review; if every probe becomes a permanent commit, the branch history becomes hard to read. The Espressif guide recommends committing after each coherent, verified state instead of waiting until the end of a large task, because small commits make the agent's work easier to review, easier to compare between steps, and easier to recover from (ESP-IDF workflow).

Finally, the quality of the work still starts upstream of the worktree. Teams that split product design from technical design and write a spec the agent and the human both read report fewer surprises during implementation, because verification moves earlier and code review becomes easier rather than larger (Boundary and HumanLayer discussion). A worktree gives each agent a clean room; a good spec gives it something worth building in that room.

When you are running several agents across more than one model, wiring each worktree's agent to a single endpoint keeps the plumbing simple: Quanta Inference serves text, image, video, audio and embedding models through one OpenAI-compatible key, billed prepaid in US dollars, so an experiment can swap models per worktree without changing the harness.