---
name: worktrees-reference
description: CC git worktree integration — isolated repo copies per agent for parallel or destructive work.
layer: reference
cc_feature: worktrees
source: https://docs.claude.com/en/docs/claude-code/worktrees
concept: git-worktree-isolation
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: approved
---

# Worktrees — Reference

Git worktrees let a repo check out multiple branches simultaneously in
separate directories. Claude Code integrates with worktrees to give
agents isolated filesystem scopes — one agent's edits cannot clash
with another's.

## How it surfaces in CC

- **`isolation: "worktree"` on a subagent call** — the harness creates
  a temporary worktree for the subagent. The subagent runs with its
  cwd set to the worktree. Changes stay there until merged or
  discarded.
- **`/worktree` skill / command** — interactive tooling for creating,
  listing, and merging worktrees during a session.
- **Auto-cleanup** — worktrees created by subagents are removed if the
  subagent made no changes. Otherwise the path is returned in the
  result for the caller to review.

## Branch semantics

- Each worktree checks out a named branch. Two worktrees cannot check
  out the same branch (git's rule).
- Creating a worktree creates a branch if one does not exist.
- Deleting a worktree does not delete the branch; use `git branch -d`
  separately if desired.

## Use cases

- **Parallel exploration** — three subagents trying three approaches,
  each in its own worktree. The parent compares diffs.
- **Destructive experiments** — upgrade a dependency, run the full
  test suite, measure breakage. Discard the worktree if results are
  bad.
- **Long-running session without blocking main** — execute a refactor
  in a worktree while continuing other work in the main checkout.

## Pitfalls

- **Shared state leaks** — node_modules, .env, build artifacts are
  per-worktree but may be symlinked in ways that defeat isolation.
  Verify.
- **Disk use** — each worktree is a full checkout of the tree. For
  large repos, disk pressure adds up.
- **Branch proliferation** — agents that create worktrees without
  cleanup leave orphan branches. Prune periodically.
- **Not a sandbox** — a worktree isolates files, not network or
  processes. A subagent in a worktree can still call the outside
  world.

## Composition

- Worktrees + background agents: a background agent in a worktree can
  work on a long task while the user continues in the main checkout.
- Worktrees + subagents + hooks: hooks fire inside the worktree cwd,
  so path-based hooks naturally scope to the isolated work.