Parallel Coding with Git Worktrees: Zero-Collision Execution
When engineering teams scale AI agent usage, running multiple terminal sessions in the same working directory creates immediate file lock collisions, uncommitted file overwrites, and git state corruption. If Session A refactors auth.ts while Session B runs integration tests on user.ts, both sessions compete for the single .git/index lock file. Git Worktrees solve this problem by allowing developers to check out multiple branches of the same repository into separate directories while sharing a single .git object store.
In this article, we demonstrate how to orchestrate multi-agent Claude Code sessions using Git worktrees. We trace a scenario in a user-management-service repository — running 3 parallel Claude Code subagents on refactoring, test writing, and bug fixing — while preventing git lock contention. For broader agent architecture and context mechanics, see How Claude Code Works and Inside Claude Code's Context Window.
Why Git Worktrees are Essential for AI Agents
A standard git checkout modifies files in-place within a single working directory. When autonomous AI agents edit files, run test suites, and execute git commits in parallel, operating on a single working directory causes frequent race conditions.
Git Worktrees allow you to link multiple working trees to a single repository database. Each worktree possesses its own working directory, HEAD reference, and staging index (.git/index), but shares all local branches, commit history, and stash states.
| Metric | Single Directory (In-Place) | Git Worktrees (Multi-Directory) |
|---|---|---|
| Concurrency | 1 active agent session at a time | Unlimited parallel agent sessions |
| Index Safety | Frequent index.lock contention | Isolated index lockfile per worktree |
| Context Separation | Agents see each other's uncommitted files | Strict filesystem boundary per task |
| Disk Space Cost | Low | Low (Shares single .git object store) |
Quick reference
- Worktrees share object databases, avoiding the disk space overhead of cloning multiple repository copies.
- Each worktree operates with a dedicated working branch, preventing uncommitted file collisions.
- Claude Code automatically respects directory boundaries when launched inside a worktree root.
Remember this
Git Worktrees provide the filesystem and git index isolation necessary for running concurrent AI coding sessions without collisions.
Creating & Managing Worktrees for Agent Sessions
To launch parallel agent sessions, initialize worktrees in a dedicated .worktrees/ directory (which should be added to your root .gitignore).
Here is how to set up 2 parallel worktrees for distinct agent tasks:
1# Create dedicated worktree directory2mkdir -p .worktrees3 4# Branch 1: Refactor database client5git worktree add .worktrees/refactor-db -b feat/refactor-db-client6 7# Branch 2: Write missing API unit tests8git worktree add .worktrees/api-tests -b test/api-coverage-boost9 10# Launch Claude Code Session #1 in worktree 111cd .worktrees/refactor-db && claude12 13# In a separate terminal tab, launch Session #2 in worktree 214cd .worktrees/api-tests && claudeQuick reference
- Always add
.worktrees/to your root.gitignorefile to prevent tracking worktree metadata. - Worktree branches can be rebased and merged into
mainindependently once agent PRs pass CI. - Remove completed worktrees cleanly using
git worktree remove .worktrees/refactor-db.
Remember this
Organizing worktrees under a dedicated .worktrees/ directory makes parallel agent execution clean and predictable.
Git Lockfile Isolation & Conflict Mitigation
When Claude Code executes git operations (such as stage, commit, or stash), git creates a temporary .git/index.lock file. In a single working directory, simultaneous commits from two agent terminals will cause one process to crash with fatal: Unable to create index.lock: File exists.
Worktrees prevent this failure mode because each worktree stores its index lockfile inside .git/worktrees/<worktree-name>/index.lock. Simultaneous commits in separate worktrees execute in complete isolation.
Quick reference
- Separate index lockfiles eliminate lock contention during parallel commits.
- Automated PR creation commands (
gh pr create) run cleanly without branch swapping. - Worktree sessions maintain independent prompt context histories.
Remember this
Isolated index lockfiles guarantee zero git lock collisions during concurrent multi-agent work.
Pruning Stale Worktrees & Directory Hygiene
After an agent session completes its task and pushes a pull request, the worktree directory should be pruned to keep the workspace organized:
1. Verify PR Status: Ensure all branch commits are pushed to remote.
2. Remove Worktree: Run git worktree remove .worktrees/<name>.
3. Prune References: Run git worktree prune to clear stale administrative metadata.
4. Clean Branches: Delete merged local branches with git branch -d <branch-name>.
Quick reference
- Running
git worktree listprovides an overview of all active working trees and their HEAD commits. - Forcing removal on uncommitted files requires
git worktree remove --force. - Pruning stale metadata maintains repository responsiveness in large teams.
Remember this
Regular worktree pruning prevents directory clutter and keeps multi-agent repository management efficient.
Hands-on Practice: Run 2 Parallel Worktree Agents
Solidify your understanding of worktree concurrency with this hands-on exercise:
1. Create Worktrees: In a sample git repository, run git worktree add .worktrees/task-a -b feat/task-a and git worktree add .worktrees/task-b -b feat/task-b.
2. Launch Terminal 1: In .worktrees/task-a, start Claude Code and prompt it to create src/utils/math.ts with helper functions.
3. Launch Terminal 2: In .worktrees/task-b, start a second Claude Code session and prompt it to update README.md.
4. Verify Concurrency: Confirm that both agents complete their file edits and git commits simultaneously without git index errors.
Quick reference
- Verify that
git worktree listdisplays both active worktrees correctly. - Confirm that neither agent session encounters an
index.lockerror. - Check that both branches merge cleanly into
mainafter completion.
Remember this
Executing parallel worktree agent sessions proves how easy it is to scale concurrent AI workflows safety.
Key takeaway
Git Worktrees are the bedrock of high-throughput AI engineering workflows. By isolating working directories, HEAD references, and staging lockfiles, developers can run multiple Claude Code sessions in parallel without risk of file overwrites or git index corruption.
Practice (20 min): Create two git worktrees in a test repo. Launch Claude Code in both worktree directories simultaneously to perform independent file edits and git commits. Verify clean parallel execution without index lock errors.
Related Articles
Explore this topic