Git worktrees for AI coding agents

Short answer: a git worktree is a second (or tenth) working directory attached to the same repository, each with its own branch checked out. AI coding agents use worktrees so several agents can edit the same repo at once without overwriting each other's files. Create one with git worktree add -b my-task ../my-task, run an agent inside it, and merge the branch when you're done.

What a git worktree is

A normal clone has one working directory. git worktree lets one repository have several, each checked out to a different branch (git docs).

What the worktrees share: the object database (so history isn't duplicated), refs and the repo config. What each worktree has on its own: HEAD, the index and the working files. A commit made in one worktree is visible from the others right away, because they all read the same objects.

The commands you need

# New worktree on a new branch, starting from HEAD
git worktree add -b fix-login ../repo-fix-login

# New worktree on an existing branch
git worktree add ../repo-feature-a feature/a

# Throwaway worktree with no branch
git worktree add --detach ../repo-scratch

# See them all
git worktree list

# Remove one (refuses if it has uncommitted or untracked changes)
git worktree remove ../repo-fix-login
git worktree remove --force ../repo-fix-login

# Clean up entries for directories you deleted by hand
git worktree prune

There are also lock, unlock, move and repair for less common cases.

Limits and gotchas

• One branch, one worktree. You can't check out the same branch in two worktrees. Git stops you with an error like fatal: 'feature/a' is already used by worktree at '<path>'.
• Untracked files don't come along. A new worktree is a fresh checkout of tracked files only. Your .env, .env.local and node_modules are not there. Copy env files and install dependencies in every worktree.
• Disk and install time. History is shared, but working files and dependency installs are not. Ten worktrees means ten node_modules.
• Ports collide. Two dev servers started from two worktrees will both try to use port 3000. Give each one its own port.
• Git LFS. Large files may need a git lfs pull in the new worktree.
• Stale entries. If you rm -rf a worktree directory instead of using git worktree remove, run git worktree prune.
• Ignore the folder. If your tool puts worktrees inside the repo, add the folder (for example .claude/worktrees/) to .gitignore.

How coding agents use worktrees natively

Tool	How to start	Where worktrees live	Copying .env and setup
Claude Code	claude --worktree <name> or -w	.claude/worktrees/<name>/	.worktreeinclude
Codex app	Local or Worktree, under the composer	$CODEX_HOME/worktrees	.worktreeinclude
Cursor	Worktree per task in the editor	Managed by Cursor	.cursor/worktrees.json
Gemini CLI	gemini --worktree <name> (experimental)	.gemini/worktrees/<name>	Not listed

Claude Code (docs) puts each worktree on a branch named worktree-<name>, branched from the remote default branch unless you set worktree.baseRef to "head". A .worktreeinclude file in gitignore syntax lists ignored files, like .env, to copy into new worktrees. Clean worktrees are removed on exit and changed ones prompt you. Subagents can run with isolation: worktree.

Codex (docs) lets you pick Local or Worktree for each chat, and "Handoff" moves a chat between the two. It also reads .worktreeinclude and keeps the 15 most recent managed worktrees by default.

Cursor (docs) gives each task an isolated checkout. Setup goes in .cursor/worktrees.json, for example:

{
  "setup-worktree": ["npm ci", "cp $ROOT_WORKTREE_PATH/.env .env"]
}

It caps a machine at 25 worktrees by default, and /best-of-n runs the same task in one worktree per model.

Gemini CLI (docs) has worktrees behind an experimental flag, {"experimental": {"worktrees": true}}, and keeps them on exit.

OpenCode has no built-in worktree flag in its docs, but its SDK can create, list and remove worktrees.

Where worktrees stop helping

Worktrees solve file collisions on one machine. They don't tell you what the agent in the other worktree is doing, and they do nothing about your teammate's five worktrees on their laptop. Two people can still send two agents at the same bug.

How Coagy uses worktrees

Coagy gives every task its own git worktree and branch, for Claude Code, Codex, Gemini CLI or Cursor, so parallel agents never share files. The difference is that the worktrees show up in one shared workspace. Your team can see every running task across everyone's computers, watch an agent live, ask it what it changed, and pick up a session a teammate left. Sessions are private until the owner shares them.

Working alone? Coagy Local is a free desktop-style app that runs agents side by side, each task optionally in its own worktree, with no account. For more on the parallel workflow, read how to run multiple AI coding agents in parallel and AI agent orchestration for coding teams.

Questions

What is a git worktree?

A git worktree is an extra working directory linked to the same repository. Each worktree has its own checked-out branch, HEAD and index, while sharing the repository's history, refs and config.

Why do AI coding agents use git worktrees?

So several agents can work on the same repository at once. Each agent edits files in its own worktree on its own branch, so one agent never overwrites another's changes. You review and merge each branch separately.

Does a git worktree copy my .env file and node_modules?

No. A new worktree is a fresh checkout of tracked files only. Copy env files and install dependencies in each worktree. Claude Code and Codex can copy listed ignored files through a .worktreeinclude file, and Cursor runs setup commands from .cursor/worktrees.json.

Can two git worktrees use the same branch?

No. Git refuses to check out a branch that is already checked out in another worktree. Create a new branch for each worktree, or use --detach for a throwaway one.

How do I delete a git worktree?

Run git worktree remove with the worktree path. It refuses if there are uncommitted or untracked changes unless you add --force. If you already deleted the folder by hand, run git worktree prune.