TIL: Git Worktree: The Secret Weapon for AI Coding Agents

Today I finally understood why everyone in the AI coding space keeps talking about git worktrees. After running into context switching nightmares with Claude Code, I discovered that worktrees solve the fundamental problem of running multiple AI agents in parallel.

The Problem: Context Switching Kills AI Agents

When an AI agent like Claude Code operates in a single directory and you switch branches:

Re-indexing overhead - The agent must re-scan the entire codebase when files change
Context pollution - Conversation history built around one branch becomes invalid
State loss - Partial edits, uncommitted changes, or build artifacts get corrupted

For parallel agent workflows, this becomes a nightmare. One agent’s branch switch causes filesystem changes that confuse another agent’s understanding of the codebase.

What is Git Worktree?

Git worktree (introduced in Git 2.5) lets you maintain multiple working directories from the same repository, each checked out to a different branch. The key insight: all worktrees share the same .git/objects database while maintaining isolated file systems.

project/
├── .git/
│   ├── objects/        ← shared across all worktrees
│   ├── refs/           ← shared branches, tags
│   └── worktrees/
│       ├── feature-a/  ← per-worktree metadata
│       └── bugfix/     ← per-worktree metadata
│
├── main/               ← main worktree
├── feature-a/          ← linked worktree
└── bugfix/             ← linked worktree

Unlike cloning the repo multiple times (which duplicates the entire .git directory), worktrees achieve multi-directory checkout with minimal disk overhead.

Essential Commands

# Create a worktree for a new branch
git worktree add ../project-feature-a -b feature-a

# Create a worktree for an existing branch
git worktree add ../project-bugfix bugfix-branch

# List all worktrees
git worktree list

# Remove a worktree after merging
git worktree remove ../project-feature-a

# Prune stale worktree metadata
git worktree prune

Why This Matters for AI Coding Agents

Claude Code

Anthropic’s official best practices now recommend worktrees for parallel agentic coding:

# Create worktrees for different tasks
git worktree add ../project-auth feature/oauth
git worktree add ../project-ui feature/dashboard

# Start independent Claude Code sessions
cd ../project-auth && claude
cd ../project-ui && claude

Each Claude session maintains complete context isolation. Switch terminal tabs and each Claude is exactly where you left it - full knowledge of its branch, recent edits, and task at hand.

Cursor 2.0 Parallel Agents

Cursor’s Parallel Agents feature (late 2025) bakes worktree integration directly into the IDE. It supports up to 8 concurrent agents, each automatically isolated in its own worktree. The platform handles worktree creation, context switching, and cleanup automatically.

The Parallel Advantage

Running the same task through 2-3 agents and selecting the best implementation consistently produces superior code. LLM non-determinism becomes a feature:

# Create 3 worktrees from main
git worktree add -b attempt-1 .trees/attempt-1 main
git worktree add -b attempt-2 .trees/attempt-2 main
git worktree add -b attempt-3 .trees/attempt-3 main

# Start agents in parallel with same task
cd .trees/attempt-1 && claude "implement caching layer" &
cd .trees/attempt-2 && claude "implement caching layer" &
cd .trees/attempt-3 && claude "implement caching layer" &

# Review all three, cherry-pick best elements

Practical Patterns

Pattern 1: One Agent Per Feature

git worktree add ../feature-auth feature/oauth-integration
git worktree add ../feature-ui feature/dashboard-redesign

# Each agent works independently
cd ../feature-auth && claude
cd ../feature-ui && cursor

Pattern 2: Hotfix Without Interruption

While working on a long-running feature:

# You're deep in feature work
cd ~/project/feature-a
claude "implement complex refactoring"

# Alert: production bug!
# Instead of stashing or interrupting...
git worktree add -b hotfix-urgent .trees/hotfix main
cd .trees/hotfix
claude "fix payment timeout"
git push

# Feature A work remains untouched

Gotchas and Best Practices

1. Explicit Boundaries in Prompts

AI agents don’t inherently understand worktree boundaries. Be explicit:

“You are working in /home/user/myproject-auth-feature on the feature/oauth branch. Make all changes within this directory.”

2. Port Conflicts

Multiple dev servers across worktrees will clash on ports. Configure different ports per worktree or use containers.

3. Shared Config Files

Worktrees share configuration files by default. For .env files:

Symlink shared ones to avoid duplication
Copy .env.local files if they diverge per branch

4. Clean Up After Merging

# Always remove worktrees after merging
git worktree remove .trees/feature-completed

# Prune any stale references
git worktree prune

Quick Reference

Command	Description
`git worktree add <path> <branch>`	Create worktree for existing branch
`git worktree add <path> -b <new-branch>`	Create worktree with new branch
`git worktree list`	Show all worktrees
`git worktree remove <path>`	Remove a worktree
`git worktree prune`	Clean up stale metadata

What I Learned

Git worktrees enable true parallel AI agent workflows without context switching overhead
Each worktree has its own HEAD, index, and working files - but shares Git history
Cursor 2.0 and Claude Code both benefit massively from worktree isolation
Running 2-3 agents on the same task and picking the best result produces higher quality code
Explicit boundaries in agent prompts are essential - they don’t understand worktree isolation implicitly
Production teams report 40-60% speedup by combining worktrees with parallel AI agents