Skip to main content

Using Git Worktrees to Parallelize AI Agents

Using Git Worktrees to Parallelize AI Agents

🌳 Claude Code Skill Available: The git-worktree skill in SkillBox automates worktree creation and management for AI agents. Install with npx skills add antjanus/skillbox and invoke with /git-worktree to streamline your parallel development workflow. Read the announcement.

One of the difficult parts of working agentic coding tools is how long it takes them to do anything. In general, I’ve found that AI tools take longer than hand-writing code. This may come as a surprise to some but to many, this is the reality we’re living in.

The thing is that while AI tooling may take longer to accomplish a task, you, as a developer, are freed from coding. This lends to the idea of executing multiple agents at once. After all, you can parallelize agentic coding tools, you can’t parallelize yourself.

I’m, for example, currently running five separate agents. I’m generally checking on progress, steering each agent toward the right solution, and abstaining from coding myself. So while a bugfix may take 2 hours instead of 1 hour by hand, I can simultaneously debug ten different issues and they’ll still all take 2 hours total but now I’m at 10+ hours of hand-coding to match that performance.

But here’s the issue. While my machine can easily spawn 5, 10, 20, or 30 different agents, and while Anthropic has no issue crunching the data my agents send it, it can be difficult to coordinate all of that work. Especially if majority of that work is in one repo. That’s where Git Worktrees come in.

Note: I wonder if agentic AI will influence the microservices vs. monolith discussion given that agentic AI works better in smaller environments (microservices)

What Are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to the same Git repository. Think of it like having multiple browser tabs open to the same website, each showing different content. Each worktree can be on a different branch, but they all share the same Git history and object database.

Gone are the days of having “project-name-1”, “project-name-2”, “project-name-3”, etc. copies of a repo just so you can work on two things separately. I know some people used tools that took advantage of git worktrees before coding AI became a thing; however, agentic coding tools really pushed git worktrees into popularity.

Check out my article on Demystifying Git Worktrees for a beginner-friendly introduction with practical examples and commands.

Traditional workflow:

git checkout -b feature-a
# work on feature-a
git checkout -b feature-b
# work on feature-b

Worktree workflow:

git worktree add ../feature-a -b feature-a
git worktree add ../feature-b -b feature-b

Result:

~/project-main/ (main branch)
~/feature-a/   (feature-a branch)
~/feature-b/   (feature-b branch)

Why Git Worktrees Matter for AI Agents

Git Worktrees enable AI agents (such as Claude Code, OpenCode, or Gemini) to work independently and in parallel on the same project. This has quite a few advantages:

Parallel Execution

Multiple instances of agentic AI can work at the same time. This means that you can have one agent developing a new feature and another doing a bugfix – at the same time.

The traditional approach forces you to work with AI agents serially – complete one task, then start another. This creates a productivity bottleneck. With worktrees, you can embrace true parallelization. (For more on why this matters, see All In On AI which discusses the context-switching costs of serial AI workflows.)

No Context Pollution

Each agent has a clean, isolated file space. Changes in one worktree don’t affect another until you explicitly merge them.

This also allows agents to create scratch files without messing with each other. For instance, I have a Claude Code SKILL.md that creates a session_progress.md file to keep track of progress. Each worktree can have its own separate temporary files, session progress, etc.

Experiment Safely

Test different approaches in parallel without affecting your main work. Let one agent try approach A while another tries approach B.

Review Without Switching

With multiple agents working at the same time, it’s much easier to switch between them and compare their outputs.

Git Worktree Basics

Creating a Worktree

# Create a new worktree with a new branch
git worktree add ../project-feature-name feature-name

# Create a worktree from an existing branch
git worktree add ../project-bugfix existing-branch-name

# Create a worktree from main
git worktree add ../project-experiment -b experiment-branch

Managing Worktrees

# List all worktrees
git worktree list

# Output example:
# /Users/you/project-main      abc123 [main]
# /Users/you/project-feature-a def456 [feature-a]
# /Users/you/project-bugfix    ghi789 [bugfix]

# Remove a worktree (must commit or stash changes first)
git worktree remove ../project-feature-name

# Prune deleted worktrees from the list
git worktree prune

Worktree Limitations

  • You cannot check out the same branch in multiple worktrees
  • Each worktree takes up disk space
  • Git operations affect all worktrees (fetch, pull, push)

Note: Your project needs to be setup to be able to run multiple instances on the same machine. So if you’re using your local Postgres database for development, you’d need a separate one per worktree. This isn’t an issue with a fully dockerized setup

Setting Up Your Workspace for AI

Directory Structure

Organize worktrees as sibling directories:

~/projects/
  ├── my-app/              # Main worktree (main branch)
  ├── my-app-feature-auth/ # Feature development
  ├── my-app-bugfix-123/   # Bug fix
  └── my-app-refactor/     # Experimental refactor

Shell Configuration (Optional)

This is optional but highly recommended for tracking which worktree you’re in. Update your prompt to show the worktree name by adding to ~/.zshrc:

# Add worktree name to prompt
parse_git_worktree() {
  local worktree=$(basename "$PWD")
  if [[ "$worktree" != "$(basename $(git rev-parse --git-dir 2>/dev/null))" ]]; then
    echo " [$worktree]"
  fi
}

# Add to your PS1/PROMPT
PROMPT='%~ $(parse_git_worktree) %# '

While there are oh-my-zsh plugins for managing worktrees (like trthomps/git-worktree-zsh-plugin or jspears/worktree), none currently provide prompt display functionality. The custom function above is the recommended solution. You can combine both approaches:

# In ~/.zshrc:

# Add management plugin for worktree commands and aliases
plugins=(git worktree)  # or git-worktree if installed

# Add custom prompt function for worktree display
parse_git_worktree() {
  local worktree=$(basename "$PWD")
  if [[ "$worktree" != "$(basename $(git rev-parse --git-dir 2>/dev/null))" ]]; then
    echo " [$worktree]"
  fi
}

PROMPT='%~ $(parse_git_worktree) %# '

This gives you both convenient worktree management commands and visual feedback in your prompt.

Using Git Worktrees with Claude Code

Combining git worktrees with Claude Code creates a powerful parallel development workflow. For general Claude Code best practices, see Best Practices for AI-Assisted Coding with Claude Code.

Example Workflow

Setup:

cd ~/projects/my-app

# Create worktrees for parallel work
git worktree add ../my-app-auth -b feature/auth-refactor
git worktree add ../my-app-api -b feature/new-endpoint
git worktree add ../my-app-bug -b bugfix/memory-leak

Terminal 1: Authentication refactor

cd ~/projects/my-app-auth
# setup project
npm install

# run agent
claude
# Agent: "Refactor authentication to use JWT tokens"

Terminal 2: New API endpoint

cd ~/projects/my-app-api
# setup project
npm install

# run agent
claude
# Agent: "Add POST /api/users endpoint with validation"

Terminal 3: Bug fix

cd ~/projects/my-app-bug
# setup project
npm install

# run agent
claude
# Agent: "Fix memory leak in WebSocket connection handler"

All three agents work simultaneously without conflicts.

Claude Code Git Worktree Skill

One great way to help out with Git Worktrees is by utilizing a Claude Code Git Worktree skill.

With my personal skill, you can just do:

/git-worktree

and then ask it to create a new tree. If you want to supercharge your development, add documentation for how Git Worktrees should work in your project in your CLAUDE.md or AGENTS.md files.

Here’s an example of how to structure that:

## Starting development

When starting development, create a new Git Worktree utilizing the git-worktree skill. 

Follow the following naming convention for branches:

- prefix with `feat/`, `fix/`, or `release/` depending on the work being done
- follow with Jira ticket number. eg. `JIRA-000`
- suffix with a quick description of work

Example PR name: `feat/JIRA-123-add-auth`

Follow the following naming conventions for worktrees:

- prefix with project name. eg. `project-name-`
- follow with Jira ticket number, eg. `JIRA-000`
- suffix with PR description

Example worktree name: `project-name-JIRA-000-add-auth`

Tools with Built-In Support

AI Tools with Native Worktree Support

Claude Code:

  • Automatically detects worktree context
  • Git operations scoped to current worktree
  • No special configuration needed

Cursor:

  • Per-worktree agent sessions
  • Automatic branch detection
  • Parallel agent support

Superset:

  • built-in worktree support
  • built-in support for agentic tools

Third-Party Integrations

Git GUI tools:

  • GitKraken: Visual worktree management
  • Sourcetree: Worktree support in recent versions
  • Tower: Built-in worktree operations

Common Pitfalls and Solutions

Handling Dependencies

Problem: Installing dependencies in each worktree is slow and wasteful.

Solutions:

  • Use pnpm (shares packages via hard links)
  • Symlink dependency directories
  • Use Docker containers with mounted volumes

Cleaning Up Old Worktrees

Problem: Forgotten worktrees clutter your filesystem.

Solution:

# List merged branches in worktrees
git worktree list

# Remove if merged
git worktree remove path/to/worktree

# Force remove if needed (be careful!)
git worktree remove --force path/to/worktree

When NOT to Use Worktrees

Simple, Quick Changes

If you’re making a one-line fix or quick update, just use git checkout. The overhead isn’t worth it.

Projects with Large Binary Dependencies

If your project has gigabytes of binary assets or dependencies, duplicating them across worktrees becomes problematic.

When You Need Frequent Merging

If you’re constantly merging between branches, the context switching of moving between worktree directories might be more annoying than helpful.

So what now?

Git worktrees transform AI agent workflows from serial to parallel. Instead of waiting for one agent to finish before starting another, you can run multiple agents simultaneously, each in their own isolated workspace.

The setup takes minutes, but the productivity gains compound over time. No more context switching, no more file conflicts, no more waiting.

Next steps:

  1. Review Demystifying Git Worktrees if you’re new to the concept
  2. Create your first worktree for an upcoming feature
  3. Set up your shell prompt to show worktree context
  4. Try running two Claude Code agents in parallel on different features
  5. Read Best Practices for AI-Assisted Coding to optimize your workflow

Your future self (and your AI agents) will thank you.

Resources: