Git worktree with Claude Code: run AI agents in parallel

What a git worktree is, the commands you need, and how Claude Code's --worktree flag runs several agents on one repository without them overwriting each other.

7 minutes Matěj Žalmánek 2026-10-26

One AI agent on one branch is a bottleneck. While it builds a feature, you cannot let another one fix a bug in the same folder — they would overwrite each other's files. Git worktrees solve this: several working copies of one repository, each on its own branch, side by side. Here is what a git worktree is, the commands you need, and how Claude Code uses worktrees to run agents in parallel.

1. What is a git worktree

A git worktree is an extra working directory attached to the same repository. It has its own files and its own checked-out branch, but shares the history, objects and remotes with your main checkout. No second clone, no second download, and a commit made in one worktree is immediately visible from the others.

Compared with the alternatives:

Switching branches changes files under your feet — impossible while something is running in them.
A second clone works, but doubles the disk usage and the branches live in two separate repositories that you have to sync.
A worktree gives each task its own folder, while the repository stays one.

2. Git worktree commands you actually need

# new worktree on a new branch, next to the project
git worktree add ../project-feature-a -b feature-a

# worktree for a branch that already exists
git worktree add ../project-bugfix fix-issue-456

# what worktrees exist
git worktree list

# remove one when you are done (the branch stays)
git worktree remove ../project-feature-a

# clean up records of worktrees deleted by hand
git worktree prune

One rule to remember: a branch can be checked out in only one worktree at a time. Git refuses a second one, which is exactly what keeps parallel work from colliding.

3. Claude Code worktrees: one flag

Claude Code has worktrees built in. Start a session with --worktree (or -w) and a name:

claude --worktree feature-auth

Claude Code creates the worktree in .claude/worktrees/feature-auth/ on a new branch worktree-feature-auth and starts the session inside it. Run the same command with another name in a second terminal and you have two isolated agents. Add .claude/worktrees/ to your .gitignore so the worktrees do not show up as untracked files in your main checkout.

Useful details:

Base branch. New worktrees start from the repository's default branch on the remote. To start from your current work instead, set "worktree": { "baseRef": "head" } in your settings.
From a pull request. claude --worktree "#1234" fetches the PR and creates the worktree on it — handy for reviews.
Mid-session. Just ask Claude to “work in a worktree”.
Cleanup. On exit, a clean worktree is removed automatically; one with changes or commits makes Claude Code ask whether to keep it.

4. .env files and setup in a new worktree

A worktree is a fresh checkout: files ignored by git — .env, node_modules, build output — are not there. Two things help:

.worktreeinclude in the project root lists ignored files Claude Code should copy into every new worktree. It uses .gitignore syntax:
```
.env
.env.local
config/secrets.json
```
Install dependencies in the worktree — ask the agent to do it as its first step, or put it in the project's instructions.

5. Parallel subagents, each in its own worktree

Worktrees also work one level down. Ask Claude to “use worktrees for your agents”, or make it permanent for a custom subagent:

.claude/agents/refactorer.md

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

Each subagent then edits its own copy of the files, and a worktree without changes is removed automatically when the subagent finishes.

6. A parallel workflow that does not end in chaos

Split the work so the tasks do not touch the same files. Worktrees prevent overwriting, not merge conflicts.
One worktree, one task, one branch. Name them after the task, not “agent-2”.
Review each branch on its own — run the tests in that worktree before you merge.
Merge often. The longer branches live apart, the bigger the conflicts.
Remember the limit is you. Three agents produce three diffs to review. Run as many as you can actually check.

7. Common git worktree problems

“is already checked out at …” — that branch is open in another worktree. Use a new branch or remove the old worktree.
A worktree folder deleted by hand still shows in git worktree list — run git worktree prune.
Missing files in the new worktree — they are ignored by git; add them to .worktreeinclude.
Git LFS pointer files instead of real files in a worktree Claude Code created — run git lfs pull inside it.
“locked” when removing — git worktree unlock first.

Running several agents also means several of them may want your attention at once. With coden you can start a Server in each worktree (coden-server start --dir ../project-feature-a) and the approvals and “I'm done” notifications from all of them come to your phone — parallel agents do not have to keep you at your desk.

Do you see it differently? Write to support@coden-app.com.