You spin up three AI agents to work on three independent features. They all clone the same repo. They all start editing the same files. You’ve created a merge conflict factory.
Git worktrees solve this. And once you understand them, you’ll wonder how you ran parallel agent tasks without them.
What a Worktree Actually Is
A git worktree is a second (or third, or tenth) working directory attached to an existing repository.
Each worktree checks out a different branch. Each has its own HEAD, its own index, its own uncommitted state. But they all share the same .git object store — the same history, the same refs, the same hooks, the same config.
This is fundamentally different from cloning the repo multiple times:
| Multiple Clones | Worktrees | |
|---|---|---|
| Disk usage | Full copy per clone | Shared object store |
| Branch switching | Manual sync needed | Always in sync |
| Same branch in two places | Possible (dangerous) | Blocked by Git |
| Hooks and config | Duplicated | Shared |
One .git, many working directories. That’s it.
The Problem Worktrees Were Built For
The canonical use case: you’re deep in a feature branch when a prod bug lands.
Old workflow:
- Stash your changes
- Switch to main
- Create a hotfix branch
- Fix the bug
- Commit, deploy
- Switch back to your feature
- Pop the stash
- Hope nothing broke
With worktrees:
git worktree add -b fix/prod-crash ../hotfix main
cd ../hotfix
# fix it, commit it
cd ../your-feature
# still exactly where you left it
git worktree remove ../hotfix
No stashing. No context switching. Your feature branch never moved.
Core Commands
Everything you need:
# Add a worktree for an existing branch
git worktree add ../feature-auth feature/auth
# Add a worktree and create a new branch from main
git worktree add -b fix/urgent-bug ../hotfix main
# List all active worktrees
git worktree list
# Remove a worktree when done
git worktree remove ../hotfix
# Clean stale metadata (after deleting a worktree dir manually)
git worktree prune
The path you pass to add becomes the new working directory. The branch is checked out there. That’s the whole model.
The Bare Clone Setup
If you’re using worktrees heavily — or building a system where agents always work in worktrees — set up your repo as a bare clone from the start:
git clone --bare git@github.com:user/repo.git .bare
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch
Now your root directory contains no working files — just the git database. Every branch lives in its own worktree subdirectory. Clean, explicit, nothing implicit.
Why AI Agents Need Worktrees
Here’s where it gets interesting.
When you run multiple AI agents on the same codebase in parallel, you have a coordination problem. Agents don’t communicate. They don’t know what the other is touching. If two agents edit the same file, you get conflicts. If they share a branch, one agent’s commit can invalidate the other’s entire working context.
Worktrees solve this at the filesystem level.
Each agent gets its own worktree → its own branch → its own isolated directory.
No file-level conflicts. No shared HEAD state. No coordination required between agents.
This isn’t theoretical. OpenAI’s Codex app (launched February 2026) auto-generates a separate worktree for every parallel agent thread. The numbers from a real Node.js monorepo (~800 files):
| Configuration | Wall-clock time |
|---|---|
| Single agent | 42 min |
| 3 parallel agents | 18 min |
| 5 parallel agents | 14 min |
That’s a 3× speedup just from running agents in parallel — with zero merge conflicts when the tasks stayed independent.
The Pattern: Agent Worktree Lifecycle
The basic workflow for any AI agent system using worktrees:
# 1. Create an isolated worktree for the task
git worktree add ../agent-auth-feature -b agent/auth-feature main
# 2. Agent runs in that directory
# Makes changes, commits locally
# 3. Human reviews the diff
git -C ../agent-auth-feature diff main
# 4. Merge if good, discard if not
git merge agent/auth-feature # or just delete it
# 5. Clean up
git worktree remove ../agent-auth-feature
git worktree prune
The agent operates with full autonomy inside its worktree. Review happens at the boundary. This is the same mental model as a PR — except it’s local, instant, and doesn’t require a remote.
The #1 Gotcha: Dependencies Don’t Exist
A new worktree only contains files tracked by git.
node_modules? Not tracked. .env? Not tracked. dist? Not tracked. .venv? Not tracked.
If your agent needs to run the app, install dependencies, or access environment variables, the worktree will be broken out of the box.
The fix is a setup script that runs automatically when a new worktree is created:
#!/bin/bash
# .claude/setup.sh or .codex/setup.sh
set -e
cd "$WORKTREE_PATH"
npm ci --prefer-offline
cp "../.env" ".env"
echo "Worktree ready"
Run it as part of the agent’s initialization step. This is non-negotiable for any real project.
What “One Branch, One Worktree” Actually Means
Git enforces a hard rule: you can’t check out the same branch in two worktrees simultaneously.
This is a safety feature, not a limitation. It prevents two agents from silently working on the same branch and overwriting each other’s commits.
The practical implication: every agent task needs its own branch. You can name them however you want (agent/task-id, ai/feature-name, codex/thread-3). The naming scheme doesn’t matter. The isolation does.
Claude Code’s Native Worktree Support
Claude Code has built-in worktree support. When you spawn a subagent with isolation: "worktree", it automatically:
- Creates a new git worktree on a fresh branch
- Runs the agent inside that isolated directory
- Cleans up the worktree if no changes were made
- Returns the worktree path and branch name if changes exist
This means you can run parallel Claude Code agents on the same repo without writing any coordination logic. The isolation is handled at the harness level.
When to Use Worktrees (and When Not To)
Use worktrees when:
- Running multiple AI agents on the same codebase in parallel
- You need an emergency fix without disturbing in-progress work
- You want to review a branch without checking it out in your main workspace
- Running CI-style checks on a different branch while you keep working
Don’t use worktrees when:
- Tasks share files — agents writing to the same module will conflict at merge time; worktrees just delay the problem
- You need submodules (support is incomplete)
- The task is short enough that branch switching is fine
The key question: are the tasks genuinely independent? If yes, worktrees give you free parallelism. If no, no amount of isolation will prevent the conflict — you need to sequence the work instead.
The Emerging Standard
The pattern is converging across tools.
Codex uses it for parallel agent threads. Claude Code supports it natively. Linear’s “Linear for Agents” (May 2025) orchestrates issue-to-worktree workflows where each ticket becomes a worktree and agents receive their isolated directories automatically.
The model is: issue tracker as orchestration layer, worktree as isolation boundary, diff review as the human checkpoint.
Git worktrees were designed for developers doing emergency hotfixes. They turned out to be exactly what AI agent parallelism needed — a mechanism for multiple actors to work on the same codebase without coordinating, each in their own sandbox, each producing a clean reviewable diff.
You already had the primitive. The agents just gave you a reason to use it.
Quick Reference
# Create worktree on new branch from main
git worktree add -b <branch> <path> main
# Create worktree for existing branch
git worktree add <path> <branch>
# List all worktrees
git worktree list
# Remove worktree
git worktree remove <path>
# Clean stale worktree metadata
git worktree prune
# Lock worktree (prevent pruning)
git worktree lock --reason "active agent" <path>
# Check a worktree without entering it
git -C <path> status