---
title: "Do you need git worktrees to run AI coding agents in parallel? · Cork"
description: "Not always. When a worktree per agent pays off (a long feature on its own branch, a stable tree to build and test in, competing attempts), when one shared checkout is the better choice, and what worktrees cost once they pile up."
canonical: "https://corkcli.com/guides/do-you-need-git-worktrees-for-ai-coding-agents"
last_updated: "2026-10-16"
---

# Do you need git worktrees to run AI coding agents in parallel?

Not always. "One worktree per agent" has become the default advice, and it is good advice for some work. A worktree solves one specific problem: two agents writing the same files, or running git commands, in one folder. It also brings costs of its own. This guide sorts the work that needs a worktree from the work that runs better in one shared checkout, and says what a shared checkout needs in place of one.

Page: https://corkcli.com/guides/do-you-need-git-worktrees-for-ai-coding-agents

## What a worktree actually gives an agent

A linked worktree is a second folder attached to the same repository, with its own checked-out branch, its own index (staging area) and its own files on disk. History and branches are shared: a commit made in one worktree is visible to the others as a branch right away, but their files do not change until they merge or rebase. By default git refuses to check out a branch that another worktree already has checked out, so two agents cannot end up on the same branch by accident.

So a worktree gives an agent three things: files nobody else is writing, a branch of its own, and git state (index, HEAD, stash) nobody else can disturb. What it does not give is any knowledge of what the other agents are doing. Setup commands: [Git worktrees for parallel AI coding agents: setup and limits](https://corkcli.com/blog/git-worktrees-parallel-ai-coding-agents).

## What goes wrong in one shared checkout

When several agents work in one folder they share the files, the index and HEAD:

- **Lost writes.** Agent A reads a file, agent B edits it, A writes its version based on what it read. B's change is gone and neither agent knows.
- **Mixed commits.** One agent runs `git add -A` or `git commit -a` and its commit now holds the other agents' unfinished edits. Agents in a shared checkout should stage by explicit file list.
- **Whole-tree git commands.** `git checkout` of another branch, `git stash` or `git reset --hard` changes or throws away every agent's files at once.
- **Moving ground for tests.** A build or test run sees whatever the other agents have half written, so a failure may not be yours.

A worktree per agent removes all four at once, which is why it became the default. But the first three can also be handled inside one checkout, and the fourth only matters for some work.

## When a worktree is the right call

- **A long feature on its own branch.** A multi-step change (a new module, a migration, a refactor that touches many files) that should land as one reviewed branch. The agent commits as it goes, and nothing it does half way through reaches anyone else.
- **A stable tree to build and test in.** A long build, a full test suite or a benchmark needs files that do not change under it. In a shared checkout another agent's unfinished edit can break the run, and the failure is hard to attribute.
- **Competing attempts.** Two or three agents on the same task, keeping the best result, only works if each attempt has its own files and branch.
- **Throwaway experiments and other branches.** Work you may discard, or work that needs a different branch checked out (reviewing a pull request, fixing a release branch) while other agents keep going.

## When one checkout is the better choice

- **Small parallel edits.** Five agents each fixing a small bug in a different part of the code do not need five checkouts, five installs and five branches to merge. For a ten-line fix, the review-and-land overhead of a branch is most of the work.
- **Work that builds on other work in flight.** If agent B needs the function agent A is writing right now, separate worktrees keep B from seeing it until A commits and B merges or rebases. In one checkout B sees A's work as it lands.
- **Expensive setup.** A worktree is a fresh checkout of tracked files. Dependencies, build caches and gitignored files such as `.env` are set up again in each one, and dev servers need distinct ports. Claude Code can copy gitignored files listed in `.worktreeinclude` into each worktree it creates; installs and services still cost time and disk per worktree.

## The choice at a glance

| The work | Where to run it |
|---|---|
| A multi-step feature that lands as one reviewed branch | Worktree |
| A long build or test run that must not see other agents' edits | Worktree |
| Two attempts at the same task, keep the better one | Worktree each |
| An experiment you may throw away | Worktree |
| Reviewing or fixing another branch while agents keep working | Worktree |
| Several small fixes in different parts of the code | One checkout, with a guard |
| Tasks that build on each other's unfinished work | One checkout, with a guard |
| Setup per checkout takes minutes (big installs, services) | One checkout, with a guard |

## What a shared checkout needs instead

Without a guard, a shared checkout loses edits. The options, from lightest to strongest:

- **File ownership in the prompt.** Tell each agent which paths it owns and that it must ask before editing anything else. It removes most overlap, but it is a request, not a rule.
- **Deny rules for whole-tree git commands.** Block `git reset`, `git stash`, `git clean` and branch switches wherever your agent tool supports deny rules (in Claude Code, `permissions.deny` in `.claude/settings.json`), and ask for staging by file list.
- **A hook that enforces ownership.** A PreToolUse hook in Claude Code or Codex can block an edit outside an agent's paths. Working script: [How to stop Claude Code agents from overwriting each other's changes](https://corkcli.com/blog/stop-claude-code-agents-overwriting-changes).
- **A write gate.** A check on every edit that holds it when another agent is changing that code right now, instead of relying on ownership drawn up in advance. See [Write gate](https://corkcli.com/blog/write-gate).

Whichever you choose, merge-time problems are the same in both setups: land one branch, or one batch of commits, at a time, rebased onto what already landed and with the tests rerun. A rename by one agent plus new calls to the old name by another merges cleanly and breaks the build (a [semantic merge conflict](https://corkcli.com/blog/semantic-merge-conflicts)), with or without worktrees.

## The cost people forget: worktrees pile up

Agent tools now create worktrees for you. Claude Code keeps them under the repo's `.claude/worktrees/`, Cursor's parallel agents under `~/.cursor/worktrees/`, and the Codex app and Conductor in their own folders. Some cleanup is built in (on exit, Claude Code removes a clean unnamed worktree and asks about one with changes or commits), but worktrees whose branches have long since merged still accumulate, each holding a full set of files and often its own dependencies. Run `git worktree list` in a repo where agents have been busy for a few weeks and the count is usually a surprise.

Removing them safely: [How to clean up the git worktrees your AI coding agents leave behind](https://corkcli.com/guides/clean-up-git-worktrees-ai-coding-agents).

## How Cork fits

[Cork](https://corkcli.com) is the coordination layer for parallel coding agents. With Cork in a checkout, every write by Claude Code, Codex or Cursor is checked against other agents' live changes before it lands, and only a real collision is stopped, with the tool result naming who and what. That is the guard a shared checkout needs, so agents can work in the main checkout without a worktree each.

It does not argue against worktrees. In a repo that has agent worktrees, Cork tells each agent at session start that it does not need one just to avoid overwriting other agents, as a recommendation rather than a rule: a worktree is still right for a multi-step feature built and tested on its own branch, and Cork follows the agent there too. Agents in different worktrees also hear when another agent renames or re-signatures code they depend on, which is the part worktrees leave open.

For the pile-up, Cork removes finished agent worktrees in the background: only ones an agent tool made, that are unlocked, merged, have no changes and have sat untouched for a day. It uses plain `git worktree remove`, keeps every branch, and says what it removed and how to bring one back. To turn it off, set `{ "tidy_worktrees": false }` in `.cork/config.json`, or `CORK_TIDY_WORKTREES=0`.

Cork, free and local, covers one machine with no account:

```sh
curl -fsSL https://corkcli.com/install.sh | sh
```

## Common questions

### Do I need a git worktree for every AI coding agent?

No. A worktree solves one problem: two agents writing the same files, or running git commands, in one folder. If something else stops lost writes in a shared checkout (strict file ownership, a hook that blocks out-of-bounds edits, or a write gate that holds an edit against code another agent is changing), small parallel tasks run fine in one checkout. Use a worktree when the work itself needs its own branch or its own stable tree.

### When is a worktree the right call?

A multi-step feature that should live on its own branch and land as one reviewed change; a stable tree for a build or a long test run that should not see other agents' half-finished edits; two or more competing attempts at the same task; risky work you may throw away; and any time you need a different branch checked out, such as reviewing a pull request while another agent keeps working.

### What goes wrong when several agents share one checkout?

They share the files, the index and HEAD. Agent A can write a file based on a version it read before agent B changed it, and B's change is gone. One agent's `git add -A` or `git commit -a` sweeps the others' unfinished edits into its commit. `git checkout` of another branch, `git stash` or `git reset --hard` changes or discards everyone's files at once. And a test run sees whatever the other agents have half written.

### Do worktrees stop merge conflicts between agents?

No. They stop agents overwriting each other while they work and move every conflict to merge time. Semantic conflicts, such as one agent renaming a function while another adds new calls to the old name, merge cleanly and break the build. You still need to land one branch at a time with a rebase and a test run, or live notice of each other's changes.

### What do worktrees cost?

Each worktree is a fresh checkout of tracked files: dependencies, build output and gitignored files such as `.env` have to be set up again, two dev servers on the same port clash, and each one takes disk. Each is also a branch someone has to review and merge. And they pile up: agent tools create them faster than people remove them, so finished worktrees can sit on disk long after their branches merge.

### Does Cork replace git worktrees?

Partly. With Cork in a checkout, every write is checked against other agents' live changes before it lands, and only a real collision is stopped, with the tool result naming who and what. That covers the reason most people reach for a worktree per agent. A worktree is still right for a multi-step feature you build and test on its own branch, and Cork works there too. Cork also tidies finished agent worktrees: merged, clean, unlocked and untouched for a day.

## Related

- [Cork vs git worktrees](https://corkcli.com/blog/cork-vs-git-worktrees)
- [Multiple AI coding agents, one codebase](https://corkcli.com/guides/multiple-ai-coding-agents-one-codebase)
- [Install Cork](https://corkcli.com/install)