Git worktrees for agents: working in parallel without collisions

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 and 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.

# 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 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 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 and how to parallelize work across agents.

What is shared and what is not?

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:

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
• Run parallel sessions with worktrees (Claude Code documentation)
• Subagents in Claude Code (documentation)
• Git worktrees (Codex, OpenAI documentation)
• Worktrees (Cursor documentation)