DEV Community

Cover image for Git Worktrees for AI Coding: Run Multiple Agents in Parallel
Mashrul Haque
Mashrul Haque

Posted on • Originally published at easyappdev.com

Git Worktrees for AI Coding: Run Multiple Agents in Parallel

#git #dotnet #ai #productivity

Last Tuesday I had Claude Code fixing a pagination bug in my API layer. While it worked, I sat there. Waiting. Watching it think. For eleven minutes.

Meanwhile, three other tasks sat in my backlog: a Blazor component needed refactoring, a new endpoint needed tests, and the SCSS build pipeline had a caching issue. All independent. All blocked behind my single terminal.

I thought: I have 5 monitors and a machine that could run a small country. Why am I running one agent at a time?

Then I discovered that Claude Code shipped built-in worktree support, and everything changed. I went from sequential AI coding to running five agents in parallel, each on its own branch, none stepping on each other's files. My throughput didn't just double. It went up roughly 5x.

Here's exactly how I set it up, the .NET-specific gotchas I hit, and why I think worktrees are the single biggest productivity unlock for AI-assisted development right now.

Table of Contents

What Are Git Worktrees

A git worktree is a second (or third, or fifth) working directory linked to the same repository. Each worktree checks out a different branch, but they all share the same .git history, refs, and objects.

Think of it this way: instead of cloning your repo five times (and wasting disk space on five copies of your git history), you create five lightweight checkouts that share one .git folder.

# Your main repo
C:\code\MyApp\                    # on branch: master

# Your worktrees (separate folders, same repo)
C:\code\MyApp-worktrees\fix-pagination\    # on branch: fix/pagination
C:\code\MyApp-worktrees\add-tests\         # on branch: feature/api-tests
C:\code\MyApp-worktrees\refactor-blazor\   # on branch: refactor/blazor-grid
Enter fullscreen mode Exit fullscreen mode

Git introduced worktrees in version 2.5 (July 2015). They've been around for over a decade. Most developers have never used them because, until AI coding agents, there was rarely a reason to work on five branches simultaneously.

Now there is.

The Problem: One Repo, One Agent, One Branch

Here's the typical AI coding workflow in 2026:

  1. Open terminal. Start Claude Code (or Cursor, or Copilot).
  2. Describe a task. Watch the agent work.
  3. Wait 5-15 minutes while it reads files, writes code, runs tests.
  4. Review the changes. Commit.
  5. Start the next task.

Steps 1-4 are sequential. You're blocked. Your machine is doing maybe 10% of what it could.

"But I can just open another terminal and start a second agent."

No, you can't. Not safely. Two agents editing the same working directory is a recipe for corrupted state. Agent A writes to OrderService.cs while Agent B is reading it. Agent A runs dotnet build while Agent B is mid-refactor. Merge conflicts happen in real-time, inside your working directory, with no version control to save you.

Worktrees fix this. Each agent gets its own directory, its own branch, its own isolated workspace. They can all build, test, and modify files simultaneously without interference.

Setting Up Your First Worktree

The syntax is simple:

# Create a worktree with a new branch
git worktree add ../MyApp-worktrees/fix-pagination -b fix/pagination

# Create a worktree from an existing branch
git worktree add ../MyApp-worktrees/fix-pagination fix/pagination

# List all worktrees
git worktree list

# Remove a worktree when you're done
git worktree remove ../MyApp-worktrees/fix-pagination
Enter fullscreen mode Exit fullscreen mode

I keep my worktrees in a sibling directory to avoid cluttering the main repo:

C:\code\
├── MyApp\                        # Main working directory
└── MyApp-worktrees\              # All worktrees live here
    ├── fix-pagination\
    ├── add-tests\
    └── refactor-blazor\
Enter fullscreen mode Exit fullscreen mode

One critical rule: you cannot check out the same branch in two worktrees. Git enforces this by default. If your main directory is on master, no worktree can also be on master. You can override this with git worktree add -f, but don't. It prevents two workspaces from stomping on each other's state. The restriction is a feature, not a bug.

Running Multiple AI Agents in Parallel

Here's where it gets interesting. Once you have worktrees set up, you can launch an AI agent in each one.

With Claude Code

Claude Code has built-in worktree support with a --worktree (-w) CLI flag that starts a session in an isolated worktree automatically. You can also create worktrees manually and point Claude Code at them:

# Terminal 1: Main repo - fixing the pagination bug
cd C:\code\MyApp
claude "Fix the pagination bug in OrdersController where offset is off by one"

# Terminal 2: Worktree - adding API tests
cd C:\code\MyApp-worktrees\add-tests
claude "Add integration tests for all endpoints in OrdersController"

# Terminal 3: Worktree - refactoring Blazor component
cd C:\code\MyApp-worktrees\refactor-blazor
claude "Refactor the OrderGrid component to use virtualization"

# Terminal 4: Worktree - fixing SCSS
cd C:\code\MyApp-worktrees\fix-scss
claude "Fix the SCSS compilation caching issue in the build pipeline"

# Terminal 5: Worktree - documentation
cd C:\code\MyApp-worktrees\update-docs
claude "Update the API documentation for the Orders endpoint"
Enter fullscreen mode Exit fullscreen mode

Five terminals. Five agents. Five branches. Zero conflicts.

Claude Code also supports spawning subagents in worktrees internally using isolation: "worktree" in agent definitions, where each subagent works in isolation and the changes get merged back. Boris Cherny, Creator and Head of Claude Code at Anthropic, called worktrees his number one productivity tip — he runs 3-5 worktrees simultaneously and described it as particularly useful for "1-shotting large batch changes like codebase-wide code migrations."

With Other AI Tools

The same pattern works with any AI coding tool:

# Cursor - open each worktree as a separate workspace
code C:\code\MyApp-worktrees\fix-pagination

# GitHub Copilot CLI - run in each worktree directory
cd C:\code\MyApp-worktrees\add-tests && gh copilot suggest "..."
Enter fullscreen mode Exit fullscreen mode

The worktree is just a directory. Any tool that operates on a directory works.

The .NET Worktree Survival Guide

This is where generic worktree guides fall short. .NET projects have specific pain points that will bite you if you're not prepared.

Pain Point 1: NuGet Package Restore

Each worktree needs its own bin/ and obj/ directories. The good news: dotnet restore handles this automatically. The bad news: your first build in each worktree takes longer because it's restoring packages from scratch.

# After creating a worktree, always restore first
cd C:\code\MyApp-worktrees\fix-pagination
dotnet restore
Enter fullscreen mode Exit fullscreen mode

The NuGet global packages cache (%userprofile%\.nuget\packages on Windows, ~/.nuget/packages on Mac/Linux) is shared across all worktrees. So the packages aren't downloaded again — they're just linked. Fast enough.

Pain Point 2: Port Conflicts in launchSettings.json

This one will get you. If all your worktrees use the same launchSettings.json, they'll all try to bind to the same port. Two Kestrel instances on port 5001 means one of them crashes.

Fix it with environment variables or override the port at launch:

# In worktree terminal, override the port
dotnet run --urls "https://localhost:5011"

# Or set it via environment variable
ASPNETCORE_URLS=https://localhost:5011 dotnet run
Enter fullscreen mode Exit fullscreen mode

One gotcha: if you have Kestrel endpoints configured explicitly in appsettings.json, those override ASPNETCORE_URLS. The --urls flag is safer because it takes highest precedence.

I usually don't bother with any of this — most of the time the AI agent doesn't need to run the app, just build and test it.

Pain Point 3: User Secrets and appsettings.Development.json

User secrets are stored by UserSecretsId (set in your .csproj) under %APPDATA%\Microsoft\UserSecrets\<UserSecretsId>\secrets.json on Windows (~/.microsoft/usersecrets/ on Mac/Linux). They live outside the repo entirely. So they're shared automatically across worktrees. This is usually what you want.

appsettings.Development.json is tracked in git (or should be gitignored), so it exists in every worktree. No issues here.

Pain Point 4: Database Migrations Running in Parallel

If two agents both try to run dotnet ef database update against the same database at the same time, you'll get lock contention or worse.

My rule: only one worktree touches the database at a time. If a task involves migrations, it gets its own dedicated slot and the other agents work on code-only changes.

Or better: use a separate database per worktree for integration tests. Your docker-compose.yml can spin up isolated Postgres instances:

# docker-compose.worktree-tests.yml
services:
  db-pagination:
    image: postgres:17
    ports: ["5433:5432"]
    environment:
      POSTGRES_DB: myapp_pagination

  db-tests:
    image: postgres:17
    ports: ["5434:5432"]
    environment:
      POSTGRES_DB: myapp_tests
Enter fullscreen mode Exit fullscreen mode

Pain Point 5: Shared Global Tools and SDK

The .NET SDK is machine-wide. global.json in your repo pins the version. Since all worktrees share the same repo, they all use the same SDK version. No issues here — this just works.

My 5-Agent Workflow

Here's my actual daily workflow. I've been running this for a few weeks and it's settled into a rhythm.

Morning planning (10 minutes):

  1. Check the backlog. Pick 4-5 independent tasks.
  2. "Independent" means: different files, different concerns, no shared migration paths.
  3. Create worktrees and branches: 
# Quick script I keep handy
#!/bin/bash
REPO="C:\code\MyApp"
TREES="C:\code\MyApp-worktrees"

for branch in "$@"; do
    git worktree add "$TREES/$branch" -b "$branch" 2>/dev/null || \
    git worktree add "$TREES/$branch" "$branch"
    echo "Created worktree: $TREES/$branch"
done
Enter fullscreen mode Exit fullscreen mode 
# Usage
./create-worktrees.sh fix/pagination feature/api-tests refactor/blazor fix/scss update/docs
Enter fullscreen mode Exit fullscreen mode

Parallel execution (1-2 hours):

  1. Open 5 terminals (I use Windows Terminal with tabs).
  2. Launch Claude Code in each worktree with a clear, scoped prompt.
  3. Monitor. Most tasks complete in 5-15 minutes.
  4. Review each agent's work as it finishes.

Merge back (15 minutes):

  1. Review diffs. Run tests in each worktree.
  2. Merge completed branches back to master: 
git checkout master
git merge fix/pagination
git merge feature/api-tests
# ... and so on
Enter fullscreen mode Exit fullscreen mode
  1. Clean up worktrees: 
git worktree remove ../MyApp-worktrees/fix-pagination
git worktree remove ../MyApp-worktrees/add-tests
# Or nuke them all
git worktree list | grep -v "bare" | awk '{print $1}' | xargs -I{} git worktree remove {}
Enter fullscreen mode Exit fullscreen mode

Results: What used to take a full day of sequential agent sessions now takes about 2 hours including review time.

Task Selection Matters

Not every task is a good worktree candidate. The ideal task for parallel AI execution:

Good for worktrees Bad for worktrees
Bug fix in isolated file Database schema migration
Adding tests for existing code Renaming a shared model class
New endpoint (separate controller) Refactoring shared base classes
UI component work Changing DI registration order
Documentation updates Anything that touches Program.cs

The rule of thumb: if two tasks would cause a merge conflict, don't run them in parallel.

Common Worktree Pain Points

The criticisms are real. Let me address them honestly.

"I have to npm install in every worktree."

True for Node projects. For .NET, dotnet restore is fast because the global package cache is shared. If you're in a monorepo with both Node and .NET, install node_modules per worktree — it takes 30 seconds with a warm cache.

"Pre-commit hooks don't install automatically."

If you use Husky or similar, run the install command after creating the worktree. For .NET projects using dotnet format as a pre-commit hook, it works automatically since the tool is restored via dotnet tool restore.

"I have to copy env files."

Write a setup script. Seriously. If you're creating worktrees regularly, spending 20 minutes on a setup-worktree.sh script will save you hours:

#!/bin/bash
WORKTREE_DIR=$1
cp .env "$WORKTREE_DIR/.env"
cd "$WORKTREE_DIR"
dotnet restore
dotnet tool restore
echo "Worktree ready: $WORKTREE_DIR"
Enter fullscreen mode Exit fullscreen mode

"Ports conflict."

Pass --urls to override the port. For ASP.NET Core integration tests, port conflicts aren't even an issue — WebApplicationFactory<T> uses an in-memory test server with no actual port binding. Multiple test suites can run simultaneously without stepping on each other.

These are all solvable problems. The throughput gain is worth the 30-minute setup cost.

When Worktrees Don't Make Sense

I'm not going to pretend worktrees are always the answer. Skip them when:

  • Your task list has sequential dependencies (task B needs task A's output)
  • You're working on a single large feature that touches every layer
  • Your repo is small enough that the agent finishes in under 3 minutes anyway
  • You're on a machine with less than 16GB RAM (each agent + build process eats memory)
  • The codebase has heavy shared state — a single God.cs file that everything imports

For a focused 30-minute bug fix, just use your main directory. Worktrees shine when you have 3+ hours of independent tasks and the machine to run them.

Frequently Asked Questions

What is a git worktree?

A git worktree is an additional working directory linked to an existing repository. It lets you check out a different branch in a separate folder while sharing the same git history and objects. Created with git worktree add <path> <branch>, worktrees have been available since Git 2.5 (July 2015).

Can I use git worktrees with Visual Studio?

Yes. Visual Studio 2022 and later can open a worktree folder as a project. Solution files, project references, and NuGet packages all work normally. The only caveat is that Solution Explorer shows the worktree path, not the main repo path. JetBrains Rider also handles worktrees well.

How many git worktrees can I run at once?

Git imposes no hard limit. The practical limit is your machine's RAM and CPU. Each worktree with an AI agent running dotnet build consumes roughly 2-4GB of RAM. On a 32GB machine, 5-6 concurrent worktrees with active builds is comfortable. On 64GB, you can push to 10+.

Do git worktrees share the NuGet cache?

Yes. The NuGet global packages folder (~/.nuget/packages) is machine-wide, not per-repository. When you run dotnet restore in a worktree, packages are resolved from the global cache. Only packages not already cached will be downloaded. This makes the first restore in a new worktree fast — usually under 10 seconds for a typical .NET solution.

Are git worktrees better than multiple git clones?

For AI-assisted parallel development, yes. Worktrees share git history, refs, and the object database. Five worktrees use a fraction of the disk space of five full clones. Commits made in any worktree are immediately visible to all others (same .git directory). The only advantage of separate clones is full isolation — useful if you need different git configs or hooks per copy.

How do I resolve merge conflicts from parallel worktree branches?

Merge each branch back to your main branch one at a time. If branches touched different files (which they should if you planned well), merges are clean. For conflicts, resolve them using your normal merge workflow. The key is task selection: if you chose truly independent tasks, merge conflicts are rare. I've been running 5 parallel branches daily for weeks and hit fewer than 3 conflicts total.

Stop Waiting, Start Parallelizing

The era of watching a single AI agent grind through your tasks one by one is over. Git worktrees give you isolated workspaces in seconds. AI coding tools give you agents that can fill each one.

The math is simple. If one agent takes 10 minutes per task and you have 5 tasks, that's 50 minutes sequential. With 5 worktrees, it's 10 minutes plus review time.

Set up a few worktrees. Pick independent tasks. Launch your agents. Go make coffee.

When you come back, five branches will be waiting for review.

Now if you'll excuse me, I have 4 agents running and one of them just finished refactoring my Blazor grid component. Time to review.

About the Author

I'm Mashrul Haque, a Systems Architect with over 15 years of experience building enterprise applications with .NET, Blazor, ASP.NET Core, and SQL Server. I specialize in Azure cloud architecture, AI integration, and performance optimization.

When production catches fire at 2 AM, I'm the one they call.

Follow me here on dev.to for more .NET and AI coding content

Top comments (0)