Skip to main content

Claude Worktrees

Run parallel Claude Code sessions with Git worktrees

When working on multiple tasks at once, you need each Claude session to have its own copy of the codebase so changes don't collide. Git worktrees solve this by creating separate working directories that each have their own files and branch, while sharing the same repository history and remote connections. This means you can have Claude working on a feature in one worktree while fixing a bug in another, without either session interfering with the other.

Use the --worktree (-w) flag to create an isolated worktree and start Claude in it. The value you pass becomes the worktree directory name and branch name:

# Start Claude in a worktree named "feature-auth"
# Creates .claude/worktrees/feature-auth/ with a new branch
claude --worktree feature-auth

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

If you omit the name, Claude generates a random one automatically:

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

Worktrees are created at <repo>/.claude/worktrees/<name> and branch from the default remote branch. The worktree branch is named worktree-<name>.

You can also ask Claude to "work in a worktree" or "start a worktree" during a session, and it will create one automatically.

Subagent Worktrees​

Subagents can also use worktree isolation to work in parallel without conflicts. Ask Claude to "use worktrees for your agents" or configure it in a custom subagent by adding isolation: worktree to the agent's frontmatter. Each subagent gets its own worktree that is automatically cleaned up when the subagent finishes without changes.

Worktree Cleanup​

When you exit a worktree session, Claude handles cleanup based on whether you made changes:

  • No changes: the worktree and its branch are removed automatically
  • Changes or commits exist: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding all uncommitted changes and commits

To clean up worktrees outside of a Claude session, use manual worktree management.

Add .claude/worktrees/ to your .gitignore to prevent worktree contents from appearing as untracked files in your main repository.

Manual Management​

For more control over worktree location and branch configuration, create worktrees with Git directly. This is useful when you need to check out a specific existing branch or place the worktree outside the repository.

# Create a worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Create a worktree with an existing branch
git worktree add ../project-bugfix bugfix-123

# Start Claude in the worktree
cd ../project-feature-a && claude

# Clean up when done
git worktree list
git worktree remove ../project-feature-a

Learn more in the official Git worktree documentation.

Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include running dependency installation (npm install, yarn), setting up virtual environments, or following your project's standard setup process.

Non-Git VCS​

Worktree isolation works with git by default. For other version control systems like SVN, Perforce, or Mercurial, configure WorktreeCreate and WorktreeRemove hooks to provide custom worktree creation and cleanup logic. When configured, these hooks replace the default git behavior when you use --worktree.

For automated coordination of parallel sessions with shared tasks and messaging, see agent teams.