git worktree: A Hidden Git Feature Rediscovered in the Age of AI Coding Agents | Namsang LABS

#TL;DR

git worktree is a built-in Git feature that lets you check out multiple branches into separate directories simultaneously. Introduced in 2015, it spent a decade as a niche convenience. Now it is being rediscovered as infrastructure for running AI coding agents like Claude Code in parallel. Claude Code supports it natively with the --worktree flag, and even subagent isolation and the /batch skill are built on worktrees.

#What is `git worktree`

A Git repository has only one working directory by default. Switching branches means git stash → checkout → work → checkout back → stash pop. When you have many modified files or build caches, switching itself becomes a burden.

git worktree checks out a different branch of the same repository into a separate directory. Each directory has its own independent working tree, but they share the .git folder — commit history, branch info, and configuration.

my-project/               ← main worktree (main branch)
my-project-payments/       ← linked worktree (feature/payments)
my-project-refactor/       ← linked worktree (feature/refactor)

This looks similar to git clone, but with a key difference. Clone duplicates the entire history and uses twice the disk space. Worktree shares the .git database, minimizing additional disk usage. Commits made in one worktree are instantly visible in the other.

#Basic commands

# Create a worktree with a new branch
git worktree add ../my-project-hotfix -b hotfix/critical main

# Create a worktree for an existing branch
git worktree add ../my-project-payments feature/payments

# List current worktrees
git worktree list

# Remove a worktree
git worktree remove ../my-project-hotfix

# Clean up manually deleted worktrees
git worktree prune

#Good to know

You cannot check out the same branch in two worktrees simultaneously. Git enforces this. (Overridable with --force, but not recommended.)
Stashes are shared between worktrees, since they are stored in the .git object store.
.gitignored files (node_modules, .env, etc.) are not copied to worktrees. You need to reinstall dependencies in each new worktree.
Worktrees are linked to the original. They are not separate clones, so branch creation and commits are visible from both sides.

#Why it is getting attention again in the age of AI coding agents

git worktree was introduced in Git 2.5 (2015). For a decade it sat in the “nice to know” category. That changed in 2025–2026 as AI coding agents started actively leveraging it.

#The core reason: AI agents occupy the working directory

AI coding agents like Claude Code, Cursor, and Codex directly read and modify files in the working directory. While an agent is working on feature/payments, the working directory is in a modified state. Checking out another branch or running another agent session in the same directory causes conflicts.

When humans work, they edit files one at a time, so git stash suffices. But AI agents modify multiple files simultaneously, and tasks take several minutes. During that time, the developer can only wait.

Worktrees solve this. Assign a separate worktree to each agent session, and you can run multiple tasks concurrently. While an agent works in one worktree, you can review completed results in another.

“The real power is that while Claude is working in one worktree, you can be reviewing what finished in another. You’re not waiting — you’re directing.”

— Dan Does Code: Parallel Vibe Coding with Git Worktrees

#A trend across the agent ecosystem

This is not just a Claude Code story. OpenAI’s Codex CLI runs background agents in isolated sandboxes. Open-source tools like parallel-code run Claude Code, Codex, and Gemini in separate worktrees in parallel. Boris Cherny (Claude Code developer at Anthropic) has mentioned routinely running 10–15 worktrees simultaneously.

What was a “convenience feature” has become “parallel execution infrastructure.”

#Claude Code’s native worktree support

Claude Code (v2.1.49+) supports worktrees natively. No need to manually run git worktree add — the --worktree (-w) flag handles worktree creation and session startup in one step.

#Basic usage

# Create a named worktree + start session
claude --worktree feature-auth
# Created at .claude/worktrees/feature-auth/
# Starts on worktree-feature-auth branch

# Auto-generate a name
claude --worktree
# Something like bright-running-fox

# Shorthand works too
claude -w bugfix-123

For parallel work, just open multiple terminals.

# Terminal 1: feature work
claude -w feature-auth

# Terminal 2: bug fix
claude -w bugfix-payment

# Terminal 3: refactoring exploration
claude -w refactor-db

Each session is completely independent. No file conflicts, no context interference.

#Worktree cleanup

When you end a session, Claude asks how to clean up.

No changes: Worktree and branch are automatically deleted.
Changes exist: You can choose to keep or delete. Keeping lets you return later; deleting removes uncommitted changes and the branch.

Orphaned subagent worktrees are cleaned up automatically. Worktrees created with the --worktree flag are not auto-cleaned, so you need to remove them manually or choose the cleanup option when ending the session.

#Auto-copying environment files with `.worktreeinclude`

New worktrees do not include .gitignored files like .env. Create a .worktreeinclude file in the project root to auto-copy specified files.

# .worktreeinclude (uses .gitignore syntax)
.env
.env.local
config/master.key

#Subagent and `/batch` — extending worktrees

#Subagent worktree isolation

Claude Code’s subagents can also use worktrees. Request “use worktrees for your agents” during a session, or set isolation: worktree in a custom subagent’s frontmatter.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Review code changes for quality issues
isolation: worktree
allowed-tools: ['Read', 'Bash']
---
Review the changes in the current branch...

#`/batch` skill — large-scale parallel changes

The /batch skill leverages worktrees at scale. It decomposes a large task into 5–30 independent units, launching a background agent in a separate worktree for each. Each agent independently implements, tests, and creates a PR.

# Example: migrate src/ from Solid to React
/batch migrate src/ from Solid to React

The orchestrator analyzes the task, decomposes it into units like src/components/Button and src/pages/Home, and runs agents in separate worktrees for each. On completion, individual PRs are created for each unit, enabling granular review.

The incident.io team reported an 18% (30-second) reduction in API client generation build time using Claude Code’s parallel worktree execution.

#Practical workflows

#Basic pattern: parallel development

# 1. Start feature work
claude -w feature-auth

# 2. Bug fix in another terminal
claude -w bugfix-payment

# 3. Review completed worktree while Claude works
cd .claude/worktrees/feature-auth
git diff main

# 4. Create PR (from inside the worktree)
git push -u origin feature/auth
gh pr create --title "Add auth module" --base main

# 5. Clean up
git worktree remove .claude/worktrees/feature-auth

#Writer/Reviewer pattern

Use two sessions with role separation. One session implements the feature, and another reviews with fresh context. Less biased than having the same agent review its own code.

# Terminal 1: implement
claude -w implement-feature

# Terminal 2: review (after implementation completes)
claude -w review-feature
# "review the changes in ../implement-feature branch"

#Test-driven pattern

One session writes tests first, and another writes code to pass them.

# Terminal 1: write tests
claude -w write-tests

# Terminal 2: implement
claude -w implement
# "make all tests in the write-tests branch pass"

#Things to watch out for

#Dependencies need to be reinstalled

Worktrees do not copy .gitignored files, so node_modules, virtual environments, etc. need fresh installation. .worktreeinclude can copy .env files, but large dependencies must be installed manually.

#Modifying the same files causes merge conflicts

File isolation between worktrees is complete, but merging branches that modified the same files will still produce conflicts. This is Git behavior, not a worktree issue. Separating the scope of files each session modifies is important.

#There are practical limits on worktree count

Git does not limit the number of worktrees, but each Claude Code session running in a worktree consumes CPU and memory. 3–5 is a practical sweet spot; beyond that, consider CI/CD or agent orchestration.

#Use notification settings

Running multiple worktrees makes it hard to track which session finished. Setting up Claude Code’s Notification hook lets you receive alerts when a session completes or needs input.

On macOS, terminal-notifier is a widely used CLI notification tool.

brew install terminal-notifier

Add the following to .claude/settings.json.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message '$CLAUDE_NOTIFICATION'"
          }
        ]
      }
    ]
  }
}

#stash vs clone vs worktree

Aspect	git stash + checkout	git clone	git worktree
Disk usage	Minimal	Full duplication	Minimal (shared)
History sharing	Same repo	Separate copy	Same repo
Parallel work	Not possible	Possible	Possible
AI agent parallel execution	Not possible	Possible but inefficient	Optimal
Instant commit sharing	N/A	Requires push/pull	Instant
Claude Code native support	None	None	`--worktree` flag

Clone can do parallel execution too, but it duplicates the entire repository, doubling disk usage and requiring push/pull to share commits. Worktree achieves the same result without that overhead.

git worktree is a decade-old feature, but it has found its true purpose alongside AI coding agents. claude -w task-name — one line, and your parallel development environment is ready.

#References

Claude Code Docs — Common Workflows: Git Worktrees — Official documentation on worktree support
Botmonster — CLAUDE.md Productivity Stack: Skills, Git Worktrees, and Hooks — Full stack guide: worktree + CLAUDE.md + hooks + skills
Dan Does Code — Parallel Vibe Coding: Using Git Worktrees with Claude Code — VS Code integration, PR workflow, conflict handling
incident.io — Shipping Faster with Claude Code and Git Worktrees — 18% build time reduction case study
Threads — Boris Cherny: Introducing built-in git worktree support for Claude Code — Official announcement from Claude Code developer
GitHub — parallel-code: Run Claude Code, Codex, and Gemini side by side — Open-source tool for parallel AI agent execution via worktrees
Git official docs — git-worktree