Git worktrees for parallel AI coding agents

What is a git worktree, and why do agents need one?

A worktree is a second working directory for the same repository. The git documentation puts it this way: a repository can support multiple working trees, which lets you check out more than one branch at a time. Each worktree has its own files, HEAD and index, and all of them share the repository’s history.

That is what parallel agents need. Two agents in one folder edit the same files, and neither knows. With a worktree each agent gets its own copy to change, and you decide what to merge.

The tool makers agree. Claude Code, Codex, Cursor and Gemini CLI all document worktrees as a way to run parallel sessions. Cursor’s docs say to use them when you want to start several agents on the same repo without conflicts. If you want the wider picture first, read our guide to running several Claude Code sessions at once.

Which git commands do you need?

A handful of commands cover almost everything:

git worktree add ../app-auth -b auth creates a directory next to your project, on a new branch named auth. git worktree add ../app-hotfix fix-login checks out an existing branch instead.

git worktree list shows every worktree and its branch. git worktree remove ../app-auth deletes one when you are done. Git only removes clean worktrees, with no untracked files and no changes to tracked files, unless you add --force.

git worktree prune cleans up the bookkeeping if you deleted a folder by hand.

For a throwaway experiment, git worktree add -d ../app-scratch makes a worktree with a detached HEAD at the current commit, tied to no branch.

One rule trips people up. A branch can be checked out in only one worktree at a time. If you ask for a branch that is checked out elsewhere, git refuses unless you pass --force. Codex’s docs make the same point: if a branch is checked out in a worktree, you cannot check it out in your local checkout at the same time.

What do the agent CLIs do for you?

As of October 2026, from each vendor’s documentation:

Claude Code: claude --worktree feature-auth (or -w) creates .claude/worktrees/feature-auth/ on a branch called worktree-feature-auth. When you exit, it checks the worktree for changed files and new commits, and asks before it removes one that holds work. One surprise: by default the new worktree branches from your repository’s default branch on the remote, so your unpushed commits are not in it unless you set worktree.baseRef to head. See the worktrees docs.

Gemini CLI: worktrees are experimental. Set experimental.worktrees to true, then run gemini --worktree feature-search. It creates the worktree under .gemini/worktrees/ and leaves it in place when you exit, so you clean up yourself. See the Gemini CLI worktree docs.

Cursor CLI: agent --worktree creates worktrees under ~/.cursor/worktrees/<repo>/<name>, and a .cursor/worktrees.json file can run setup commands such as npm ci. Details are in the Cursor worktree docs.

Codex: worktrees live in the ChatGPT desktop app. Choose Worktree in a new chat, pick the starting branch, and use Handoff to move a chat between your local checkout and the worktree. See the Codex worktree docs.

What does a new worktree not have?

A worktree is a fresh checkout of tracked files, so anything git ignores is missing: node_modules, .env, build output, caches and local databases.

Install dependencies in each worktree. Claude Code can copy gitignored files for you if you list them in a .worktreeinclude file, which uses .gitignore syntax. Cursor’s setup-worktree commands do the same job, for example npm ci followed by a copy of your .env. Cursor’s docs advise against symlinking dependencies into a worktree because it can cause problems in the main checkout.

Two more traps are easy to miss. Dev servers want the same port, so give each worktree its own, or the second one will fail to start. And if two worktrees run migrations against one local database, a schema change from one branch can break the other.

Submodules deserve a warning. The git docs say multiple checkout is still experimental, support for submodules is incomplete, and it is not recommended to make multiple checkouts of a superproject.

How do you review, merge and clean up?

Review each branch on its own. git diff main...auth shows what the branch changed since it split from main, and git diff --stat main...auth gives the file summary. Run the project’s checks inside that worktree, not in your main folder.

Merge one branch at a time. After each merge, update the next branch from main and run its checks again. Two branches that pass alone can still conflict.

Then remove the worktree and its branch. If a worktree has uncommitted work, git worktree remove will refuse. That refusal is a feature: commit or copy what you want first, because --force throws the changes away.

Skip the bookkeeping

SwarmPane’s Layouts can open a launch set of agents in one click, each in its own worktree if you want, and the Files, Git and Find tools beside the terminals let you review the diff and open a worktree without leaving the window. Agent Race works in separate copies of the project too, so two agents can take the same task without touching each other’s files.

It runs the agent CLIs and accounts you already have. Start with a 7-day trial for $1 and try three agents on three branches.