Claude Code Now Has Built-In Git Worktree Support

Boris Cherny, the creator of Claude Code, dropped the announcement this morning: built-in git worktree support is now in the CLI.

The desktop app already had this. The CLI is now at feature parity. It shipped across two back-to-back releases: 2.1.49 (February 20) and 2.1.50 (February 21).

The Problem It Solves

If you’ve run multiple Claude Code sessions in the same repo, you’ve seen the problem. Two agents editing the same files at the same time means one of them is going to blow up the other’s work. It’s not a bug in Claude Code — it’s just how shared working trees behave. You can’t have two processes freely rewriting the same files without conflicts.

Worktrees fix this at the git level. Each agent gets its own checkout of the repo on its own branch in its own directory. They share the object store, so there’s none of the disk overhead you’d get from a full clone. But the working files are completely separate. No clobbering.

Cherny himself recommends spinning up 3-5 git worktrees at once, each with its own Claude session running in parallel, calling it “the single biggest productivity unlock.”

The --worktree Flag

Start a session with claude --worktree (or the -w shorthand) and Claude spins up in an isolated git worktree automatically.

# Claude names the worktree for you (e.g., "bright-running-fox")
claude --worktree

# Or name it yourself
claude --worktree feature-auth
claude -w bugfix-123

Worktrees land at .claude/worktrees/<name> in your repo root. The branch gets named worktree-<name> and branches from your default remote. Add .claude/worktrees/ to your .gitignore so the contents don’t show up as untracked files in the main repo.

Pair it with --tmux and each session gets its own tmux window, giving you process isolation on top of the filesystem isolation. Community tools like workmux and claude-tmux have been doing variations of this pattern for a while; now the core functionality is built in.

Worktree Cleanup

When a session ends, Claude checks whether anything changed:

• No changes: the worktree and its branch are removed automatically. Clean exit, no leftovers.
• Changes exist: Claude prompts you to keep or remove it. Keeping preserves the directory and branch for later. Removing deletes everything including uncommitted work.

Subagent Isolation

This is where it gets interesting for complex tasks. When Claude is orchestrating multiple subagents — a large batch migration, parallel feature work, a monorepo refactor — each subagent can now get its own worktree. They work independently and their changes don’t touch each other until you’re ready to merge.

You can ask for this at runtime (“use worktrees for your agents”), or you can bake it into your custom agent definitions so it’s always the default.

Custom Agent Frontmatter

If you’re building agents in .claude/agents/, add isolation: worktree and every invocation of that agent gets its own isolated worktree automatically. No per-session flag required.

---
name: migration-agent
description: Runs large batched code migrations in isolation
isolation: worktree
---

Your agent instructions here...

The worktree lifecycle follows the same cleanup rules: auto-removed if nothing changed, prompted if there are commits or uncommitted changes.

Two bugs related to this were fixed in 2.1.50 as well: custom agents and skills weren’t being discovered when running from a git worktree (project-level .claude/agents/ from the main repo is now included), and background tasks in worktrees were failing because of remote URL resolution reading from the wrong gitdir.

Non-Git VCS Support

Mercurial, Perforce, and SVN users aren’t left out. Version 2.1.50 adds WorktreeCreate and WorktreeRemove hook events. When you configure these hooks, they replace the default git behavior entirely.

WorktreeCreate fires when a worktree is needed. Your hook receives a JSON payload with the session ID, working directory, and the worktree name. It must print the absolute path to the created worktree directory on stdout and exit 0. Anything else goes to stderr so it doesn’t interfere with the path Claude reads.

{
  "session_id": "abc123",
  "cwd": "/Users/you/my-project",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeRemove fires on cleanup. It receives the path that WorktreeCreate printed, so your hook knows exactly what to tear down.

An SVN example from the docs:

{
  "hooks": {
    "WorktreeCreate": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
      }]
    }],
    "WorktreeRemove": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
      }]
    }]
  }
}

Other Things That Shipped in 2.1.50

The worktree features were the headline, but 2.1.50 brought a few other things worth knowing about:

• claude agents CLI command: lists all configured agents in your project
• Fixed a memory leak in agent teams where completed teammate tasks were never garbage collected
• Opus 4.6 in fast mode now gets the full 1M context window
• CLAUDE_CODE_DISABLE_1M_CONTEXT environment variable if you need to cap it
• startupTimeout config for LSP servers
• /extra-usage command support in VSCode sessions

---

Available now in CLI, Desktop app, IDE extensions, web, and Claude Code mobile. Update to 2.1.50 and run claude --worktree to try it.