Claude Code Worktrees: Run Parallel AI Agents Without Git Conflicts

February 2026 • 10 min read

You have three features to build. You spin up three Claude Code sessions, point them all at the same repo, and tell each one to get to work. Twenty minutes later, every session is stuck in merge conflict hell. One agent rewrote the imports another agent was editing. A third deleted a file the first one just created. Your “parallel productivity” experiment just tripled your workload.

This is the single most common failure mode in multi-agent development. The fix is not better prompts or smarter agents. It is git worktrees — and Claude Code has built-in support for them.

The Problem: Shared Working Directory

When two Claude Code sessions operate on the same repository checkout, they share a single working directory. Every file write from Agent A is immediately visible to Agent B. This creates three categories of failure:

• Write conflicts — two agents edit the same file simultaneously, and the last write wins. The first agent’s changes vanish silently.
• State corruption — Agent A installs a dependency. Agent B runs the build before node_modules finishes updating. The build fails, Agent B starts “fixing” it, and now you have two problems.
• Branch chaos — both agents are on the same branch. Their commits interleave unpredictably. Reverting one agent’s work means cherry-picking through a tangled history.

The root cause is simple: git was designed for one developer per working directory. Multiple agents need multiple working directories.

The Solution: Git Worktrees

Git worktrees let you check out multiple branches of the same repository into separate directories — without cloning the repo multiple times. Each worktree has its own working directory, its own index, and its own HEAD. But they all share the same .git object database, so there is no wasted disk space and no need to fetch twice.

# Create a worktree for a new feature branch
git worktree add ../my-repo-feature-auth feature/auth

# Create another worktree for a different feature
git worktree add ../my-repo-feature-dashboard feature/dashboard

# List all worktrees
git worktree list

Each worktree is a fully independent checkout. Agent A can rewrite every file in worktree 1 without affecting Agent B in worktree 2. When both are done, you merge their branches through normal git workflow — pull requests, code review, the usual process.

Claude Code Worktree Support

Claude Code has native worktree support. When you start a session, you can tell it to create and operate inside an isolated worktree automatically:

# Start Claude Code in a new worktree
claude --worktree

# Or specify a name for the worktree
claude --worktree my-feature-branch

When you use the --worktree flag, Claude Code does the following:

1. Creates a new git worktree in .claude/worktrees/ based on the current HEAD
2. Creates a new branch for the worktree automatically
3. Switches the session’s working directory to the worktree
4. On session exit, prompts you to keep or remove the worktree

This means every agent session is completely isolated from every other session. No shared files. No write conflicts. No interleaved commits.

Step-by-Step: Parallel Agent Setup

Here is the complete workflow for running three parallel Claude Code agents on the same project without conflicts.

Step 1: Prepare Your Branches

Before spawning agents, decide what each one will work on. The key rule: no two agents should touch the same files. Divide work by feature boundary, not by file type.

Step 2: Launch Worktree Sessions

Open three terminal tabs (or use Beam’s split pane layout) and launch each agent in its own worktree:

# Terminal 1
cd /path/to/your/project
claude --worktree auth-feature

# Terminal 2
cd /path/to/your/project
claude --worktree dashboard-feature

# Terminal 3
cd /path/to/your/project
claude --worktree api-docs

Each agent now operates in a completely isolated directory. They can install different dependencies, modify shared config files, and make breaking changes — none of it affects the others.

Step 3: Give Each Agent Its Task

Be explicit about scope. Tell each agent exactly what it owns and what it should not touch:

# In the auth-feature worktree session
"Build user authentication with email/password login. Create the auth
routes in src/app/api/auth/, the login/signup components in
src/components/auth/, and the session middleware in src/middleware.ts.
Do not modify any dashboard or analytics files."

Step 4: Monitor and Merge

As each agent completes its work, review the changes in its worktree branch. Then merge into main through your normal workflow:

# Review Agent 1's work
cd ../my-repo-auth-feature
git log --oneline
git diff main

# Create PR or merge directly
git checkout main
git merge feature/auth-feature

Managing Worktree Sessions in Beam

Running parallel worktree sessions from raw terminals works, but it quickly becomes hard to track which terminal is which agent. Beam solves this with its workspace and tab system.

Create a workspace for your project, then open one tab per worktree agent. Name each tab after the feature it is working on. Use split panes to monitor two agents side by side. When an agent asks a question or hits an error, you can see it immediately without cycling through terminal windows.

The key advantage: visual monitoring. When you have three agents running in parallel, you need to see all of them at once. If Agent 2 goes off track, you catch it in 30 seconds instead of discovering the mess 20 minutes later. Beam’s side-by-side layout gives you that visibility without any terminal management overhead.

Worktree Cleanup

After merging, clean up your worktrees to avoid clutter:

# Remove a specific worktree
git worktree remove ../my-repo-auth-feature

# Prune stale worktree references
git worktree prune

# List remaining worktrees
git worktree list

If you used Claude Code’s --worktree flag, the session will prompt you to keep or remove the worktree when you exit. For manually created worktrees, run cleanup periodically so you do not end up with dozens of stale directories.

When Worktrees Are Not Enough

Worktrees solve the file-level isolation problem, but some conflicts happen at a higher level:

• Database migrations — two agents adding migrations with the same sequence number. Solution: assign migration number ranges to each agent before starting.
• Shared config files — both agents need to modify package.json to add dependencies. Solution: have one agent install all dependencies first, or reconcile after merging.
• API contracts — Agent A changes the API response shape that Agent B depends on. Solution: define API contracts in a shared spec before agents start coding.

The pattern is the same: resolve coordination at the planning stage, not during implementation. Worktrees give you file isolation. Good task decomposition gives you logical isolation.

Performance Considerations

Each worktree shares the git object database, so disk usage is minimal — only the working tree files are duplicated. However, each Claude Code session consumes its own API tokens and system resources. Running three agents in parallel means roughly 3x the token usage.

For most projects, the time savings far outweigh the token cost. Three agents completing three features in 30 minutes beats one agent doing them sequentially in 90 minutes. But monitor your token usage and set budgets per session to avoid surprises.

Summary

Running parallel AI agents on the same codebase without worktrees is a recipe for merge conflicts and wasted time. Git worktrees give each agent its own isolated working directory while sharing the same repository. Claude Code’s --worktree flag makes this seamless.

The workflow is straightforward: divide work by feature boundary, launch each agent in its own worktree, monitor progress side by side, and merge one branch at a time. Combined with a tool like Beam for visual monitoring, you can reliably run three or four agents in parallel and ship features at a pace that would be impossible with a single session.