Claude Code with git worktrees: the practical setup

The one-flag version

# one isolated session
claude --worktree feature-auth

# short form, second terminal, second task, no collision
claude -w search-index

# no name: Claude generates one, such as bright-running-fox
claude -w

That creates a worktree at .claude/worktrees/feature-auth/ in the repository root, on a new branch named worktree-feature-auth, and starts the session inside it. Run it again in another terminal with a different name and you have two sessions that cannot touch each other's files.

What the flag actually creates

app/                              <- main checkout, your branch
  .git/
  .gitignore                      <- contains .claude/worktrees/
  .worktreeinclude                <- committed; lists .env and friends
  .claude/
    worktrees/
      feature-auth/               <- branch worktree-feature-auth
      search-index/               <- branch worktree-search-index
  src/

Which commit it branches from

By default a new worktree branches from the repository's default branch on the remote, not from wherever you happen to be standing. The setting is worktree.baseRef, and it takes two values.

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

Branching from a pull request

claude --worktree "#1234"

Claude Code fetches pull/1234/head from origin and puts the worktree at .claude/worktrees/pr-1234. A full GitHub pull request URL works too. This is the fastest route to "review this PR without touching what I am doing", which was the original human use for worktrees long before agents existed.

Reusing a name

Passing a name whose directory already exists opens that worktree rather than creating a new one. With the default "fresh" base it also resets to the default branch, but only when the worktree is clean, still on the branch Claude Code made for it, and either has no commits of its own or has had its pull request merged and its remote branch deleted. Anything else, including any reuse under "head", reopens at the old tip. The conservative direction is the correct one: a reset that discards commits should require every condition, not most of them.

Carrying the gitignored files across

A worktree is a fresh checkout, so .env, node_modules, and build output are not there. The config half is solved by a committed file; the dependency half is a normal install.

.env
.env.local
config/secrets.json

Only files that match a pattern and are gitignored are copied, so tracked files are never duplicated. It applies to every worktree Claude Code creates with git: --worktree sessions, subagent worktrees, and desktop parallel sessions alike.

For dependencies, run the install in the worktree, or ask Claude to. If you run several worktrees regularly, move the project to a package manager with a content-addressed store so the second install costs almost nothing.

cd .claude/worktrees/feature-auth
pnpm install --prefer-offline

The isolation is enforced, not requested

This is the part that makes the built-in flag different from a shell script that runs git worktree add and then claude. While a session is isolated in a worktree, Claude Code blocks tool calls that would reach the main checkout. The same checks cover every subagent that session spawns, interactive or background.

What a worktree still shares with the main checkout

The approvals row is the useful one in practice: an approval granted inside a throwaway worktree now applies everywhere and survives that worktree being removed, so you are not re-approving the same test command in every session.

Cleanup, and what happens if you skip it

When you exit an interactive worktree session, Claude Code inspects the worktree for anything removal would destroy: changed files, untracked files, and new commits.

git worktree list
git worktree remove .claude/worktrees/feature-auth

# if it has uncommitted work you have decided to discard
git worktree remove --force .claude/worktrees/feature-auth

# after deleting a directory by hand
git worktree prune -n -v && git worktree prune

Subagents get their own worktrees too

A single session can fan out. Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent with one line of frontmatter.

---
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 such subagent gets a temporary worktree, using the same base branch rule as --worktree. Claude Code removes it automatically when the subagent finishes with no changes; one that produced changes stays on disk.

When to create the worktree with git instead

The flag covers new work from a clean base. Two cases still want git directly: checking out a branch that already exists, and putting the worktree somewhere other than .claude/worktrees/.

# an existing branch, as a sibling of the repository
git worktree add ../app-bugfix fix-issue-456
cd ../app-bugfix && claude

# a new branch from a specific base
git worktree add -b feature/x ../app-x origin/release-2
cd ../app-x && claude

# read-only look at a tag, no branch involved
git worktree add --detach ../app-v1 v1.0.0

Getting the work back, and where this stops scaling

cd .claude/worktrees/feature-auth
git diff main...HEAD

git push -u origin worktree-feature-auth
gh pr create --fill

1. Attention. Past three or four sessions, terminal tabs stop being a usable index of what is running and which one is waiting on you.
2. Quota. Consumption scales with sessions, not with your patience. Four agents drain a plan roughly four times as fast, and the failure mode is discovering it mid-task.
3. Review. The ceiling that actually binds. Four agents produce more diff than one person reads carefully, and unreviewed agent output is a liability rather than an asset.

Questions people ask

Keep reading