Git Worktrees Clearly Explained — And How to Use Them With AI Agents

⏱ ~18 min 🎤 David Ondrej 🏷 Git Worktrees 🏷 AI Agents 🏷 Parallel Development

Git worktrees let you check out multiple branches of the same repository simultaneously — each in its own directory, sharing a single .git store. This old Git feature has suddenly become essential in the AI agent era: instead of one agent blocking another by monopolizing the working directory, you give each agent its own worktree and let them code in parallel on separate branches. This is the missing piece for multi-agent development workflows.

▶️ Watch Video

01

Problem Without Worktrees

0:00

In a standard Git workflow, you have one working directory. To switch branches, you run git checkout or git switch, which changes the files on disk. This creates several problems:

Context switching cost — switching branches means saving state, stashing changes, rebuilding dependencies
Single occupancy — only one branch can be checked out at a time in a single directory
Agent collision — if two AI agents work on the same repo, they fight over the working directory
Build cache invalidation — switching branches often invalidates build caches, costing minutes per switch

"With one working directory, switching branches is like moving to a different apartment every time you want to work on a different project. Worktrees let you have multiple apartments."

02

Why Worktrees Are Exploding Now

2:00

Git worktrees have existed since Git 2.5 (2015), but they're having a moment right now. The reason: AI coding agents. When you want multiple agents working on the same repository simultaneously, each needs its own isolated working directory — and worktrees provide exactly that.

Agent parallelism — give Agent A a worktree on feature/auth and Agent B a worktree on feature/dashboard
No conflicts — each agent has its own file system space; no race conditions on file writes
Shared history — all worktrees share the same Git object store, so commits are visible across all of them
Tools are adopting it — Claude Code, Codex, and other AI agents are adding native worktree support

The pattern is clear: worktrees are becoming the standard infrastructure for multi-agent development, just as branches became standard for multi-developer workflows.

03

How Worktrees Work

4:00

A worktree is a linked working directory that shares the .git object store with the main repository. Instead of cloning the repo multiple times (which duplicates all objects), worktrees create lightweight checkouts that reference the same underlying data.

# Your repo structure with worktrees:
my-project/              # main worktree (usually 'main' branch)
├── .git/                # the shared object store
├── src/
└── ...

../my-project-feature-a/ # linked worktree (feature/auth branch)
├── .git                 # ← file, not directory! Points to main .git
├── src/
└── ...

../my-project-feature-b/ # linked worktree (feature/dashboard branch)
├── .git                 # ← also a pointer file
├── src/
└── ...
        

Key constraint: each branch can only be checked out in one worktree at a time. You can't have two worktrees both on main. This prevents ambiguity about which working directory reflects a branch's state.

04

Practical Setup

7:00

Creating and managing worktrees is simple — it's built into Git:

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

# Create a worktree with a new branch
git worktree add -b feature/dashboard ../my-project-feature-b

# List all worktrees
git worktree list
# /home/user/my-project              abc1234 [main]
# /home/user/my-project-feature-a    def5678 [feature/auth]
# /home/user/my-project-feature-b    ghi9012 [feature/dashboard]

# Remove a worktree when done
git worktree remove ../my-project-feature-a

# Prune stale worktree references
git worktree prune
        

Each worktree gets its own node_modules, build cache, and running processes. This isolation is what makes parallel agent work possible — no file system conflicts.

05

Multiple Agents in Parallel

10:00

Here's the workflow that brings it all together — running multiple AI agents on different features simultaneously:

# 1. Create worktrees for each agent
git worktree add -b feature/auth ../project-auth
git worktree add -b feature/dashboard ../project-dashboard

# 2. In tmux pane 1: run Agent A in the auth worktree
cd ../project-auth
claude "Implement OAuth2 login flow"

# 3. In tmux pane 2: run Agent B in the dashboard worktree
cd ../project-dashboard
codex "Build the analytics dashboard component"

# 4. Both agents work simultaneously, no conflicts
# 5. When done, merge both branches into main
        

This pattern combines worktrees for filesystem isolation with tmux for session persistence. Each agent gets its own branch, its own directory, and its own tmux pane. They share the Git history but never step on each other's files.

"Worktrees + tmux is the multi-agent development stack. Each agent gets a branch, a directory, and a pane. You orchestrate from the outside."

06

Best Practices

14:00

After working with worktrees extensively, here are the patterns that work best:

Naming convention — use ../project-feature-name as the worktree path to keep things organized alongside the main repo
Keep main clean — use the main worktree only for reviewing PRs and merging. Do all active work in linked worktrees.
Clean up after merge — always git worktree remove after merging a feature branch. Don't let stale worktrees accumulate.
Separate node_modules — each worktree needs its own npm install. Consider using pnpm with shared content-addressable storage to save disk space.
One branch per worktree — Git enforces this, but it's also a good mental model. Think of worktrees as "active workspaces."
Bare repo pattern — for maximum flexibility, clone with --bare and create all working directories as worktrees.

# Bare repo pattern (advanced)
git clone --bare git@github.com:user/project.git project.git
cd project.git

# Create worktrees for each branch you want to work on
git worktree add ../project-main main
git worktree add ../project-feature feature/new-thing
        

✦ Key Takeaways

1 Git worktrees let you check out multiple branches simultaneously in separate directories, sharing a single .git object store.

2 They solve the AI agent parallelism problem — each agent gets its own worktree and branch, eliminating file system conflicts.

3 Worktrees are lightweight — no repo duplication. Each linked worktree is just a checkout pointing at the shared object store.

4 Combined with tmux, worktrees create the ideal multi-agent stack: each agent has a branch, a directory, and a persistent terminal pane.

5 Best practice: use the bare repo pattern for maximum flexibility, clean up worktrees after merging, and use consistent naming conventions.