# Git worktrees for agents: working in parallel without collisions

> A git worktree is an extra working folder of the same repository. Each AI agent edits its own copy and does not clash with another agent's changes.

*Tags: ai, agents, git, parallelism*

---


> [!info] Quick Definition
> A **git worktree** is an additional working folder linked to the same repository, with its own branch and its own files. When several AI agents run at once, giving each one a worktree stops them from editing the same files and colliding.


## What is a git worktree?

Usually you have one project folder with one active branch. To work on another branch without losing what you have half-done, the classic way is to save with `git stash`, switch branches and come back later. The other option is to clone the repository again into another folder. If branches or commits are new to you, start with [[git-for-designers|Git for designers]] and [[branches-and-pull-requests|branches and pull requests]]; here we only cover what changes when an agent is the one doing the work.

A worktree is a middle ground. According to the Git documentation, the new worktree is linked to the current repository and shares everything except per-worktree files such as `HEAD` and the index. In other words: two folders, one history.

```bash
# creates the folder ../project-login with a new branch called feature-login
git worktree add ../project-login -b feature-login

# creates a worktree on a branch that already exists
git worktree add ../project-review fix-signup

# lists the repository's worktrees
git worktree list

# deletes the worktree when you are done
git worktree remove ../project-login
```

Two details from the documentation matter with agents. If you run `git worktree add <path>` without naming a branch, Git uses a branch named after the folder (and creates it if it does not exist). And Git refuses to create a worktree on a branch that is already checked out in another one, unless you force it with `--force`.

## Why does it matter to an agent?

An agent that edits files writes directly into the folder it runs in. If you launch two in the same folder, they can:

- edit the same file and leave changes half applied,
- run tests that fail because of the other agent's work,
- make mixed commits that are hard to review,
- and, if one runs a cleanup, delete what the other was doing.

With one worktree per agent, each has its own files and its own branch. When it finishes, it hands over a reviewable branch and a pull request of its own. The reviewer can approve one, ask for changes on another and discard a third without touching the rest (more in [[reviewing-agent-prs|human review of agent PRs]]).

Several tools already do this for you, according to their official documentation:

- **Claude Code.** `claude --worktree feature-auth` creates the folder `.claude/worktrees/feature-auth` on the branch `worktree-feature-auth`. By default the branch starts from the remote's default branch, not from your local `HEAD`; setting `worktree.baseRef` to `"head"` starts it from your current work. A `.worktreeinclude` file copies ignored files such as `.env` into each new worktree. A [[subagents|subagent]] can be declared with `isolation: worktree`, and its temporary worktree is removed automatically if it made no changes.
- **Codex (app).** It creates managed worktrees in `$CODEX_HOME/worktrees` and by default works in a detached `HEAD`, not tied to a branch. It keeps the 15 most recent by default and does not delete one while its chat is still in progress.
- **Cursor.** In its agents window, each task sent to a worktree gets a separate checkout. A `.cursor/worktrees.json` file defines the setup commands and, from Cursor 3.5, cleanup keeps a default maximum of 25 worktrees per machine.

For the bigger picture of coordination, see [[agent-orchestration|agent orchestration]] and [[parallelizing-agents|how to parallelize work across agents]].

## What is shared and what is not?

| Shared | Not shared |
|---|---|
| Commit history | Per-worktree state files (`HEAD`, index) |
| Branch references (`refs/`, except cases such as `refs/bisect`) | Active branch: each worktree has its own |
| Repository configuration (by default) | Installed dependencies (`node_modules`, virtual environments) |
| Configured remotes | Ignored files such as `.env`, and local databases |

The last row is the one that bites most. A new worktree is a clean checkout: it brings no dependencies and no ignored files. You need to install, copy the `.env` (with `.worktreeinclude` if the tool supports it) and, if your tests use a local database, give each worktree its own. Cursor also advises against symlinking dependencies into a worktree and suggests fast package managers such as pnpm or uv.

## What is the life cycle of an agent worktree?

1. **Create.** One worktree per task, named for what it does (`fix-signup`, not `test2`).
2. **Prepare.** Install dependencies, copy environment variables and point to a database of its own.
3. **Launch the agent** inside that folder, with a bounded task.
4. **Review.** Open a pull request from its branch and review only its files.
5. **Merge or discard.** Either way, the worktree and its branch are no longer needed.
6. **Clean up.** `git worktree remove <path>` refuses to delete a worktree with modified or untracked files; with `--force` it allows it, and that work is lost. For records of worktrees whose folder no longer exists, `git worktree prune` removes them.

## When should you NOT use them?

- When two agents' work depends on each other in real time. A worktree separates them too much and you end up integrating by hand.
- When the project is very large and every worktree needs heavy dependency installs. Disk space and install time multiply.
- When you will not review the resulting branches. Creating ten worktrees and leaving them unreviewed only produces orphan branches.
- When the repository uses submodules. The Git documentation warns that submodule support with multiple checkouts is incomplete and does not recommend multiple checkouts of a superproject.

## Example

Illustrative example: you have a product with a broken sign-up form and a pricing page to redesign. You create two worktrees:

```bash
git worktree add ../app-fix-signup -b fix-signup
git worktree add ../app-pricing-v2 -b pricing-v2
```

You launch one agent in each folder. The sign-up agent runs the form tests in its folder; the pricing agent changes components in its own. Neither sees the other's changes until you merge them separately. When the sign-up agent finishes, you open its pull request and review only its files. After merging it, you run `git worktree remove ../app-fix-signup` and the folder is gone.

## Common mistakes

- Creating worktrees and never deleting them. Old folders pile up and confuse everyone.
- Assuming a worktree has its dependencies installed. It does not; install before running tests.
- Assuming the agent starts from your current branch. In Claude Code it starts from the remote's default branch by default: your unpushed local commits will not be there.
- Using the same local database in every worktree. Migrations and test data collide.
- Trying to check out a branch that is already open in another worktree. Git refuses, and it is right to.
- Deleting the folder with `rm -rf` instead of `git worktree remove`. Git keeps the record of a worktree that no longer exists until you purge it with `git worktree prune`.

## Sources

- [git-worktree: official Git documentation](https://git-scm.com/docs/git-worktree)
- [Run parallel sessions with worktrees (Claude Code documentation)](https://code.claude.com/docs/en/worktrees.md)
- [Subagents in Claude Code (documentation)](https://code.claude.com/docs/en/sub-agents)
- [Git worktrees (Codex, OpenAI documentation)](https://learn.chatgpt.com/docs/environments/git-worktrees)
- [Worktrees (Cursor documentation)](https://cursor.com/docs/configuration/worktrees)


---

Source: https://www.fernandoux.com/en/wiki/ai/git-worktrees-for-agents/