Git Worktrees and AI Agents: The Parallel Development Superpower

Context switching is the silent killer of developer productivity. Here is how Git Worktrees and AI agents solve it.

Stop stashing and switching. Learn how to combine Git Worktrees with AI agents to eliminate context switching and unlock true parallel development.

Context switching is the silent killer of developer productivity. You are deep in a complex refactor, holding the entire mental model of a module in your head, and a critical bug report lands on your desk.

The traditional dance is painful: git stash, switch branches, npm install (because dependencies changed), fix the bug, switch back, git stash pop, and hope for no conflicts. It breaks your flow, wipes your mental RAM, and makes it significantly harder to regain your original focus.

There is a better way. By combining Git Worktrees with AI Agents, you can unlock true parallel development.

Prerequisites

  • Git 2.5+: Worktrees have been around since 2015, but they are often overlooked.
  • VS Code: Or any editor that supports multi-root workspaces or separate windows.
  • An AI Assistant: GitHub Copilot, Claude Code, or similar.

The Deep Dive: Git Worktrees 101

Most developers are used to a single working directory. You have one folder, one .git folder, and one active branch. To work on something else, you must mutate the state of that single directory.

Git Worktrees change the physics of your repository. They allow you to check out multiple branches at once in separate directories, all linked to the same underlying .git history.

Multiple branches concept

Core Commands

Creating a worktree is straightforward. You specify the path and the branch you want to check out.

# Create a new worktree for a hotfix
git worktree add -b hotfix/login-bug ../my-app-hotfix main

# List your active worktrees
git worktree list
# /Users/dev/my-app         (main)
# /Users/dev/my-app-hotfix  (hotfix/login-bug)

You now have two folders. You can run the app in my-app while fixing the bug in my-app-hotfix. No stashing. No context loss. No fighting over the node_modules folder.

When you are done, cleanup is just as easy:

# Remove the worktree
git worktree remove ../my-app-hotfix

# Prune stale references if you deleted the folder manually
git worktree prune

Why This Matters for AI Agents

2025 is the year of the AI Agent. Tools like GitHub Copilot Agents and Claude Code are no longer just autocomplete; they are autonomous workers capable of executing complex tasks. But they need space.

If you ask an agent to “refactor the auth module” in your current window, it hijacks your environment. You can’t work while it works. It changes files, runs tests, and consumes your terminal.

The Agent HQ Concept

Think of your main worktree as “Agent HQ”. This is where you orchestrate tasks. When you have a heavy task for an AI agent, you don’t block your main thread. Instead, you delegate it to a background agent running in a dedicated worktree.

By combining Worktrees with Agents, you create isolated sandboxes. You can spin up a worktree, assign an agent to it, and let it work in the background while you continue your primary task in your main window.

AI Agents working in parallel

A Pragmatic Workflow: Mindset-Based Worktrees

Instead of creating a worktree for every single feature (which clutters your disk), adopt a mindset-based approach. Create persistent worktrees for specific types of work:

  1. work: Your main active development.
  2. review: A clean slot for checking out PRs.
  3. scratch: A playground for AI experiments or quick prototypes.
# Setup persistent worktrees
git worktree add ../my-app-review main
git worktree add ../my-app-scratch main

This structure keeps your mental model clean. When you need to review code, you go to the review folder. When you need to experiment, you go to scratch.

Automating the Flow

To make this seamless, you can use simple scripts to “teleport” these persistent folders to the branch you need. Here is a pragmatic sync-worktree.sh script (inspired by Daksh Pareek):

#!/bin/bash
# Usage: ./sync-worktree.sh review pull/320/head
FOLDER=$1
TARGET=$2

cd "$FOLDER" || exit
git fetch origin
# Switch using detached HEAD so we don't lock the branch name
git checkout --detach "$TARGET"

# Re-link .env files if they don't exist
# Optional: adjust the ../shared-config/core.env path below to wherever you keep your shared env file.

# Use the package manager you prefer (default: npm)
PKG_MANAGER="${PKG_MANAGER:-npm}"
$PKG_MANAGER install
ln -sf ../shared-config/core.env .env

With this, switching contexts becomes a single command: ./sync-worktree.sh review pr-branch-name.

The “Boss Scenario” Solved

Let’s revisit the interruption scenario with this new workflow.

  1. The Request: “Production is down, fix the login timeout.”
  2. The Action: Do not touch your current work. Open your scratch worktree in a new terminal or VS Code window.
  3. The Fix:
    cd ../my-app-scratch
git fetch origin
git checkout -b hotfix/timeout-fix origin/main
# Fix the bug, push, and create PR
  4. The Return: Close the terminal/window. You are back in your main worktree, exactly where you left off. Your local server is still running. Your variables are still in memory.

VS Code Integration

VS Code handles this natively. You can open each worktree as a separate window, effectively giving you multiple monitors for your codebase.

  • Window 1 (Main): Deep work on Feature A.
  • Window 2 (Agent): Copilot Agent implementing unit tests in the scratch worktree.
  • Window 3 (Review): Reviewing a teammate’s PR in the review worktree.

VS Code Multi-root workspace

Summary

Git Worktrees are not new, but they are the missing link for effective AI-assisted development. They provide the isolation that autonomous agents require and the context preservation that human brains need.

Start small. Next time you need to review a PR, don’t switch branches. Create a review worktree instead.

git worktree add ../review-lab main

Ultimately, it’s a pragmatic decision to separate your concerns physically on disk, not just logically in Git.

To Blog