Git Worktrees for AI Coding Agents: A Complete Guide

You start two Claude Code sessions on the same project. One is refactoring the API layer. The other is updating the frontend components. Both try to edit package.json at the same time. One session’s changes silently overwrite the other’s. You don’t notice until tests fail an hour later.

This is the fundamental problem with running parallel AI coding agents: they share a working directory. Git worktrees solve it completely.

What Are Git Worktrees?

A git worktree is a separate working directory linked to the same repository. Each worktree has its own branch, its own files, and its own index — but they all share the same .git history.

# Your main checkout
~/projects/myapp/          ← branch: main

# A worktree for feature work
~/projects/myapp-auth/     ← branch: feat/auth-refactor

# Another worktree
~/projects/myapp-api/      ← branch: feat/api-endpoint

Each directory is a fully independent working copy. Changes in one don’t affect the others. But they share commit history, so merging is straightforward.

Why Worktrees Matter for AI Agents

Without worktrees, parallel AI sessions have three problems:

File conflicts: Two agents editing the same file simultaneously produces corrupted state
Dirty working directory: Agent A’s uncommitted changes confuse Agent B’s context
Branch confusion: Both agents think they’re on the same branch and step on each other

With worktrees, each agent gets an isolated environment. They can edit any file without conflict. They each have their own branch. When they’re done, you merge their branches normally.

Setting Up Worktrees

Create a Worktree

cd ~/projects/myapp

# Create a new worktree with a new branch
git worktree add ../myapp-auth -b feat/auth-refactor

# Create a worktree from an existing branch
git worktree add ../myapp-api feat/api-endpoint

Run an Agent in a Worktree

cd ~/projects/myapp-auth
claude    # or codex

Each agent session now operates in complete isolation.

List Active Worktrees

git worktree list

Merge and Clean Up

cd ~/projects/myapp
git merge feat/auth-refactor
git worktree remove ../myapp-auth

Workflow Patterns

Pattern 1: Feature Branches

Each agent session gets its own feature branch in its own worktree.

main (your review/merge point)
├── feat/auth-refactor    → Claude Code session 1
├── feat/api-endpoint     → Codex session 2
└── feat/test-coverage    → Claude Code session 3

When to use: Independent features that touch different parts of the codebase.

Pattern 2: Stacked Changes

For sequential work where each task builds on the previous one.

main
└── feat/step-1-models    → Agent session 1 (finish first)
    └── feat/step-2-api   → Agent session 2 (starts after step 1)

Pattern 3: Parallel Attempts

Run multiple agents on the same task to compare approaches.

main
├── attempt/auth-v1-jwt       → Claude Code (JWT approach)
├── attempt/auth-v2-session   → Codex (session-based approach)

Review all approaches, pick the winner, merge it, delete the rest.

Pattern 4: Fix + Feature

Keep your main branch clean for hotfixes while feature work continues in worktrees.

Common Gotchas

Shared Node Modules

Each worktree needs its own node_modules. After creating a worktree:

cd ~/projects/myapp-auth
npm install

Lock File Conflicts

If multiple agents update dependencies, their lock files will conflict at merge time. Avoid dependency changes in parallel sessions.

Branch Locking

A branch can only be checked out in one worktree at a time. Always create a new branch for each worktree.

Tools That Automate Worktrees

agentree

A CLI tool that automates worktree creation for AI agent sessions. Run agentree start and it creates a worktree, starts your agent, and cleans up when done.

Claude Code (Built-in)

Claude Code’s --worktree flag automatically creates an isolated worktree for the session.

Nimbalyst

Nimbalyst can create a git worktree automatically for every session. When you start a new Claude Code or Codex session, it can run in its own worktree with its own branch. When the session completes, you review the diff and merge from within the app. No manual worktree management needed.

Manual Script

agent-session() {
  local name=$1
  local branch="agent/$name-$(date +%s)"
  git worktree add "../$(basename $(pwd))-$name" -b "$branch"
  cd "../$(basename $(pwd))-$name"
  echo "Worktree ready at $(pwd) on branch $branch"
}

How Many Parallel Agents?

Sessions	Review Load	Recommendation
1–2	Light	Anyone can manage this
3–4	Moderate	Sweet spot for most developers
5–6	Heavy	Needs visual management tools
7+	Overload	Scale back

The bottleneck isn’t running agents — it’s reviewing their output.

Verdict

Git worktrees are the single most important technique for parallel AI agent development. They solve the file conflict problem completely, they’re built into git, and they make merging straightforward.

If you’re running more than one AI agent session at a time and you’re not using worktrees, set them up. The 5-minute setup saves hours of debugging.