Git Worktrees for Parallel Agents

The Problem

You want three Claude Code agents working simultaneously:

• One refactoring the API
• One writing tests
• One updating documentation

But they all need the same codebase. Cloning three copies wastes disk space and creates sync nightmares.

Why Worktrees

Git worktrees create lightweight, isolated workspaces from a single repository.

• Shared git history - All worktrees reference the same .git directory
• Independent working directories - Each agent gets its own files to modify
• No duplication - node_modules, build artifacts stay in one place
• Automatic sync - Commits in any worktree appear in all others

Think of worktrees as browser tabs for your repo. Same session, different views.

Setup

Create Your First Worktree

From your main repo:

# Create worktree on a new branch
git worktree add ../myproject-agent1 -b feature/api-refactor

# Create worktree on existing branch
git worktree add ../myproject-agent2 existing-branch

This creates a new directory ../myproject-agent1 with a full working copy checked out to the specified branch.

Verify Your Worktrees

git worktree list

Output:

/Users/you/myproject         abc1234 [main]
/Users/you/myproject-agent1  def5678 [feature/api-refactor]
/Users/you/myproject-agent2  ghi9012 [existing-branch]

Launch Agents

Open separate terminals for each worktree:

# Terminal 1
cd ../myproject-agent1
claude

# Terminal 2
cd ../myproject-agent2
claude

Each Claude Code session operates in complete isolation. No file conflicts. No merge disasters mid-task.

Workflow

Parallel Development Pattern

1. Plan tasks - Break work into independent chunks
2. Create worktrees - One per task/agent
3. Run agents - Each in its own directory
4. Review commits - All appear in shared history
5. Merge branches - Standard git workflow
6. Clean up - Remove finished worktrees

Best Practices

• One branch per worktree - Git enforces this; you can’t checkout the same branch twice
• Name directories clearly - myproject-agent-tests, myproject-agent-docs
• Keep main clean - Do agent work on feature branches
• Commit often - Smaller commits are easier to review and merge

Handling Dependencies

For Node.js projects, you have two options:

# Option 1: Separate node_modules per worktree
cd ../myproject-agent1
npm install

# Option 2: Symlink to save space
ln -s ../myproject/node_modules node_modules

Option 2 saves disk space but can cause issues if agents need different dependency states.

Cleanup

Remove a Single Worktree

# From any worktree or main repo
git worktree remove ../myproject-agent1

Force Remove (if files were modified)

git worktree remove --force ../myproject-agent1

Prune Stale References

If you manually deleted a worktree directory:

git worktree prune

Clean Up Branches

After merging, delete the feature branches:

git branch -d feature/api-refactor

Quick Reference

When to Use Worktrees

• Running multiple AI agents in parallel
• Testing a feature while fixing a bug on main
• Comparing behavior across branches
• Code review while continuing development

Worktrees turn your single repo into a fleet-ready workspace. Each agent gets isolation without the overhead of full clones.

Next: Coordinating Agent Tasks