--worktree — Run Claude Code Sessions in Parallel

What is it

Claude Code has a --worktree flag that creates an isolated copy of your repo, puts it on a fresh branch, and starts a Claude session inside it. Each worktree is its own directory with its own branch, so changes in one don't touch any other. When you're done, Claude cleans up automatically.

Under the hood it uses git worktrees, but Claude Code adds the good stuff on top: automatic creation, automatic cleanup, .env file copying, and subagent isolation. Think of it like having multiple desks, each with a different task spread out. You can walk between them without cleaning up first.

Claude Code worktree docs

What problems it solves

You're working on a feature with Claude and a bug report comes in. You'd normally have to stash your changes, switch branches, fix the bug, switch back, and pop the stash. Half the time something goes wrong with the stash, or you forget which branch you were on. With worktrees, you just open a new terminal, start Claude in a fresh worktree, fix the bug there, and your feature work stays untouched.

Or you want Claude to work on two independent tasks in parallel. Maybe it's refactoring the auth module and also adding a new API endpoint. Without worktrees, these would conflict because they're editing files in the same directory. With worktrees, each task runs in its own copy of the repo and there's zero chance of collision.

How to use it

Start Claude in a new worktree with the -w flag:

# Start Claude in a worktree called "feature-auth"
claude --worktree feature-auth

# Start another session in a separate worktree
claude --worktree bugfix-123

Each worktree gets created at .claude/worktrees/<name>/ with a new branch called worktree-<name>. The branch starts from wherever origin/HEAD points (usually main).

If you don't care about the name, let Claude pick one:

# Auto-generates a name like "bright-running-fox"
claude --worktree

You can also ask Claude during a session to "work in a worktree" and it'll set one up for you.

Cleanup

When you exit a worktree session, Claude handles it automatically:

• No changes made — the worktree and branch are removed. Clean slate.
• Changes or commits exist — Claude asks if you want to keep it or toss it.

Gitignored files like .env

Worktrees are fresh checkouts, so they won't have your .env, .env.local, or other untracked files. Create a .worktreeinclude file in your project root to fix this:

.env
.env.local
config/secrets.json

These files get copied into every new worktree automatically.

Pro tips

Subagents can use worktrees too. If you ask Claude to "use worktrees for your agents," each subagent gets its own isolated copy to work in. For custom subagents, add isolation: worktree to the agent's frontmatter. The worktree gets cleaned up automatically when the subagent finishes.

If origin/HEAD points to the wrong branch (it gets stale when the remote default changes), re-sync it with git remote set-head origin -a. This only updates your local reference, nothing on the remote.

References

• Claude Code worktree workflows
• Git worktree docs
• Related tips: /compact — Free Up Context · /permissions — Control Tools