Git Worktrees for Parallel Claude Code Sessions: Run 10+ AI Agents Without File Conflicts

Git worktrees let you attach many working directories to a single repo. Each one has its own branch checked out. Claude Code ships a native --worktree (-w) flag that handles the setup in one command. It creates a worktree, checks out a new branch, and launches Claude inside it. Run the same command in another terminal and you’ve got a second agent. Scale to five, ten, or more sessions and none of them clash on disk.

This pattern already has real production mileage. The team at incident.io went from zero Claude Code use to four to seven agents per developer in about four months. Their CTO told the team to “spend as many of my hard-earned VC dollars on Claude as possible” and put a usage leaderboard up in the office. One task, building a JavaScript editor with multiline support, line numbers, and code completion, was sized at two hours of human work. Claude Code shipped it in ten minutes. The friction that kept worktrees a niche git feature is gone now that AI tooling actually needs the isolation they provide.

Why AI Agents Need Worktree Isolation

Without worktrees, two Claude Code sessions on the same checkout fight over the same files. One agent’s edits overwrite the other’s. Staged changes collide, test runs trip each other up, and you spend more time fixing chaos than shipping code. The old fix is to clone the repo more than once. That wastes disk space by copying the full .git folder, and it loses the shared commit history that makes parallel branch work easy.

Git worktrees fix this cleanly. Each worktree is its own folder linked back to the same .git store. They share object storage, reflog, and config, yet each one has its own HEAD, index, and working files. Claude Code spots when it’s inside a worktree and scopes all file reads, writes, bash commands, and test runs to that branch. No setup is needed.

Worktrees turn a serial bottleneck (one developer, one branch, one agent) into parallel work with little overhead. One developer, N branches, N agents, all working at once on the same repo without stepping on each other.

This pattern isn’t unique to Claude Code. OpenAI’s Codex CLI and other terminal-based AI coding agents gain from the same isolation model. Still, Claude Code was the first to ship built-in CLI support for worktree setup and cleanup. Boris Cherny at Anthropic announced the feature in early 2026.

The –worktree Flag: Setup in One Command

Claude Code’s --worktree flag (short form -w) cuts the parallel session setup to one command per agent:

claude --worktree bugfix-123

This makes an isolated worktree at .claude/worktrees/bugfix-123/. It cuts a new branch named worktree-bugfix-123 from wherever origin/HEAD points, then launches Claude Code scoped to that folder. Open another terminal and run:

claude -w feature-auth

Now you’ve got two separate agents. Each sees only its own branch’s state. Scale up by opening more terminals and repeating the pattern.

If you skip the name, Claude picks a random one for you:

claude --worktree

You can also pair worktrees with tmux for headless use:

claude --worktree api-refactor --tmux

This puts the session in its own tmux pane. Your terminal is then free for monitoring or starting more agents.

Worktree Cleanup

Cleanup depends on whether the session made any changes:

• If the session made no changes, the worktree and its branch get dropped on exit.
• If commits or edits exist, Claude asks you to keep or drop the worktree. You can also clean up by hand with git worktree remove .claude/worktrees/bugfix-123.
• Stale worktrees from crashes or killed sessions get auto-pruned at startup once they pass your cleanupPeriodDays setting, as long as they have no uncommitted edits or unpushed commits.

Subagent Worktree Isolation

For Claude Code’s built-in subagents, add isolation: worktree to a custom subagent’s frontmatter. Each subagent gets its own worktree, set up on the fly. The worktree is dropped when the subagent finishes without changes. You can also ask Claude to “use worktrees for your agents” during a session and it will spin them up for you.

The newer Agent Teams feature shipped in v2.1.32. The team lead agent steers multiple teammates that each run in their own context windows and worktrees. When they finish, the team lead merges results one by one. It works much like human developers on separate branches who merge through pull requests.

Team Patterns and Real-World Results

The incident.io Workflow

incident.io’s engineering team wrote up their path from Claude Code newcomers to power users. They now run four to seven agents per developer. Key takeaways from their write-up:

• Their CTO told the team to spend big on Claude, then put up an office leaderboard tracking API token use. Tinkering turned into a team sport.
• Engineer Rory Bain built a w bash function that fuses worktree creation and Claude launch into one command: w myproject new-feature claude. It auto-completes existing worktrees, creates new ones with username-prefixed branches, and runs commands in the worktree context without changing your current folder.
• The biggest wins came from sharing workflow patterns and tools across the team, not from crafting perfect prompts. When one person found a sharp way to use Plan Mode or worktree isolation, the whole team picked it up.

The Decomposition Pattern

The best parallel workflow splits a feature into separate sub-tasks. Each sub-task goes to its own Claude session in its own worktree. For a typical feature this looks like:

Each agent works on its own, all at the same time. The developer’s job shifts from writing code to splitting up work, kicking off agents, and reviewing their output. Shipyard’s guide to multi-agent orchestration covers more advanced patterns, including Agent Teams and third-party tools like Gas Town and Multiclaude.

Desktop Management with Nimbalyst

For devs who prefer a GUI over terminal juggling, Nimbalyst (formerly Crystal, open source at github.com/stravu/crystal ) is a desktop app for running many Claude Code and Codex sessions across parallel git worktrees. It handles worktree setup and session lifecycle, and gives you one view of every running agent. Useful when you scale past the number of terminals you can keep in your head. To let those parallel sessions talk to each other, the open source repos that make Claude Code unstoppable include a peer messaging broker that wires separate sessions together.

The Practical Sweet Spot

Five to ten parallel agents works well for most devs. Past ten, the merge step is the bottleneck, not the build step. You spend more time fixing branches than you save from running in parallel. Start with two or three agents on a well-scoped feature. Get used to splitting work, then scale up as your task-splitting skills get sharper.

Coordination Strategies and Avoiding Merge Conflicts

Worktrees stop filesystem conflicts, since each agent gets its own folder. They do not stop git merge conflicts. If two agents edit the same file on different branches, you’ll get conflicts when you combine their work. The coordination strategy is as important as the isolation mechanism.

Scope by File and Feature Boundaries

The safest setup gives each agent its own set of files. One handles api/users.ts. Another handles components/UserList.tsx. A third writes tests/users.test.ts. No file overlap means no merge conflicts.

For larger features, scope by vertical slice. Each agent owns a full route-plus-component-plus-test stack that doesn’t touch other agents’ slices. It’s the same way you’d split work among human devs on a team.

Watch Out for Shared State

All worktrees share the same local database, Docker daemon, and cache folders. Two agents running database migrations or changing shared state at once will race in ways worktree isolation can’t stop. Lock files like package-lock.json, go.sum, and Cargo.lock are common conflict sources. Pick one “primary” worktree for dependency changes and tell other agents to leave those files alone.

Coordination via CLAUDE.md

Drop coordination notes in the project’s CLAUDE.md file so every agent sees the same scoping rules and norms. You can say which files belong to which agent, what testing patterns to use, and which files are off-limits. Addy Osmani’s write-up on agent orchestra patterns shows how AGENTS.md files build up patterns and norms across sessions. Each later session gets more productive as a result.

The Human Merge Step

After parallel agents finish, a human (or a dedicated merge agent) reviews and combines the branches. This is where conflicts show up and get fixed. With well-scoped work, this step is fast. With poorly scoped work, it becomes the bottleneck that eats your time savings.

Scaling Beyond Individual Productivity

CI/CD Integration

The worktree pattern extends to build pipelines. Run Claude Code agents in worktrees as part of CI: one agent runs tests, another writes docs, a third runs a security review, all at once. This shifts AI agents from dev tools into infra components.

Cost and Resource Management

Each parallel session burns API tokens on its own. At four to seven agents per dev across a twenty-person team, token budgets pile up fast. incident.io turned this into a feature with their leaderboard, but most teams will need spending alerts and per-developer token caps.

On the hardware side, terminal-based Claude Code sessions are light. Twenty concurrent sessions use roughly 7% CPU combined . Rate limits are the real bottleneck, since local compute is small. IDE-based AI tools (Cursor, VS Code extensions) can use a lot more CPU due to renderer processes. Each worktree also takes some disk space for working files, though the .git folder is shared. Watch disk use when you run ten or more worktrees on CI runners with tight storage.

Rate limits are a big deal at scale. On the Pro plan, two Opus-class sessions in parallel will hit the cap in minutes. Max 5x plans give enough headroom for two or three concurrent sessions without constant throttling. Teams running many agents tend to use API keys with org-level rate limits, not personal plans.

Agent Specialization

Rather than give every agent the same generic prompt, write specialized CLAUDE.md notes per worktree. One agent is the test writer and knows your testing framework. Another is the API designer and follows your REST patterns. A third is the code reviewer focused on security and speed. Specialized agents put out better work than one generalist juggling many concerns.

Merge Queue Integration

Connect parallel worktree branches to your existing merge queue (GitHub merge queue, Mergify, or similar) so finished agent work flows through the same review and CI process as human-written code. That stops AI-generated code from skipping quality gates and keeps your main branch stable as agent output goes up.

Parallel AI development through worktrees is still maturing. Six months ago, most devs worked with a single AI assistant in a tight loop. Today, the most productive teams run many agents in parallel. Each agent is scoped to its own branch and files, while the developer orchestrates from above. The tools and norms are moving fast, yet the core technique (git worktrees for filesystem isolation) has been stable in git since 2015. AI agents were the missing piece that finally gave worktrees a reason to be in every developer’s daily toolkit. For a closer look at how Claude Code’s internals enable this scale, the Claude Code source architecture write-up covers the permission model, context handling, and tool dispatch that make concurrent sessions work.