Claude Code worktrees: run parallel sessions with claude --worktree

Based on the Claude Code worktree docs as of November 2026. Claude Code changes quickly; check the docs if a flag behaves differently.

Why run Claude Code in a worktree?

Two Claude Code sessions in the same directory edit the same files. One session’s refactor shows up in the other’s diff, tests fail for reasons neither caused, and both run git against the same index. A git worktree gives each session its own files and branch while sharing one repository, so commits from one are visible to the other without any copying.

Start a session in a worktree

claude --worktree feature-auth
# in a second terminal
claude --worktree fix-login

• The worktree lives at .claude/worktrees/<name>/ in your repository root.
• The branch is worktree-<name>. Leave out the name and Claude generates one, such as bright-running-fox.
• By default the worktree branches from your repository’s default branch on the remote (usually origin/main), not from whatever you have checked out.
• Add .claude/worktrees/ to .gitignore so the worktrees don’t show up as untracked files in your main checkout.

You can also ask Claude mid-session to “work in a worktree”, and it will create one and move the session there.

Start from a pull request or your current branch

claude --worktree "#1234"

This fetches PR #1234 and creates .claude/worktrees/pr-1234. Quote the argument so your shell doesn’t treat # as a comment. To branch from your current local HEAD instead of the remote default branch, set "worktree": { "baseRef": "head" } in Claude Code’s settings.

Copy .env and other ignored files

A new worktree contains only tracked files, so .env, .env.local and other ignored config are missing. Create .worktreeinclude in the repository root with .gitignore-style patterns:

.env
.env.local
config/secrets.json

Claude copies files that match a pattern and are gitignored. Dependencies are not copied: install them in each worktree, or ask Claude to do it as its first step.

What happens when you exit

• No changes: for an unnamed session, Claude removes the worktree and its branch automatically. Named sessions ask first.
• Changes or new commits: Claude asks whether to keep or remove the worktree. Keep it, and resume later with the claude --worktree <name> --resume command it prints.
• Non-interactive runs (claude -p --worktree …) have no exit prompt, so their worktrees stay behind, locked. Remove one with git worktree unlock <path> followed by git worktree remove <path>.

Choosing “remove” deletes the directory and branch along with any work in them. If you’re not sure whether a worktree’s commits were pushed or merged, check before you answer. Our worktree cleanup checklist covers how.

Give subagents their own worktrees

Subagents can run in temporary worktrees too. Ask Claude to “use worktrees for your agents”, or make it permanent for a custom subagent with isolation: worktree in its frontmatter:

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

A subagent’s worktree is removed automatically if it made no changes. Worktrees that still hold work stay on disk until a periodic sweep can remove them safely.

Gotchas

• Trust prompt first. In a directory where you’ve never run Claude, run plain claude once to accept the trust dialog, or --worktree exits with an error.
• Isolation is enforced. While a session is in a worktree, Claude Code blocks edits to files in the main checkout and git commands redirected into it.
• Permission approvals are shared. “Don’t ask again” in a worktree saves the rule to the main checkout’s settings, so it applies to every worktree of that repository.
• Branches pile up. Every kept session leaves a worktree-* branch. Over a week of parallel sessions you can end up with many, some merged, some not.

Seeing all your Claude Code worktrees at once

With several sessions running, the hard part is no longer creating worktrees but knowing what each one is doing. Orchard shows every worktree in every project on your Mac, including the ones under .claude/worktrees/. It marks which ones Claude Code is working in right now, flags a session that hasn’t changed a file for a while and may be waiting for you, and tells you which worktree-* branches are already in main and safe to clean up, with the evidence.

FAQ