Git Worktrees: The Essential Tool for AI Development in 2025

Revolutionizing AI Development with Git Worktrees

Imagine working on a feature branch with Claude Code, an AI agent that analyzes your code to rewrite the authentication system. You're making good progress when suddenly, a Slack message interrupts you: production is down, and an urgent fix is needed on the main branch. In a traditional workflow, this would force you to set aside your changes, switch branches, and lose all the context that your AI agent had built. You would then need to fix the bug, push the changes, and return to your original task, spending time reorienting the agent on what it was doing.

The problems become even more complicated if you are running two agents simultaneously in the same directory. Imagine two agents modifying the package.json file at the same time, generating changes to the same files. The second agent could silently overwrite the first agent's changes, without warning or error, leading to corrupted work that you would only discover an hour later when the tests fail inexplicably.

Git worktrees eliminate this class of problems. Although they are not a new invention — this feature has been in Git since version 2.5, released in 2015 — the wave of AI coding in 2025–2026 has made them essential. A single .git directory, multiple working directories, each on its own branch, each invisible to the others. Each AI agent gets its own isolated workspace. The fix gets its own workspace. Nothing overlaps.

According to recent statistics, 51% of professional developers now use AI tools daily in their work. However, only 17% of them believe these tools have actually improved collaboration within their teams. This significant gap is not due to a shortcoming of the tools themselves, but rather an infrastructure issue. Teams have adopted these AI agents without putting in place an adequate workflow layer. This guide aims to bridge that gap.

Understanding Git Worktrees

A standard Git repository has a single working directory — the folder where your files reside and where you modify the code. To work on another branch, you need to switch to it, which changes all the files in that directory to match the branch. If you have uncommitted work, you must first stash it. If your AI agent is working, you interrupt it.

Git worktrees break this constraint. A worktree is a separate directory checked out from the same repository. You can have as many as you need, each on its own branch, all coexisting simultaneously on your filesystem.

• my-project/ ← main working directory (branch: main)
• my-project-feat-auth/ ← linked worktree (branch: feat/auth)
• my-project-feat-api/ ← linked worktree (branch: feat/api)
• my-project-hotfix-login/ ← linked worktree (branch: hotfix/login)

All these directories share the same .git folder. They share the history, objects, and commits. But each has its own checked-out files, its own index, and its own working state. An agent modifying files in my-project-feat-auth/ cannot see or touch anything in my-project-feat-api/. These are physically separate directories that share a Git backend.

Why is this preferable to multiple clones? The naive alternative to worktrees is to clone the repository twice and work in different clone directories. This works, but it has real costs: you duplicate the entire repository on disk, the Git history is not shared between clones, commits in one clone are not immediately visible in another, and there is no coordination between them at the Git level. With worktrees, you clone once. Each additional worktree only adds the cost of the checked-out files, not another copy of the complete history.

The seven commands that cover everything you need to manage worktrees:

• git worktree add <path> -b <branch> : Creates a new worktree on a new branch.
• git worktree add <path> <existing-branch> : Checks out an existing branch into a new worktree.
• git worktree list : Displays all active worktrees with their branches and commit hashes.
• git worktree lock <path> : Prevents a worktree from being deleted (useful while an agent is running).
• git worktree unlock <path> : Releases the lock.
• git worktree remove <path> : Cleans up a worktree (the branch is preserved).
• git worktree prune : Cleans up metadata for worktrees that have been manually deleted.

This is the complete set of commands. Everything else in this article is a workflow built on these seven commands.

Prerequisites: Git 2.5 or higher. Run git --version to check. Any modern system (macOS, Linux, Windows with WSL or Git Bash) comes with a version higher than 2.5.

Step 1: Start from a Clean Repository

Worktrees work best when your main branch is clean. Commit or stash any ongoing work before creating your first worktree.

Check that you have a clean working directory

If you have uncommitted work, commit it:

git add . && git commit -m "checkpoint: work in progress"

Step 2: Create Your First Worktree

Create a new worktree at ../myapp-feat-auth on a new branch feat/auth. Replace "myapp" with your project name and "feat/auth" with your branch name:

git worktree add -b feat/auth ../myapp-feat-auth main

Verify it has been created

git worktree list

You should see output like this:

/home/user/myapp            abc1234 [main]
/home/user/myapp-feat-auth  abc1234 [feat/auth]

Both directories exist. Both contain the same files from the main branch. From this point on, any changes you make in myapp-feat-auth/ remain on feat/auth and are completely isolated from main.

Step 3: Set Up the Environment in the New Worktree

This is the step that most tutorials overlook. A worktree is a new working directory. It does not automatically have your .env file, your installed node_modules, or your Python virtual environment. You need to set them up explicitly.

cd ../myapp-feat-auth

• Copy the environment files that are ignored by Git. Files like .env, .env.local, and similar are not tracked in Git — they will not automatically appear in the new worktree:

cp ../myapp/.env .env
cp ../myapp/.env.local .env.local 2>/dev/null || true

• Node.js project: install dependencies. Each worktree is an independent working directory — the parent’s node_modules do not transfer.
• Python project: create and activate a virtual environment:

python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Step 4: Verify that the Worktree is Isolated

From inside the new worktree:

• It should display: feat/auth
• Make a test change:

echo "// test" >> test-isolation.js

• This change should only show in this worktree. Switch to the main directory and check that it is unaffected:

ls test-isolation.js 2>/dev/null || echo "Not here -- isolation confirmed"

That's all you need to get started. The worktree is active. Any agent you open in this directory operates solely on feat/auth.

A Real-World Case Study

The clearest documented example of using Git worktrees for AI-driven parallel development comes from the Microsoft Global Hackathon 2025.

Tamir Dresher, a technical lead, faced a problem that everyone encountering AI agents eventually runs into: too many features, too little time, and no way to work on more than one thing at a time without constant context switching. Creating multiple clones of the repository was cumbersome. Switching branches destroyed the context of the AI agent. Something had to change.

The solution was to use Git worktrees to create what Dresher described as a virtual AI development team. Each feature got its own worktree. Each worktree got its own VS Code window. Each window ran its own AI agent. Dresher's role evolved from developer to technical lead: defining tasks, reviewing results, guiding agents that were stuck, and merging completed work.

The setup looked like this:

• myapp/ ← main window: coordination and reviews
• myapp-feat-authentication/ ← Agent 1: implementing the OAuth2 flow
• myapp-feat-api-endpoints/ ← Agent 2: building REST endpoints
• myapp-bugfix-login-crash/ ← Agent 3: fixing a production bug

Each VS Code window was completely independent. Language servers, linters, and test runners operated per window. The agents never touched each other's files. When Agent 1 finished, Dresher reviewed the diff, approved it, and opened a pull request (PR) from that branch — the same workflow as reviewing a PR from a human engineer.

Three concrete benefits that Dresher documented during the hackathon:

• No loss of context. Each AI agent maintained the complete context of its specific task. Switching from one feature to another meant changing VS Code windows, not branches, no stashing, no agent restarts. The agent's understanding of what it was building remained intact.

• Different tools for different jobs. Since each window was independent, Dresher ran Roo in one window for rapid feature development and GitHub Copilot with Visual Studio in another for debugging complex issues. Mixing tools between tasks was trivial.

• Clean branch management. If a feature needed to be abandoned, closing the window and deleting the worktree took ten seconds. Other agents were unaffected.

The model that emerged from this hackathon is now a documented best practice in the AI coding community.

Running Parallel AI Agents with Worktrees

The mechanics of the complete parallel workflow involve four steps: setting up worktrees, giving each agent its context, running the agents, and regularly checkpointing.

Step 1: Worktree Creation Script

Do not create worktrees manually each time. A script ensures that each worktree gets the same configuration — environment files, dependency installation, and a clean starting point.

Prerequisites: Git 2.5+, Bash (macOS/Linux/WSL)

How to run: Save as create-worktree.sh in the root of your project, run chmod +x create-worktree.sh, then ./create-worktree.sh feat/auth-redesign main.

#!/usr/bin/env bash
# create-worktree.sh
# Creates an isolated worktree for an AI agent task
# Usage: ./create-worktree.sh  [base-branch]
# Example: ./create-worktree.sh feat/auth-redesign main
set -euo pipefail
BRANCH="${1:?Usage: $0  [base-branch]}"
BASE="${2:-main}"
REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
# Replace slashes in