The --worktree Flag and Session Isolation
The --worktree flag starts Claude Code in an isolated git worktree. The session gets its own branch and working directory — the main tree is completely untouched until you choose to merge.
Quick Reference
- →claude --worktree name — create a new worktree session
- →claude -w name — shorthand
- →claude -w — auto-generate a name
- →claude -w feature --tmux — launch in a new tmux session
- →Creates branch: worktree-{name} at .claude/worktrees/{name}/
- →Auto-cleanup: no commits = worktree removed on exit
- →With commits: branch and path returned for review
- →Shipped stable in Claude Code v2.1.49 (February 19, 2026)
What --worktree Does
Running claude --worktree creates a new isolated environment for the session before it starts. Claude Code creates a git branch, creates a working directory at .claude/worktrees/{name}/, and starts the session in that directory. Everything the session does — reads, edits, commits — happens in the worktree, not in your main working directory.
Branch creation
Claude Code creates a new branch named worktree-{name}, branching from the current HEAD of your default remote branch (origin/HEAD).
Directory creation
A new working directory is created at .claude/worktrees/{name}/ and the branch is checked out there.
Session starts
The Claude Code session starts in the new directory. All file operations are scoped to this worktree — your main working directory is untouched.
While the worktree session is running, your main working directory is exactly as you left it. You can run other commands, other sessions, or other worktrees from the main directory without any interference.