How to Run Multiple Claude Code Agents in Parallel with Git Worktrees

Mar 16, 2026

The Problem

I tried running two Claude Code agents at once. One was refactoring the backend while the other worked on the frontend. Within minutes, both agents tried to edit the same config file. Chaos ensued:

CONFLICT (content): Merge conflict in src/config.ts
Automatic merge failed; fix conflicts and then commit the result.

Worse, my dev server crashed because both agents were trying to bind to port 3000. I lost half an hour of work.

Why Git Normally Fails Here

Git only allows one branch checked out at a time. When I tried to work on multiple features simultaneously:

Main repo (main branch)
    |
    +-- Agent 1 working on feature-a
    |
    +-- Agent 2 working on feature-b  <-- CONFLICT!

Both agents share the same working directory. If agent 1 creates a file, agent 2 sees it immediately. If both modify the same file, the last write wins or Git complains about uncommitted changes.

Git Worktrees: The Solution

A Reddit user (idoman) pointed me to the answer:

“Once you’re comfortable with Claude Code, look into running multiple agents in parallel using git worktrees. Each agent gets its own branch and port so they don’t step on each other.”

Git worktrees let me create additional working directories that all share the same Git repository. Each worktree has its own branch, its own files, and its own port. No conflicts.

Main Repository
    |
    +-- .git/ (shared history)
    |
    +-- main/           (main branch working dir)
    |
    +-- .claude/worktrees/
            |
            +-- agent-auth/    (feature-auth branch)
            +-- agent-api/     (feature-api branch)
            +-- agent-tests/   (feature-tests branch)

The key insight: one repository, multiple working directories. Each agent operates in complete isolation while sharing the same commit history.

My First Attempt: Manual Worktree Setup

I started by creating worktrees manually.

Step 1: Create a Worktree

# Create a new branch with its own working directory
git worktree add .claude/worktrees/agent-auth -b feature-auth

# List all worktrees
git worktree list

Output:

/home/user/project                abc1234 [main]
/home/user/project/.claude/worktrees/agent-auth  abc1234 [feature-auth]

Step 2: Start Claude Code in the Worktree

# Navigate to the new worktree
cd .claude/worktrees/agent-auth

# Start Claude Code
claude

# Now this agent works in isolation on feature-auth branch

Step 3: Configure Different Ports

Each agent needs its own port for the dev server:

# In agent-auth worktree
export PORT=3001
npm run dev

# In another worktree (agent-api)
export PORT=3002
npm run dev

Step 4: Merge and Clean Up

After the agent finishes its work:

# Go back to main
cd ../../..

# Merge the feature branch
git merge feature-auth

# Remove the worktree (keeps the branch)
git worktree remove .claude/worktrees/agent-auth

# Optionally delete the branch
git branch -d feature-auth

This worked, but setting up worktrees manually for every agent was tedious. I kept forgetting to assign different ports. I needed automation.

Automating with a Script

I wrote a script to standardize the process:

#!/bin/bash

WORKTREE_BASE=".claude/worktrees"
BASE_PORT=3001

create_agent_worktree() {
    local name=$1
    local branch="agent/$name"
    local path="$WORKTREE_BASE/$name"
    local port=$((BASE_PORT + ${2:-0}))

    # Create the worktree
    git worktree add "$path" -b "$branch"

    # Create .env with unique port
    echo "PORT=$port" > "$path/.env"

    echo "Created worktree at $path on branch $branch (port $port)"
}

# Setup three parallel agents
create_agent_worktree "frontend" 0
create_agent_worktree "backend" 1
create_agent_worktree "tests" 2

echo ""
echo "Parallel agents ready. Start Claude Code in each worktree:"
echo "  cd $WORKTREE_BASE/frontend && claude"
echo "  cd $WORKTREE_BASE/backend && claude"
echo "  cd $WORKTREE_BASE/tests && claude"

Running this script:

chmod +x setup-parallel-agents.sh
./setup-parallel-agents.sh

Output:

Created worktree at .claude/worktrees/frontend on branch agent/frontend (port 3001)
Created worktree at .claude/worktrees/backend on branch agent/backend (port 3002)
Created worktree at .claude/worktrees/tests on branch agent/tests (port 3003)

Parallel agents ready. Start Claude Code in each worktree:
  cd .claude/worktrees/frontend && claude
  cd .claude/worktrees/backend && claude
  cd .claude/worktrees/tests && claude

The Galactic Tool: Zero Configuration

Then I discovered Galactic, which automates this entire workflow:

# Clone Galactic
git clone https://github.com/idolaman/galactic
cd galactic

# Start with 3 agents
./galactic start --agents 3

Galactic handles:

Worktree creation with proper naming
Port assignment automatically
Agent session isolation
Cleanup after work completes

This is what I use now for most projects.

Port Assignment Strategy

When running multiple dev servers, I use a consistent port strategy:

Agent Name     Branch           Port
---------------------------------------
frontend       agent/frontend   3001
backend        agent/backend    3002
tests          agent/tests      3003
docs           agent/docs       3004

I store this in each worktree’s .env file:

PORT=3001
API_URL=http://localhost:3002

Merge Strategy for Parallel Work

After agents finish their tasks, I merge systematically:

# First, check what branches exist
git branch -a

# Merge one at a time
git checkout main
git merge agent/frontend
# Test, fix any issues

git merge agent/backend
# Test, fix any issues

git merge agent/tests
# Test, fix any issues

# Clean up worktrees and branches
git worktree prune
git branch -d agent/frontend agent/backend agent/tests

Issues I Encountered

Issue 1: Forgot to Remove Worktrees

I deleted branches without removing worktrees first:

fatal: cannot delete branch 'agent/auth' checked out at '.claude/worktrees/auth'

Fix:

# Remove worktree first, then branch
git worktree remove .claude/worktrees/auth
git branch -d agent/auth

Issue 2: Port Conflicts

Two agents tried to use port 3000:

Error: listen EADDRINUSE: address already in use :::3000

Fix: Always set PORT in .env or command line:

PORT=3001 npm run dev

Issue 3: Stale Worktrees

After some experimentation, git worktree list showed paths that no longer existed:

# Clean up stale worktree references
git worktree prune

Best Practices I Follow

Naming Conventions

I use descriptive branch names that indicate the work:

agent/auth-system     - Authentication feature
agent/api-refactor    - API refactoring task
agent/test-coverage   - Adding tests

Assign Non-Overlapping Files

When possible, I give each agent ownership of specific modules:

Agent 1: src/auth/*       (authentication module)
Agent 2: src/api/*        (API module)
Agent 3: tests/*          (test files)

This reduces merge conflicts significantly.

Review Before Merging

Each agent’s work gets reviewed before I merge:

# See all changes before merging
git diff main...agent/frontend

# Check for unexpected modifications
git log main..agent/frontend --oneline

When Parallel Agents Shine

I find parallel agents most useful for:

Independent features: Frontend vs backend vs tests
Research tasks: Each agent investigates a different approach
Refactoring: One agent per module
Documentation: While code agents work, doc agent writes

When Parallel Agents Don’t Help

Single-threaded tasks don’t benefit:

Sequential dependencies: Task B needs Task A’s output
Shared file modifications: Both agents editing config.ts
Database migrations: Only one can run at a time

Summary

Git worktrees transformed my Claude Code workflow from single-threaded to parallel. Instead of waiting for one agent to finish before starting another, I run multiple agents simultaneously.

The setup is straightforward:

Create a worktree for each agent
Assign unique ports for dev servers
Start Claude Code in each worktree
Merge and clean up when done

For quick setup, use the manual approach. For ongoing projects, Galactic automates everything.

The productivity gain is real: what used to take me a full day now takes a few hours. Multiple agents working in parallel, each in its own isolated workspace, with no conflicts and no chaos.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Git Worktree Documentation
👨‍💻 Galactic - Parallel Claude Code Automation
👨‍💻 Claude Code Official Documentation
👨‍💻 r/AI_Agents Discussion

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!