Parallel workspaces with worktrees

A Git worktree is another working directory sharing repository history and remotes. Claude Code uses it to isolate parallel sessions so feature and bug-fix edits do not collide in one checkout.

#When to use one

Monorepos can reduce checkout size with sparsePaths and symlinkDirectories; see Large codebases. Desktop parallel sessions can create worktrees automatically; this guide focuses on CLI.

#Start a worktree session

claude --worktree feature-auth

Start another isolated task:

claude --worktree bugfix-123

Or generate a name:

claude --worktree

You can also ask Claude to work in a worktree. EnterWorktree creates and enters it; switching to another managed worktree leaves the original on disk.

Ignore generated directories:

.claude/worktrees/

#Base branch

By default, new worktrees start from origin/HEAD, falling back to local HEAD if no remote is available or fetch fails.

To include the current branch's unpushed commits:

{
  "worktree": {
    "baseRef": "head"
  }
}

For a GitHub PR, use a #number or full PR URL:

claude --worktree "#1234"

Claude fetches pull/<number>/head from origin and creates .claude/worktrees/pr-<number>.

#Copy local configuration

A new checkout does not automatically include untracked .env files or local secrets. A root .worktreeinclude uses gitignore-style patterns to copy selected ignored files:

.env
.env.local
config/secrets.json

#Subagent isolation

---
name: fixer
description: Fix an independent issue in an isolated worktree.
tools: Read, Grep, Glob, Edit, Bash
isolation: worktree
---

Keep the change focused. Report changed files and validation results when finished.

You can request worktrees for agents directly. Their base strategy is the same: remote default unless baseRef is head. Unchanged temporary worktrees are removed; changed ones retain information for review.

#Cleanup

Periodic cleanup of subagent/background worktrees requires:

• Older than cleanupPeriodDays.
• No uncommitted changes.
• No untracked files.
• No unpushed commits.

Explicit --worktree workspaces are not removed by that background sweep. Active agent worktrees are locked against concurrent cleanup and unlocked after completion.

#Manual management

For explicit location/branch control:

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix bugfix-123

Start Claude inside it:

cd ../project-feature-a
claude

Each directory needs the project's applicable dependencies, virtual environments, generated files, and initialization steps.

#Other version-control systems

For SVN, Perforce, Mercurial, or custom isolation, implement WorktreeCreate/WorktreeRemove hooks:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

The hook reads the requested name from stdin, creates a directory, and prints its path. It replaces Git creation and must handle local configuration copying itself.

#Common mistakes

#Official references

• Worktrees
• Subagents
• Settings
• Hooks
• Git worktree