Claude Code worktrees let developers run isolated sessions against separate Git checkouts so concurrent tasks do not edit the same working tree. Current Claude Code supports claude --worktree name, worktree isolation for subagents, sparse worktree paths for large repositories, and hook events around worktree creation/removal. This makes worktrees a practical boundary for parallel implementation, risky experiments, and background agents.
Within Claude Engineering, worktrees solve a coordination problem rather than a context problem alone. Two Claude sessions can reason correctly and still collide if both modify the same checkout. A separate branch and working directory gives each session a version-control boundary that can be reviewed and merged explicitly.
Existing Git commands provide baseline worktree/branch context; this page focuses on Claude Code orchestration.
Use a worktree when concurrent edits could collide
If Claude is fixing a bug while another session builds a feature, both should not be writing into the same files, running formatters, or changing generated output in one checkout.
Starting a worktree session creates a separate checkout and branch context from an existing commit.
The repository must have at least one commit before Git can create a worktree, so initialize/commit baseline state first.
Worktrees are stronger than “please don’t touch my changes”
Prompt instructions can ask an agent to avoid files, but shell commands, generators, formatters, or dependency tools may still modify shared working state.
Filesystem and Git isolation make the boundary concrete. Each session gets its own checkout, index, and branch, while the Git object database remains shared.
This is especially important for autonomous/background tasks where the user is not watching every edit.
Name worktrees after tasks or outcomes
Use names that map to the work: auth-refresh-fix, billing-refactor, security-review-fixes.
Task-oriented names make git worktree list, branch review, and cleanup easier than generic labels such as claude1.
Keep names stable enough that issue/PR references can point to the same worktree during the session.
Sparse paths make large-repository worktrees practical
Current Claude Code large-codebase guidance supports worktree.sparsePaths so a worktree checks out only selected directories plus root-level files.
This reduces disk use and startup time for monorepos where a task touches one service or package.
Claude Code for Large Repositories explains how sparse paths combine with per-directory instructions and scoped work.
Subagents can request worktree isolation directly
A custom Claude Code subagent can set isolation: worktree in frontmatter. The subagent then runs Bash/PowerShell inside its temporary worktree instead of the main conversation’s checkout.
Current Claude Code also enforces working-directory protections intended to keep isolated agent commands from redirecting Git back into the main checkout.
This is a useful default for code-writing subagents that run concurrently or may make broad transformations.
Worktree hooks can customize creation and cleanup
Current Claude Code hook lifecycle includes WorktreeCreate and WorktreeRemove events.
Organizations can use them to create worktrees through custom version-control logic, seed environment files, enforce naming, or perform cleanup.
If a custom creation hook produces something Git does not recognize as a normal worktree, pair it with a removal hook so cleanup does not rely on Git’s fallback removal behavior.
Dependency directories should not be duplicated blindly
Large node_modules, build caches, virtual environments, or package stores can make several worktrees expensive.
Current large-repo guidance mentions symlinkDirectories alongside sparse worktrees for directories that can safely be shared.
Share only immutable/cache-like directories. Do not symlink build output or mutable state if concurrent sessions can corrupt one another through it.
Ports, databases, and local services still need isolation
A separate Git checkout does not prevent two sessions from starting the same dev server on port 3000 or running migrations against one local database.
Use environment variables, containers, per-worktree ports, temporary schemas, or disposable databases so runtime dependencies match the code isolation.
The worktree is only one layer of parallel-session safety.
Review and merge should happen like ordinary branch work
When the task completes, inspect the worktree’s diff, run tests, commit coherent changes, and merge/rebase through the team’s normal process.
Do not auto-merge simply because the isolated Claude session reported success.
The main benefit of a worktree is that the output arrives as an ordinary reviewable Git branch instead of hidden changes mixed with the developer’s own work.
Cleanup should happen after outcome is preserved
Before removing a worktree, ensure useful changes are committed, pushed, or otherwise preserved.
Claude Code can clean up normal Git worktrees automatically in supported flows, including isolated subagent worktrees with no changes.
Keep worktrees around only while they provide useful isolation; stale branches and checkouts create confusion about which task is still active.
Worktrees are successful when parallelism stops producing merge chaos
The mature workflow isolates code, runtime dependencies, and task ownership, uses sparse checkout for scale, validates each branch independently, and merges only reviewed outcomes.
Worktrees let Claude sessions operate in parallel without forcing every task to serialize behind one shared working directory.
Branch base matters. Current subagent worktree behavior can branch from the repository’s configured/default base rather than necessarily the parent’s current uncommitted state, depending on how the worktree is created. For interactive --worktree use, verify the commit/branch you intend before delegating work so the isolated session does not implement against an older or different baseline.
Uncommitted main-checkout changes are not automatically part of another Git worktree. If the task depends on those edits, commit/stash them or create the worktree from a commit containing the necessary state. This is a feature, not a bug: isolation should make hidden local dependencies visible rather than sharing them accidentally.
Cross-worktree generated artifacts need policy. Build systems may write caches or generated code into directories outside the checkout, package-manager global caches, Docker volumes, or local services. Decide which state is intentionally shared and which must remain worktree-specific so one agent cannot invalidate another agent’s test environment.
Rebases and merges should happen after the worktree task reaches a stable checkpoint. Constantly rebasing a live autonomous session underneath its files can create confusing diffs and stale assumptions. Let the agent finish a coherent unit, then integrate latest main and rerun validation before merge.
Worktrees are also useful for review-only experiments. A security review or legacy modernization pilot can modify an isolated branch, run tests, and compare outcomes without polluting the developer’s main checkout. If the experiment proves unhelpful, deleting the worktree cleanly discards the trial while preserving the report or selected commits.
Headless workflows can create independent worktrees per job so CI/fan-out tasks do not race on one workspace. Combine this with Claude Code Headless Mode when batch jobs analyze or modify multiple issues in parallel and each result should become a separate branch/artifact.
Subagent worktrees should have an explicit merge owner. The agent can implement and test, but a human or coordinating agent should decide whether the branch is still compatible with current main and whether semantic conflicts exist. Git can report a clean textual merge while two concurrent agents made incompatible architectural decisions.
Operationally, monitor stale worktrees and branches. Long-abandoned isolated sessions consume disk, keep outdated dependencies, and confuse branch discovery. A cleanup policy can remove worktrees with no changes automatically and flag changed worktrees older than a threshold for manual review before deletion.
Worktree-specific environment files should be generated or templated, not copied blindly from the main checkout. Secrets, ports, database names, and service URLs may need unique values per worktree. Keep real secrets outside Git and use an environment bootstrap that can create a safe local configuration for the isolated task.
File watchers and IDEs can also interact with several worktrees at once. A global formatter, language server, or build watcher may consume resources or write caches across all checkouts. Make sure developer tooling understands the separate roots and does not “helpfully” edit files in the wrong branch.
Worktree isolation is especially valuable for test-generation or security-fix agents that may make broad edits. Combine it with Claude Code Subagents so one agent researches in the main context while another implements in an isolated checkout. The coordinator can compare the resulting branch without losing its own clean working tree.
Conflict resolution should preserve intent. When two worktrees change the same area, do not let an automated merge pick one version mechanically. Re-read each task’s rationale, tests, and API assumptions, then reconcile the semantic design. Parallelism saves time only when integration receives the same engineering attention as the isolated tasks.
For long-running background work, record the base commit and task specification at worktree creation. If main advances significantly, the reviewer can decide whether to rebase, rerun the task, or discard the branch. Without that provenance, an old agent branch may look current simply because it merges cleanly.
Shared Git hooks and repository tooling should be checked in each worktree just as they are in the main checkout. Commit-msg hooks, code generators, pre-commit frameworks, and local config may resolve paths differently from an isolated directory. Run the normal repository validation from inside the worktree so the branch is proven under the same developer controls that will apply after merge.
Worktree discipline should include ownership of files and integration order. Parallel agents can still conflict semantically even when Git prevents direct working-tree collisions, so teams need small commits, explicit scopes, and an integration pass that re-runs the relevant tests after branches converge.
