claude --worktree: Launch Claude Code in an Isolated Git Worktree

The --worktree flag tells Claude Code to create a new git worktree, check out a fresh branch, and start a session inside it. Every file change stays isolated from your main checkout, making it safe to run multiple Claude sessions in parallel.

Syntax

Basic syntax

claude --worktree [name]

Argument	Required	Description
`name`	No	Branch and worktree name. If omitted, Claude generates one automatically.

What Happens When You Run claude --worktree

Running claude --worktree is roughly equivalent to running these git commands manually, though the exact behavior may vary between Claude Code versions:

Approximate behind-the-scenes flow

# Roughly what happens under the hood:

# 1. Create a new worktree with a new branch
git worktree add ../your-project-feature-name feature-name

# 2. Change into the worktree directory
cd ../your-project-feature-name

# 3. Start a Claude Code session scoped to this directory
claude

Typically, the worktree directory is created as a sibling of your current project directory. It shares the same .git object store, so branches, tags, and history are all available without duplicating data. For more on how git worktree add works, see our tutorial.

Examples

Basic: Auto-Generated Branch Name

When you omit the name, Claude Code generates a branch name automatically:

Auto-generated name

# Let Claude pick a branch name
claude --worktree

# Claude creates something like:
# Worktree: ../your-project-claude-fix-auth-bug
# Branch:   claude-fix-auth-bug

Named: Specify Your Own Branch

Pass a name to control the branch and directory:

Named worktrees

# Feature work
claude --worktree feat/user-dashboard

# Bug fix
claude --worktree fix/api-timeout

# Refactor
claude --worktree refactor/db-layer

Parallel Sessions with tmux

The most common use of --worktree is running multiple Claude sessions simultaneously. Each session gets its own worktree, so they never conflict:

Three parallel Claude sessions

# Terminal 1
claude --worktree feat/auth

# Terminal 2
claude --worktree feat/dashboard

# Terminal 3
claude --worktree fix/perf-regression

For a complete tmux setup, see our Claude Code parallel development guide.

Headless Mode with --worktree

Combine --worktree with -p (print/headless mode) to run non-interactive tasks in isolated worktrees:

Headless worktree session

# Run a one-shot task in an isolated worktree
claude --worktree fix/typos -p "Fix all typos in the docs folder"

# The worktree is created, Claude works, and results are printed
# If changes were made, Claude prompts you to keep or discard

Worktree Cleanup

Claude Code may clean up worktrees automatically when a session ends without changes. If a session produces commits, the worktree is typically kept so you can review and merge the results. The exact behavior may vary. You can always manage worktrees manually:

Manual cleanup

# See all worktrees (including ones from Claude sessions)
git worktree list

# Remove a specific worktree
git worktree remove ../your-project-feat-auth

# Clean up stale references
git worktree prune

For detailed cleanup instructions, see git worktree remove and git worktree prune.

When to Use --worktree vs a Regular Session

Scenario	Use --worktree?	Why
Running 2+ Claude sessions at once	Yes	Prevents file conflicts between sessions
Experimental changes you might discard	Yes	Easy to throw away without affecting main checkout
Single-task work on the current branch	No	Regular session is simpler, no overhead
Quick one-off question or code review	No	No file changes expected

--worktree vs Subagent Worktrees

Claude Code has two worktree mechanisms. The --worktree flag creates a top-level session in a new worktree. Inside a session, Claude can also spawn subagents with isolation: "worktree", which creates temporary worktrees for parallel subtasks.

Feature	--worktree flag	Subagent worktree
Scope	Entire session	Single subtask
Who creates it	You (CLI flag)	Claude (during a session)
Lifecycle	Lasts until session ends	Auto-cleaned when subtask completes
Use case	Parallel top-level sessions	Parallel work within one session

Learn more about subagent isolation in our parallel AI agents guide.

Common Issues

"fatal: branch is already checked out"

Git does not allow two worktrees to check out the same branch. If you see this error, either use a different branch name or remove the existing worktree first. See troubleshooting: already checked out.

Missing node_modules or .env Files

Worktrees do not share untracked files. You need to run npm install and copy .env files into each new worktree. See our node_modules guide for strategies like symlinking.

Not Inside a Git Repository

The --worktree flag requires an existing git repository. Initialize one with git init first. See troubleshooting: not a git repository.

Frequently Asked Questions

Does claude --worktree work with any git repository?

Yes. It works with any standard git repository, including bare repositories, repositories with submodules, and monorepos. The only requirement is that you run it from inside a git working tree or a bare repo.

How many worktree sessions can I run at once?

There is no hard limit from git. Practically, two to four parallel sessions is the sweet spot. Each session consumes API credits and system resources, so more sessions means more cost and more work to review.

Can I use --worktree with Claude Code in VS Code or an IDE?

The --worktree flag is a CLI feature. In VS Code, you can achieve the same result by manually creating a worktree with git worktree add and opening the new directory in a separate window. See our VS Code worktree guide.

What is the difference between claude --worktree and git worktree add?

git worktree add only creates the worktree. claude --worktree creates the worktree and starts a Claude Code session inside it, handling the full lifecycle including automatic cleanup.

Summary

The claude --worktree flag is the fastest way to start an isolated Claude Code session. It wraps git worktree add, branch creation, and session setup into a single command. Use it whenever you need parallel Claude sessions or want to keep experimental work separate from your main checkout.