Jonathon's AI Wiki

Worktrees — Isolated Git Workspaces for Parallel Claude Sessions

5 min read

Source: wiki synthesis: whats-new-2026-w21, nate-herk-every-level-of-claude, whats-new-in-claude-code-talk

Worktrees are Claude Code’s productized wrapper around git’s native worktree feature — each Claude Code session can run inside an isolated git workspace on its own branch, so two/three/four Claudes work in parallel without ever overwriting each other’s files. Released into stable Claude Code during the Week 21 2026 cycle (with refinements continuing through v2.1.143), worktrees are the primitive that turns parallelism from a manual juggling act into a first-class operator pattern. Dixon Dick (Anthropic Claude Code team) opens his Code with Claude 2026 talk’s autonomy section with “worktrees are my favorite feature” ^[inferred from source emphasis] — they are the unlock between Level 4 babysitting and genuinely scaled multi-agent work.

Key Takeaways

  • Worktrees enable true parallel Claude sessions — implement a feature in one, fix a bug in another, write tests in a third, all simultaneously, each on its own branch with its own file copy. No file conflicts because no two sessions ever see the same working tree.
  • The sweet spot is 3-4 parallel ^[inferred from Nate Herk source]. Boris Cherny (Anthropic, built Claude Code) runs five parallel sessions minimum daily — but most operators report diminishing returns past four because human attention budget caps the merge-and-review step downstream.
  • CLI invocation: claude --worktree feature-name (or claude -w) starts a new session with a fresh worktree attached on its own branch.
  • Agent tool invocation: subagents spawned via the Agent tool accept an isolation: "worktree" parameter that isolates the child in its own worktree without manual setup.
  • Automatic cleanup if no changes were made. When Claude exits a worktree and the branch has no diff against its base, the harness removes the worktree directory and the branch ^[inferred from Anthropic talk]. No janitorial sweep required.
  • Worktree path + branch are returned in the result so the caller (you, or a parent Claude session) can cd into it, inspect the diff, or merge it back into main.
  • enter_worktree / exit_worktree tools let Claude self-decide to isolate a feature without an explicit CLI flag. Putting “create a worktree for any new feature” in CLAUDE.md is the canonical configuration ^[inferred from W21 + Dixon talk].

How worktrees work in Claude Code

Git’s native git worktree command creates a second working directory pointing at the same repo, on a different branch. Claude Code wraps it with three operator-facing surfaces.

  • --worktree CLI flag. claude --worktree <name> creates a worktree at .worktrees/<name>/ (or the configured base directory), checks out a new branch named <name>, and starts the session there. The CLI handles git plumbing — no manual git worktree add.
  • Agent tool isolation: "worktree" parameter. When dispatching a subagent (via the Agent tool), passing isolation: "worktree" runs the subagent in its own worktree on its own branch. The subagent’s edits never touch the parent session’s working tree. The result returned to the parent includes the worktree path and branch name so the parent can inspect or merge.
  • Automatic cleanup if the agent makes no changes. If a subagent exits with a clean git diff (no commits, no staged edits), Claude Code removes the worktree and deletes the throwaway branch. This is what makes worktrees viable for low-stakes exploration — failed spikes leave no trace.
  • Files-shared-across-worktrees setting. New worktrees don’t have to re-install node_modules, .venv, or other expensive dependencies — declare them shared in Claude Code settings and they’re inherited.
  • Settings related to background sessions. worktree.bgIsolation: "none" (added in v2.1.143) lets background sessions edit the working copy directly instead of forcing a worktree — for repos where worktrees are impractical (monorepos, symlink-heavy configs, untracked-file-heavy projects).

Common patterns

  • Parallel feature work. The canonical pattern. Three terminal tabs, three claude --worktree <name> invocations, three independent features (or three independent bugs) progressing in parallel. Dixon’s Code with Claude 2026 demo: color tweak / border-radius slider / star shape — three Excalidraw feature branches running side by side, each rendered on its own localhost port.
  • Isolated experimentation. Spike on a refactor or library swap inside a worktree with isolation: "worktree". If it works, merge. If it doesn’t, the auto-cleanup means the failed experiment leaves zero state behind.
  • Side-by-side comparison. Dispatch the same task to two subagents, each in its own worktree with different prompts (or different models). Compare the resulting diffs to decide which approach to keep. Cheap A/B over branches.
  • Fork-session-with-files. Combine /branch (formerly /fork, which forks the conversation) with --worktree (which forks the files). The combo gives parallel reasoning and parallel files — useful when exploring two divergent design decisions that both need code experiments to validate.

Try It

  1. Run claude --worktree spike-1 in your current repo. Implement something small, exit, run git worktree list to confirm the second tree exists. Then claude --worktree spike-2 in another terminal tab and watch the two sessions stay isolated.
  2. Add to your CLAUDE.md: “For any new feature, create a worktree to isolate the work.” Next session, ask Claude to implement two unrelated features in one prompt — observe whether Claude self-splits via enter_worktree.
  3. Dispatch a subagent with isolation: "worktree" for a refactor spike. If the spike fails, confirm the worktree auto-cleans. If it succeeds, merge the returned branch.
  • whats-new-2026-w21 — worktree.bgIsolation: "none" setting, pre-existing-worktree recognition fix, and the rm -rf cleanup-safety patch
  • whats-new-in-claude-code-talk — Dixon’s three-worktree Excalidraw demo and the enter_worktree / exit_worktree tool pair
  • nate-herk-every-level-of-claude — worktrees as the Level 4 unlock; sweet spot 3-4 parallel
  • subagents — Agent tool isolation: "worktree" parameter
  • plan-mode — the planning surface that often precedes a worktree-isolated implementation
  • claudemd-file-primer — where to declare “create a worktree for new features” so Claude self-isolates
  • cli-reference — --worktree / -w flag reference and shared-files settings

Graph View

Backlinks