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 Dora, and after spending time running parallel agent workflows on shared 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 — they've been a core git feature for years. What Claude Code v2.1.49 adds is first-class native support so you don't have to script it 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 is available across CLI, Desktop app, IDE extensions (VS Code and JetBrains), web, and the Claude Code mobile app. The Desktop app actually had built-in worktree support even before v2.1.49 — the CLI catch-up is what makes this story complete.

What's created	Value
.claude/worktrees//	Isolated working directory
worktree- branch	Dedicated git branch, branched from default remote
Shared .git database	No repo duplication; full history intact
Auto-cleanup on exit	Removed if no changes; prompt to keep if changes exist

How to Set Up and Use Worktrees

Single Agent

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

# Start Claude in an isolated worktree named "feature-auth"
# 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 (background-friendly)
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, check 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 — running a large refactor in the background
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.

The official Claude Code documentation on parallel workflows captures the core promise well: you can have Claude working on a feature in one worktree while fixing a bug in another, without either session interfering with the other.

Subagents, Custom Agents & Non-Git VCS

Subagents

When Claude spawns subagents for task distribution, each subagent can now get its own worktree automatically. Just ask: "use worktrees for your agents" — and Claude handles the rest. This is especially powerful for large batched changes and code migrations where agents are writing to different parts of the codebase in parallel.

Custom Agents

For repeatable agent workflows, add isolation: worktree to a custom agent's frontmatter definition:

---
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 these in .claude/agents/ for team-wide sharing.

Non-Git VCS (SVN, Juju, etc.)

Claude Code v2.1.50 shipped WorktreeCreate and WorktreeRemove hook events specifically for this use case. If your project uses a non-git version control system — or if you need custom worktree locations (e.g., outside .claude/worktrees/ for frameworks like Laravel Valet/Herd) — you define the hooks in .claude/settings.json:

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

When these hooks are defined, the --worktree flag calls your custom scripts instead of running git commands directly — full control over VCS setup and teardown.

Cleanup and Gotchas

Cleanup behavior is automatic but conditional:

No changes made: Worktree and branch are removed automatically when the session ends.
Changes or commits exist: Claude prompts you to keep or remove. Keeping preserves directory + branch for later; removing deletes both and discards uncommitted work.

To clean up manually outside a Claude session:

git worktree list
git worktree remove .claude/worktrees/feature-auth

Run dependency installs per worktree. Each new worktree is a fresh checkout — no node_modules, no virtual environments, no build artifacts. Run your project setup (npm install, pip install, bundle install, etc.) inside each worktree before expecting Claude to build or test.

Add .claude/worktrees/** to .gitignore****.** Forgetting this causes worktree directories to show up as untracked files in your main repository. Do it once and never think about it again:

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

Unwanted auto-creation? There's currently a known bug where Claude Code can create worktrees for agents even when you didn't explicitly ask for it. The fix has landed and is shipping in the next release — but in the meantime, the official workaround from the Anthropic team is to run /permissions and add "EnterWorktree" to the deny list.