Claude Code Worktree Guide

claude-worktree-guide.md

Git Worktrees with Claude Code

Worktrees let you work on multiple branches at the same time, in separate folders. Claude Code has built-in support for them.

Start Claude in a new worktree

claude --worktree feature-auth   # named
claude -w                         # auto-named

This creates .claude/worktrees/<name> on a new branch worktree-<name>, branched from origin/HEAD.

If your origin/HEAD is out of date:

git remote set-head origin -a

Ask Claude to make one mid-session

Just say:

"Create a worktree for this work."

Claude uses its built-in EnterWorktree tool. When you're done:

"Exit the worktree."

If you made no changes, it's auto-deleted. If you did, Claude asks whether to keep it.

Copy env files automatically

Claude won't copy gitignored files by default. Add a .worktreeinclude at the repo root (uses .gitignore syntax):

.env
.env.local
config/secrets.json

Now those files get copied into every new worktree.

Run subagents in parallel

When delegating to subagents, pass isolation: "worktree" so each one gets its own worktree. Useful for fan-out tasks where agents would otherwise step on each other.

Manual worktrees still work

If you'd rather drive it yourself:

git worktree add ../myproj-feature -b feature
cd ../myproj-feature && claude

Clean up later:

git worktree list
git worktree remove ../myproj-feature

When to use which

• --worktree flag — starting fresh work on a new branch
• Ask Claude mid-session — you realized partway through you want isolation
• Subagent isolation — running parallel tasks that touch the same files
• Manual — you want full control over location and naming

Docs