Does Claude Code automatically detect that I'm in a worktree?

Yes, Claude Code has built-in support for Git worktrees. It recognizes worktrees as part of the same repository and stores sessions appropriately. The /resume command will show sessions from the same Git repository, including those from other worktrees.

Will my CLAUDE.md settings work in worktrees?

Yes, each worktree maintains its own context and can have its own CLAUDE.md file. If your worktree shares the same CLAUDE.md (via the linked Git repository), those instructions apply. You can also create worktree-specific CLAUDE.md files for different branch contexts.

What happens to my Claude Code session if I delete a worktree?

This is a known issue (GitHub Issue #15776). Sessions associated with deleted worktrees may become inaccessible or cause errors. Before deleting a worktree, use /rename to name important sessions, export any critical context, and consider running /clear to cleanly end the session.

Can I navigate between worktrees within a Claude Code session?

Currently, Claude Code cannot navigate to sibling worktrees from within a session (GitHub Issue #2841). Each worktree operates as a completely independent context. You need to start a new Claude Code session in the target worktree directory.

How to Use Git Worktrees with Claude Code

Git worktrees allow you to check out multiple branches simultaneously in separate directories, making parallel development workflows seamless. Claude Code has built-in support for worktrees, enabling you to run independent AI-assisted coding sessions across different branches of the same repository.

What Are Git Worktrees?

A Git worktree is an additional working directory linked to your repository. Unlike cloning a repository multiple times, worktrees share the same .git history and objects, making them lightweight and efficient.

Common use cases:

Working on a feature branch while keeping main clean for hotfixes
Reviewing pull requests without stashing current work
Running tests on one branch while developing on another
Comparing implementations across branches side-by-side

Prerequisites

Before setting up worktrees with Claude Code, ensure you have:

Git 2.5+ installed (worktrees introduced in Git 2.5)
Claude Code CLI installed and authenticated
A Git repository (local or cloned)
Sufficient disk space for additional working directories

Verify Git Version

git --version
# Should output: git version 2.5.0 or higher

Verify Claude Code Installation

claude --version
# Should output the installed Claude Code version

If you haven't installed Claude Code yet, see our Claude Code installation guide.

Setting Up Git Worktrees

Step 1: Create a Worktree

From your main repository directory, create a new worktree for a branch:

macOS and Linux

# Navigate to your repository
cd ~/projects/myapp

# Create a worktree for an existing branch
git worktree add ../myapp-feature-branch feature-branch

# Or create a worktree with a new branch
git worktree add -b new-feature ../myapp-new-feature main

Windows (PowerShell)

# Navigate to your repository
cd C:\Projects\myapp

# Create a worktree for an existing branch
git worktree add ..\myapp-feature-branch feature-branch

# Or create a worktree with a new branch
git worktree add -b new-feature ..\myapp-new-feature main

Windows (Command Prompt)

cd C:\Projects\myapp
git worktree add ..\myapp-feature-branch feature-branch

Step 2: Verify Worktree Creation

List all worktrees to confirm setup:

git worktree list

Expected output:

/Users/you/projects/myapp              abc1234 [main]
/Users/you/projects/myapp-feature-branch  def5678 [feature-branch]

Step 3: Initialize Claude Code in Each Worktree

Each worktree operates as an independent Claude Code context. Navigate to each worktree and initialize:

# In your main worktree
cd ~/projects/myapp
claude
> /init

# In your feature branch worktree
cd ~/projects/myapp-feature-branch
claude
> /init

Running /init in each worktree ensures Claude Code:

Analyzes the specific branch's codebase
Generates or updates CLAUDE.md for that context
Creates a session scoped to that worktree

Session Management Across Worktrees

Understanding Session Storage

Claude Code stores sessions per project directory in ~/.claude/projects/. Each worktree gets its own session storage path based on its directory location.

Session storage structure:

~/.claude/
  projects/
    Users-you-projects-myapp/
      sessions/
        session-abc123.json
    Users-you-projects-myapp-feature-branch/
      sessions/
        session-def456.json

Viewing Sessions with /resume

The /resume command shows sessions from the same Git repository, including sessions from other worktrees:

cd ~/projects/myapp-feature-branch
claude
> /resume

Output includes:

Sessions from current worktree (marked with current directory)
Sessions from sibling worktrees (shows their directory paths)
Session names (if renamed with /rename)
Last activity timestamps

Naming Sessions for Clarity

Use descriptive session names to identify work across worktrees:

claude
> /rename "Feature: User Authentication"

Naming conventions for worktree workflows:

[branch-name]: [task description]

Examples:

main: Hotfix payment validation
feature-auth: Implement OAuth flow
release-2.0: Final QA testing

Switching Between Worktree Sessions

To switch context between worktrees:

Open a new terminal for the target worktree
Navigate to the worktree directory
Start Claude Code and optionally resume a session

# Terminal 1 - Main branch
cd ~/projects/myapp
claude

# Terminal 2 - Feature branch (new terminal window)
cd ~/projects/myapp-feature-branch
claude
> /resume  # Optional: resume previous session

Important: You cannot navigate to sibling worktrees from within a Claude Code session (see Known Limitations).

Cleaning Up Sessions

Run /clear between distinct tasks to prevent context drift:

claude
> /clear

This is especially important when:

Switching between unrelated tasks in the same worktree
Preparing to delete a worktree
Starting fresh after a complex debugging session

CLAUDE.md Behavior in Worktrees

Shared vs. Worktree-Specific Configuration

CLAUDE.md files work in worktrees with some nuances:

Scenario 1: Same CLAUDE.md across branches

If your CLAUDE.md is committed to the repository and identical across branches, both worktrees use the same configuration. This is the typical setup.

myapp/
  CLAUDE.md          # Same file in main branch

myapp-feature-branch/
  CLAUDE.md          # Same file (from feature-branch)

Scenario 2: Branch-specific CLAUDE.md

If your branches have different CLAUDE.md files (different instructions per branch), each worktree uses its branch's version:

<!-- main branch CLAUDE.md -->
## Deployment
Run `npm run deploy:production` for releases.

<!-- feature-branch CLAUDE.md -->
## Deployment
Run `npm run deploy:staging` for feature testing.

Scenario 3: Untracked worktree-specific configuration

Create a CLAUDE.local.md in individual worktrees for worktree-specific settings:

cd ~/projects/myapp-feature-branch
echo "# Feature Branch Notes" > CLAUDE.local.md
echo "This branch focuses on the new authentication system." >> CLAUDE.local.md

Initializing CLAUDE.md Per Worktree

Run /init in each worktree to ensure Claude Code analyzes the specific branch's codebase:

cd ~/projects/myapp-feature-branch
claude
> /init

This is important when:

Branches have significantly different code structures
You added new dependencies on the feature branch
The branch has unique testing or build requirements

Known Limitations and Workarounds

Cannot Navigate to Sibling Worktrees (Issue #2841)

Limitation: Claude Code cannot navigate to sibling worktree directories from within a session.

Symptom: Attempting to read or edit files in a sibling worktree fails or produces unexpected results.

Workaround:

Start a new terminal session
Navigate to the target worktree
Launch a fresh Claude Code session there

# Don't try this within a session:
# > Read file at ../myapp-feature-branch/src/index.ts

# Instead, open new terminal:
cd ~/projects/myapp-feature-branch
claude

Session Loss on Worktree Deletion (Issue #15776)

Limitation: Deleting a worktree may cause associated sessions to become inaccessible.

Symptom: After removing a worktree with git worktree remove, attempting to resume sessions from that worktree may fail.

Workaround - Before deleting a worktree:

Export important context:

cd ~/projects/myapp-feature-branch
claude
> /rename "ARCHIVED: Feature work complete"
> # Document any important findings in CLAUDE.md or notes

Clean up the session:
```
> /clear
> /exit
```

Then safely remove the worktree:

cd ~/projects/myapp
git worktree remove ../myapp-feature-branch

Session Picker Shows All Repository Worktrees

Behavior: The /resume picker displays sessions from all worktrees of the same repository.

Note: This is intentional behavior, not a bug. It allows you to see all related work across branches.

Tip: Use consistent naming conventions to identify which worktree a session belongs to.

Best Practices

Use Descriptive Directory Names

Name worktree directories to clearly indicate their purpose:

# Good - Clear purpose
git worktree add ../myapp-hotfix-2024-01 hotfix/payment-bug
git worktree add ../myapp-feature-oauth feature/oauth-integration
git worktree add ../myapp-release-2.0 release/2.0

# Avoid - Unclear
git worktree add ../myapp-2 some-branch
git worktree add ../temp feature-x

Name Sessions with /rename

Always name your sessions, especially when working across multiple worktrees:

claude
> /rename "feature-oauth: Implementing Google OAuth provider"

Run /init in New Worktrees

When creating a worktree for a branch with significant differences:

cd ~/projects/myapp-feature-branch
claude
> /init

This ensures Claude Code understands the branch-specific:

Dependencies and packages
Directory structure changes
Configuration differences

Run /clear Between Tasks

Prevent context drift by clearing between unrelated tasks:

# After finishing authentication work
> /clear

# Starting new task in same worktree
> Let's work on the payment integration now

Maintain Parallel Terminals

For active parallel development:

Use terminal tabs or panes (iTerm2, Windows Terminal, tmux)
One terminal per worktree
Keep worktree paths in terminal titles

iTerm2 example (macOS):

# Set terminal title
echo -ne "\033]0;Main Branch - myapp\007"

Windows Terminal: Right-click tab > Rename Tab

Clean Up Unused Worktrees

Regularly prune worktrees you're no longer using:

# List all worktrees
git worktree list

# Remove a specific worktree (after cleaning up Claude sessions)
git worktree remove ../myapp-completed-feature

# Prune stale worktree references
git worktree prune

Complete Workflow Example

Here's a complete workflow demonstrating worktrees with Claude Code:

1. Set Up Worktrees

# Main repository
cd ~/projects/myapp

# Create worktree for new feature
git worktree add -b feature/user-dashboard ../myapp-dashboard main

# Create worktree for bug fix
git worktree add ../myapp-hotfix hotfix/login-issue

2. Initialize Claude Code

# Terminal 1 - Feature work
cd ~/projects/myapp-dashboard
claude
> /init
> /rename "Dashboard: Building user analytics view"

# Terminal 2 - Hotfix (new terminal)
cd ~/projects/myapp-hotfix
claude
> /init
> /rename "Hotfix: Login session timeout bug"

3. Work in Parallel

Work on each branch independently in separate terminals. Claude Code maintains separate context for each.

4. Clean Up When Done

# In the hotfix terminal
cd ~/projects/myapp-hotfix
claude
> /clear
> /exit

# Remove the worktree
cd ~/projects/myapp
git worktree remove ../myapp-hotfix

Troubleshooting

Sessions Not Showing in /resume

Verify you're in a worktree of the same repository
Check that sessions exist in ~/.claude/projects/
Ensure the worktree wasn't deleted (see session loss issue)

CLAUDE.md Changes Not Reflected

Run /init to reload configuration
Check if changes are on the correct branch
Verify file is named exactly CLAUDE.md (case-sensitive)

Worktree Creation Fails

# Error: 'branch-name' is already checked out

Solution: A branch can only be checked out in one worktree at a time. Either:

Use a different branch
Remove the existing worktree for that branch

git worktree list  # Find existing worktree
git worktree remove /path/to/existing-worktree

Next Steps

Need help optimizing your development workflow? Inventive HQ helps teams integrate AI coding tools effectively. Contact us for a consultation on Claude Code setup, Git workflows, and development best practices.