Worktrees: keep parallel sessions out of each other's way

A git worktree is another working directory of the same repository: separate files, separate branch, shared history and remotes. Give each Claude Code session its own worktree and one session's edits can never touch another session's files.

One-line answer

Steps

1. Confirm the problem really is sessions stepping on each other.Symptoms: two sessions open in the same directory, session A's git status suddenly shows session B's changes, files change mid-test-run.OfficialThat's exactly what worktrees are positioned for: "running each Claude Code session in its own worktree means edits in one session never touch files in another". Prerequisite: it must be a git repository.
2. Start the first isolated session.Inside the repo, run claude --worktree feature-auth (short form -w).OfficialBy default this creates the worktree at .claude/worktrees/feature-auth/ under the repo root, on a new branch named worktree-feature-auth, cut from the repo's default branch (usually main). Omit the name and one is generated automatically. Before first use, you need to have run claude once in that directory and accepted workspace trust.
3. Open a second one under a different name.In another terminal, run claude --worktree fix-login-bug — from then on, the two sessions each edit their own copy.OfficialThe docs recommend adding .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in the main checkout.
4. Initialize the environment.A worktree is a fresh checkout: dependencies need reinstalling, and gitignored files like .env aren't there.OfficialAdd a .worktreeinclude file at the project root (.gitignore syntax) listing .env, .env.local, and so on; every new worktree then gets them automatically. Only files that both match a pattern and are themselves gitignored get copied.
5. Collect the changes.OfficialA worktree shares the .git directory and remotes with the main checkout, so git commit and push work as usual inside it.Our takeSo merging needs no special ceremony: push and open a PR, or go back to the main checkout and git merge worktree-feature-auth — just treat it as an ordinary branch.
6. Clean up.OfficialWhen you exit an interactive session, Claude checks the worktree: clean, unnamed ones are removed automatically; if one still holds changes or new commits, you're asked whether to keep or remove it. Worktrees created by non-interactive claude -p runs get no exit prompt — remove them manually with git worktree remove <path> (add --force if there are uncommitted changes), and git worktree list shows what currently exists.
7. Two advanced switches.Official① Mid-session, just say "work in a worktree" and Claude creates one on the spot with the EnterWorktree tool; ② subagents can each take their own worktree too: add isolation: worktree to a custom subagent's frontmatter (subagent basics in D10 · Subagents). If you want worktrees cut from your current unpushed work rather than the default branch, set "worktree": {"baseRef": "head"} in settings.

Copy-paste prompt

Do this task in a new worktree: <task description>.
Requirements:
1. Isolate the work in a worktree — don't touch any file in my main
   checkout;
2. After entering the worktree, initialize the environment first: install
   dependencies, check whether local config files like .env exist, and if
   any are missing, list them and ask me before proceeding;
3. When the changes are done, run <test command>; once it passes, commit
   to the worktree branch, then tell me the branch name and a summary of
   the changes. I'll decide whether to merge or open a PR — don't merge
   it yourself.

Sources & last verified

• OfficialRun parallel sessions with worktrees, fetched 2026-08-05.
• Last verified: 2026-08-05 · volatility:high (cleanup, baseRef, and EnterWorktree approval behavior have changed frequently across recent versions).