Git worktrees with Claude Code: parallel features, no conflicts

Run Claude Code in a git worktree with one flag: separate branches, no stepping on each other's files. Setup, cleanup, base branches and the gotchas.

· 5 min read

A git worktree is a second checkout of the same repository, in its own folder and on its own branch. Start Claude Code in one with claude --worktree <name> and it can build a feature while another session fixes a bug somewhere else, without either one touching the other's files. This page covers the commands, what happens when you exit, and the things that surprise people the first time.

#Why do parallel Claude Code sessions collide in one checkout?

Two sessions in the same folder share one working tree. If both edit src/api.ts, the second write lands on top of the first, and a git commit in one session picks up the half-finished work of the other. Claude Code tracks only its own edits, so neither session knows what the other did.

A worktree fixes that at the file level: each session has its own copy of the files and its own branch, while the repository history and the remote stay shared. It is the same idea as cloning the repo twice, without the second .git folder and the second fetch.

#How do you start Claude Code in a worktree?

claude --worktree feature-auth

-w is the short form. Claude Code creates the worktree under .claude/worktrees/feature-auth/ at the repository root, on a new branch named 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 sessions. Leave the name out and Claude generates one.

A few rules from the docs:

  • The repository needs at least one commit.
  • Interactive runs need the folder to be trusted, so run plain claude there once first.
  • Add .claude/worktrees/ to your .gitignore, or the worktrees show up as untracked files in your main checkout.

You can also ask for it mid-session ("work in a worktree"); Claude uses its EnterWorktree tool and moves there.

#How do you set up the environment inside a worktree?

A worktree is a fresh checkout, so anything gitignored is missing: node_modules, .env, build output. Two ways to deal with it.

Ask Claude to install dependencies on the first prompt, or add a .worktreeinclude file at the project root. It uses .gitignore syntax, and files that match a pattern and are also gitignored get copied into every new worktree:

.env
.env.local
config/secrets.json

For big folders you do not want duplicated, the settings reference lists worktree.symlinkDirectories (symlink instead of copy) and worktree.sparsePaths (check out only the directories you need). Check that page for the exact shape before using them.

#Which branch does a worktree start from?

By default a new worktree branches from the repository's default branch on the remote, usually main, so it starts clean and does not carry your unpushed commits. If you want it to start from your current work, set worktree.baseRef in settings:

{
  "worktree": {
    "baseRef": "head"
  }
}

"fresh" is the default and "head" branches from your local HEAD. The setting cannot name a branch. To start from a specific existing branch, create the worktree yourself (below).

To review a pull request in isolation, pass its number with a #, quoted so the shell does not read it as a comment:

claude --worktree "#1234"

Claude Code fetches the PR's head from origin and checks it out at .claude/worktrees/pr-1234. A pull request URL works too.

#What happens to the worktree when you exit?

Claude checks whether removing it would lose work.

State when you exitWhat happens
Clean, session unnamedWorktree and branch are removed automatically
Clean, session namedClaude asks first, so you can keep it
Changed files or new commitsClaude asks whether to keep or remove it

Keeping preserves the folder and the branch. Claude prints the command to come back, in the form claude --worktree <name> --resume. Removing deletes the directory and its branch together with whatever was in them, so read the prompt. Runs with -p have no exit prompt and are never cleaned up automatically; remove those with git worktree remove.

The branch is a normal branch. Merge it, or push it and open a pull request, as in commit, push and open a PR with Claude Code.

#Can subagents and background sessions use worktrees?

Yes, and this is where worktrees pay off most. Add isolation: worktree to a custom subagent's frontmatter and every run gets a temporary worktree, removed when the subagent finishes without changes:

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

Background sessions started with claude --bg move into a worktree under .claude/worktrees/ before they edit anything, unless they are already in one or the folder is not a git repository. More on keeping track of those in running several Claude Code sessions at once.

#How do you manage worktrees by hand?

When you need a specific base branch or a worktree outside the repo, use git directly and start Claude inside it:

git worktree add ../shop-feature-a -b feature-a
cd ../shop-feature-a
claude

git worktree list shows them all, and git worktree remove ../shop-feature-a deletes one. Claude Code treats a worktree made this way like any other checkout; the shared-state notes below apply to both kinds.

#What do worktrees still share with the main checkout?

Isolation is about files, not everything:

  • The .git directory. Commits, branches and stashes live in one repository. A branch checked out in one worktree cannot be checked out in another.
  • Permission approvals. Choosing "Yes, and don't ask again" in a worktree session saves the rule to the main checkout's .claude/settings.local.json, so it applies everywhere in that repo and outlives the worktree.
  • Ports and databases. Two worktrees both running pnpm dev fight over port 3000, and both talk to the same local database. Give each its own port.
  • Untracked skills, agents and commands. If a worktree has no .claude/skills of its own, Claude Code reads the main checkout's.

Dependencies are the other cost: a worktree with its own node_modules is slow to create on a large project, which is where symlinking helps.

#In Relais

Relais has this built in as a checkbox. Under the new-session composer, "Own worktree and branch" gives the session a checkout of its own, on a branch named relais/<id> made from the repository's current branch; a Board task has a worktree chip for the same thing. The Changes tab shows the worktree, and the branch chip in the session header merges it back into the branch it came from, or deletes it, then archives the session. Without the checkbox, sessions share the branch each repository is on and Commit takes only the files the session changed. See features and the FAQ.

Claude Code,
better organized.

$14.99 a month, everything included. Mac and Linux, on your Claude Pro or Max plan. Cancel any time.