Claude Code Worktree Explained: Setup & Parallel Agents

You know that feeling when two Claude Code sessions are editing the same file at the same time — and you're watching your carefully built feature slowly get overwritten by a bugfix branch? Yeah. I've been there more than once, and it's infuriating.

I'm Hanks, and after running parallel agent workflows on real production repos, I can tell you: the messy workaround days are over. As of Claude Code v2.1.49 (shipped February 19, 2026), native git worktree support landed in the CLI — and it changes how you run parallel agents entirely. Let me walk you through exactly how it works, how to set it up, and where the gotchas are hiding.

What Claude Code Worktree Support Does — Shipped v2.1.49 (Feb 2026)

Git worktrees aren't a new concept — the command lets a single repository support multiple working trees simultaneously, so you can check out more than one branch at a time without duplicating the repo. What Claude Code v2.1.49 adds is first-class native support so you don't have to wire this up yourself.

Here's the core mechanic: each claude --worktree name command creates an isolated branch and a dedicated directory at .claude/worktrees/name/. Every agent gets its own filesystem state. They don't clobber each other. And critically — all worktrees share the same .git history and remote connections, so you're not duplicating your whole repo.

The feature ships across CLI, Desktop app, IDE extensions (VS Code and JetBrains), and the web interface. The Desktop app actually had built-in worktree support before v2.1.49 — the CLI catch-up is what makes this story complete.

What gets created with each claude --worktree name** call:**

Object	Path / Name	Purpose
Working directory	.claude/worktrees//	Isolated filesystem state for this agent
Git branch	worktree-	Dedicated branch, forked from default remote
Shared .git database	(repo root)	Full history shared across all worktrees — no duplication
Auto-cleanup	on session exit	Removed if no changes; prompted if commits exist

How to Set Up and Use Worktrees

Single Agent

The simplest path: pass --worktree (or -w) with a name when launching Claude Code.

# Creates .claude/worktrees/feature-auth/ with branch worktree-feature-auth
claude --worktree feature-auth

# Omit the name — Claude generates a random one automatically
claude --worktree

# Add --tmux to launch in its own tmux session — keeps running if you close the terminal
claude --worktree feature-auth --tmux

You can also trigger worktree mode mid-session. Just ask Claude: "work in a worktree" and it creates one on the fly and switches your session into it. Useful when you realize partway through that your changes need isolation.

For the Desktop app: head to the Code tab, enable worktree mode, and every new session gets its own isolated worktree automatically. No flag required.

Multiple Agents in Parallel

This is where things get genuinely powerful. Open separate terminals and fire them up:

# Terminal 1 — building the auth feature
claude --worktree task-auth

# Terminal 2 — fixing a production bug simultaneously
claude --worktree bugfix-payment

# Terminal 3 — long-running refactor, runs in background via tmux
claude --worktree refactor-api --tmux

Each session gets its own files, its own branch, and its own context. The agents are completely independent — no shared file state, no merge conflicts mid-session, no stepping on each other's work.

Single session vs. parallel worktrees — at a glance:

Dimension	Single session	Parallel worktrees
File isolation	None — shared working directory	Full — each agent has its own directory
Branch management	Manual stashing required	Automatic — one branch per worktree
Mid-session merge conflicts	Common when tasks overlap	Impossible within a session
Git history	One shared branch	Shared .git DB, independent branches
Cleanup	Manual	Auto on no changes; prompted if commits exist

For automated coordination between parallel sessions — shared task lists, inter-agent messaging — that's a different tool: Claude Code agent teams, which run each worker in its own independent context window.

Subagents, Custom Agents & Non-Git VCS

Subagents

Subagents support isolation: "worktree" for working in a temporary git worktree with automatic cleanup. When Claude spawns subagents for task distribution, each one can get its own isolated environment. Just ask: "use worktrees for your agents" — and Claude handles the rest. Especially powerful for large batched changes and migrations where agents write to different parts of the codebase simultaneously.

Custom Agents

For repeatable workflows, declare worktree isolation directly in a custom agent's frontmatter:

---
name: refactor-agent
description: Handles large-scale refactoring tasks
isolation: worktree
---

Every time this agent runs, it automatically gets its own worktree — no manual flag needed. Store agent definitions in .claude/agents/ for team-wide sharing.

Non-Git VCS (SVN, Perforce, Mercurial, etc.)

Worktree isolation works with git by default. For other version control systems, WorktreeCreate and WorktreeRemove hook events let you provide custom worktree creation and cleanup logic. When configured, these hooks replace the default git behavior when you use --worktree — your script receives a JSON payload on stdin with the worktree name, creates the environment however you need, and prints the absolute worktree path to stdout. Claude starts the session in that directory. The same pattern works for custom git setups, such as projects that need a custom worktree location outside .claude/worktrees/ for frameworks like Laravel Valet or Herd.

Define the hooks in .claude/settings.json:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-setup.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-teardown.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

One nuance worth knowing: WorktreeRemove hooks are currently informational — they cannot block removal. If your workflow needs persistent multi-session worktrees that shouldn't be torn down on session exit, this open GitHub issue is tracking a proposed exit code 2 mechanism for WorktreeRemove to match the existing WorktreeCreate pattern.

Cleanup and Gotchas

Cleanup behavior is automatic but conditional. When a session ends with no changes, the worktree and branch are removed automatically. When changes or commits exist, Claude prompts you: keep (preserves directory + branch for later) or remove (deletes both, discards uncommitted work).

To clean up manually outside a Claude session:

# List all active worktrees
git worktree list

# Remove a specific worktree
git worktree remove .claude/worktrees/feature-auth

# Prune stale metadata after a force-delete
git worktree prune

Run dependency installs per worktree. Each new worktree is a fresh checkout — no node_modules, no virtual environments, no build artifacts carry over. Run your project setup inside each worktree before expecting Claude to build or test:

cd .claude/worktrees/feature-auth
npm install   # or: pip install -r requirements.txt, bundle install, etc.

Add .claude/worktrees/ to .gitignore. Forgetting this causes worktree directories to appear as untracked files in your main repo. Git worktrees only duplicate tracked files — anything in your .gitignore won't carry over to new worktrees either:

echo ".claude/worktrees/" >> .gitignore

Unwanted auto-creation in Desktop? A known issue in the GitHub tracker documents that the Desktop app creates a random worktree for every new session, with no current toggle to disable it. The workaround: use the CLI with claude (no --worktree flag) to operate directly on the main checkout, or run /permissions and add "EnterWorktree" to the deny list to prevent automatic worktree entry in CLI sessions.