If you have run two Claude Code sessions against the same repository at the same time, you already know the problem. One session rewrites a service file, the other reads a stale version of it, and you end up with broken logic split across an uncommitted diff that neither session produced intentionally. With 115,000 or more developers now using Claude Code and 195 million lines of code processed every week, this collision pattern has become one of the most reported friction points in agentic development workflows. Worktrees are the structural fix. Claude Code’s built-in worktree support gives each session its own isolated working directory backed by a single shared .git folder, so two agents can write simultaneously to a codebase without ever touching the same file state.

Claude Code Worktrees 2026: Why Parallel Sessions Need Isolation

Claude Code’s adoption curve in 2026 has pushed teams beyond single-session workflows: over 75% of AI-adopting startups now run Claude Code, and enterprise subscriptions have grown 4x year-over-year. That scale forces a real engineering question — when you have multiple Claude Code sessions open, what stops them from overwriting each other’s changes? The answer without worktrees is: nothing. Two sessions sharing the same working directory will read and write the same files. If session A is refactoring a module while session B is adding tests against the original interface, one of them will produce work against a moving target and the merge will be painful. The worktree model solves this at the filesystem level before any conflict can form. Each session operates in its own directory with its own checked-out branch, so the file surfaces never overlap. This is not a soft guideline — it is a hard guarantee enforced by Git’s worktree mechanism. Understanding why that guarantee exists requires knowing how Git worktrees actually work underneath Claude Code’s flag abstraction.

What Are Git Worktrees and How Claude Code Uses Them

Git worktrees are a native Git feature, available since Git 2.5, that let a single .git directory back multiple working directories simultaneously. Under the normal model, one repository equals one working directory equals one active branch. Switching branches means stashing or committing current changes and checking out a different snapshot. Worktrees remove that constraint: you can have main, feature/auth, and hotfix/payment all checked out in separate directories at the same time, all sharing one .git store, all fully functional. Claude Code layers its --worktree flag on top of this native capability. When you start a session with --worktree, Claude Code calls git worktree add internally, creates an isolated directory under .claude/worktrees/, and runs your session there. The main repository’s .git tracks all active worktrees. Neither session can accidentally read the other’s in-progress file state because they are checked out to separate branches on separate paths. Crucially, all worktrees inherit the main repository’s CLAUDE.md settings, so project-level instructions, code style rules, and tool configurations apply uniformly across every parallel session without duplication.

# Verify your git version supports worktrees (2.5+)
git --version

# View all active worktrees in a repository
git worktree list

The –worktree Flag: Setting Up Parallel Claude Code Sessions

The --worktree flag is the primary interface for creating isolated Claude Code sessions. It handles branch creation, directory setup, and checkout in a single command — what would otherwise take three or four manual Git commands collapses into one. You can let Claude Code auto-name the worktree, which uses a timestamp-based identifier suitable for throwaway sessions, or you can supply an explicit branch name for sessions you intend to revisit. Claude Code creates the new working directory under .claude/worktrees/<branch-name>/ and starts the session there. The worktree is completely isolated from your main working directory and from any other active worktree sessions. Multiple terminal windows can each run claude --worktree against the same repository simultaneously, and they will not interfere with each other.

# Auto-named worktree — good for throwaway exploration
claude --worktree

# Named worktree — good for work you will return to
claude --worktree feature/auth-refactor

# Open an existing branch as a worktree
claude --worktree existing-branch-name

The distinction between named and auto-named worktrees matters in practice. An auto-named session (claude --worktree) produces a directory like .claude/worktrees/wt-1746700800/. It disappears cleanly when the session ends with no changes. A named session (claude --worktree feature/auth-refactor) persists the branch and can be resumed later, which is the right choice when implementing a feature over multiple work sessions rather than a single exploratory run.

Subagent Worktree Isolation: Preventing Multi-Agent File Conflicts

Subagents compound the isolation problem. When a Claude Code orchestrator spawns multiple subagents to work in parallel — a research agent, an implementation agent, a test-writing agent — they can all reach into the same working directory unless you explicitly prevent it. The isolation: worktree directive in AGENTS.md is the mechanism that prevents it. Any agent definition that includes this field gets its own automatically provisioned worktree every time it is invoked. The orchestrator receives results from each subagent as separate branches, reviews them, and merges selectively. Without this isolation, a research agent that opens files “just to read them” can accidentally write cache artifacts or modify files mid-session while an implementation agent is generating code against the same paths.

---
name: researcher
description: Read-only codebase investigation and analysis agent
isolation: worktree
---

You are a code investigation specialist. Your job is to explore the codebase,
understand structure, identify patterns, and produce written reports.
You do not modify source files. All findings are written to a report file
in your worktree directory. Do not assume the state of files matches what
another agent may have written — work only from what you can read in this
worktree's checkout.

---
name: implementer
description: Feature implementation agent that writes production code
isolation: worktree
---

You receive a specification from the orchestrator and implement it in this
isolated worktree. Do not pull changes from other worktrees mid-session.
Complete the implementation, run tests within this worktree, then signal
completion. The orchestrator will handle merging.

The isolation: worktree field applies per agent invocation, not per agent definition. If the orchestrator calls the researcher agent three times in parallel, each invocation gets its own worktree. This makes the pattern safe for fan-out patterns where many instances of the same agent role run simultaneously.

Real Parallel Workflow Patterns with Claude Code Worktrees

The research-to-implementation pipeline is the most productive pattern for complex features. A research subagent in worktree 1 explores the codebase, reads existing patterns, and produces a spec document. An implementation subagent in worktree 2 picks up that spec and writes code. A review pass happens in the main worktree or a third dedicated branch. These three phases can overlap: while the implementation agent is working from the research output, a new research agent can already be investigating the next feature. The three-terminal setup below is a concrete example for a database migration that involves schema changes, data transformation scripts, and ORM updates — three distinct concerns that have no reason to block each other.

# Terminal 1: schema work
claude --worktree db/schema-migration \
  "Write DDL migrations to add the new subscription_tier column to the users table"

# Terminal 2: data transformation (runs in parallel)
claude --worktree db/data-transform \
  "Write a Python script to backfill subscription_tier from the legacy plan field"

# Terminal 3: application layer (runs in parallel)
claude --worktree app/orm-update \
  "Update the User model and all queries to use subscription_tier"

Each worktree session runs on its own branch. When all three complete, you review the output branches and open three separate PRs in dependency order: schema first, backfill second, ORM third. The parallel execution cuts the elapsed time by roughly the duration of the longest session rather than the sum of all three. For the research-implementation-review pattern with subagents, the AGENTS.md isolation directive handles the worktree provisioning automatically — the orchestrator does not need to pass --worktree flags manually.

Worktree Cleanup: Automatic vs Manual Lifecycle Management

Claude Code’s cleanup behavior depends on what happened during the session. If a worktree session ends with no uncommitted changes — a common outcome for exploration or research sessions that write only to a report file — Claude Code removes the worktree directory and its backing branch automatically. If changes exist, Claude Code prompts: keep the worktree (and branch) or discard it. This bifurcated behavior is deliberate. Throwaway sessions should not require manual cleanup, but work-in-progress should not disappear silently. In team environments, worktrees accumulate over time regardless of cleanup behavior. Use these commands to audit and prune.

# List all worktrees with their paths and HEAD commits
git worktree list

# Remove a specific worktree directory (branch is kept)
git worktree remove .claude/worktrees/feature-auth-refactor

# Remove a worktree and delete its branch in one pass
git worktree remove .claude/worktrees/feature-auth-refactor
git branch -d feature/auth-refactor

# Prune stale worktree metadata (for worktrees deleted outside of git)
git worktree prune

One housekeeping practice worth adopting: add .claude/worktrees/ to your .gitignore at the project root. Worktree metadata is local to each developer’s machine and should not be committed to the shared repository. Without this entry, a git status in the main worktree will flag the entire .claude/worktrees/ tree as untracked. A related point: node_modules and other large dependency directories are not shared between worktrees. Each worktree checkout has its own copy, which means running npm install (or pnpm install, poetry install) separately in each worktree. If disk space is a concern, pnpm’s global content-addressable store handles this cleanly — packages are stored once and hard-linked into each worktree, so the per-worktree footprint is minimal.

Claude Code Desktop App: Automatic Worktree Isolation

The Claude Code desktop app removes the --worktree flag entirely from the daily workflow. Every new session tab the app creates automatically provisions a fresh worktree. You open a new tab, pick your repository, start your task — the worktree is created in the background with no additional input required. This matters more than it might initially seem. The CLI flag is easy to forget, particularly when you are in the middle of debugging something and open a second terminal window out of habit. The desktop app makes isolation the default rather than an opt-in. Each tab displays the branch it is operating on and the worktree path, so you can see at a glance which sessions are active and what branch each owns. When a session finishes, the same automatic cleanup logic applies: no changes means silent removal, uncommitted changes trigger a prompt. The session list UI gives teams a centralized view of all active worktree sessions, which is useful when coordinating multiple agents across a large codebase. Business subscriptions have grown 4x in 2026 partly because this desktop workflow reduces the onboarding friction for developers who are not deeply familiar with Git worktrees — they get the isolation benefits without needing to understand the underlying mechanism.

Common Worktree Mistakes and How to Avoid Them

The first mistake is running two Claude Code sessions in the same working directory without worktrees and assuming separate terminal windows provide isolation. They do not. Both sessions see the same file state, and if they both write to the same file within the same session window, the last write wins. The second mistake is creating worktrees without a clear scope. A worktree session that starts touching ten different modules across several concerns will eventually produce conflicts when you try to merge it back — not with other worktrees, but with main, because the changeset is too broad to review clearly. Keep each worktree scoped to a single concern. The third mistake is not cleaning up. Teams that run frequent parallel sessions accumulate dozens of stale worktree directories over weeks. Running git worktree list weekly and pruning completed ones keeps the repository root navigable.

# Check what branches have been merged and can be cleaned up
git branch --merged main

# Prune remote-tracking branches that no longer exist on the remote
git remote prune origin

# Remove all worktree metadata for deleted directories
git worktree prune --verbose

The fourth mistake is forgetting that CLAUDE.md is inherited but AGENTS.md is not automatically shared across worktrees. If you define agent behavior in an AGENTS.md file in the main worktree, subagents running in isolated worktrees will see it only if the AGENTS.md is committed to the branch that the worktree checks out. Keep AGENTS.md committed to your default branch so every worktree inherits it on checkout. The fifth mistake is running worktree sessions on the same branch as another active session. Git prevents two worktrees from checking out the same branch simultaneously — you will see an error. If you need two sessions doing similar work, they must be on different branches, which is correct behavior anyway since their outputs will diverge.

FAQ

Q: What is the difference between Claude Code’s --worktree flag and running git worktree add manually?

git worktree add creates the working directory but nothing else. Claude Code’s --worktree flag wraps that with automatic naming, session tracking, lifecycle management (the cleanup prompt on exit), and integration with the AGENTS.md isolation system. For one-off manual use, git worktree add is fine. For reproducible, team-scale workflows with subagents, the Claude Code flag and AGENTS.md directive are the correct tools.

Q: Does using worktrees increase my Claude Code API costs?

Yes, proportionally. Each worktree session is an independent Claude API context. Running three parallel sessions consumes up to three times the tokens of a single session covering the same ground. The efficiency argument is that elapsed time drops — three parallel sessions finishing in the time of the longest one versus sequential sessions summing all three. Whether the token cost is worth the time saving depends on your rate and how much calendar time matters relative to API budget.

Q: How do I merge work from multiple worktrees back to main?

Each worktree operates on its own branch. When a session completes, push the branch to the remote and open a pull request as you normally would. If multiple worktrees produce work that depends on each other (schema change + ORM update), merge them in dependency order — not simultaneously. There is no special Claude Code merge command; the standard Git PR workflow handles it.

Q: Can worktrees access files outside their own directory?

A worktree session can technically read any file the process has filesystem access to, but the working directory for the session is the worktree root. Claude Code’s file operations are scoped to the project directory by default. Crossing worktree boundaries manually defeats the isolation guarantee and should be avoided. If two sessions need shared data, commit it to the branch and let the other worktree pull it.

Q: Does the isolation: worktree directive in AGENTS.md work for all agent types?

The isolation: worktree field applies to custom agents defined in AGENTS.md and invoked by an orchestrating Claude Code session. It does not apply to top-level CLI sessions — those are isolated by passing --worktree at startup. For subagent-heavy architectures where the orchestrator spawns many specialized agents, AGENTS.md isolation is the right lever. For a developer manually opening multiple terminal sessions, --worktree at the CLI is the right lever. Both mechanisms produce the same underlying Git worktree structure.