Guide

Git worktrees + Claude Code: run parallel agents without conflicts

Git worktrees are the cleanest way to run several Claude Code agents in parallel without their edits colliding. The idea is simple: give each agent its own working directory checked out from the same repo on its own branch. Agent A refactors auth in one folder, agent B writes tests in another, and neither one ever sees the other half-saved file. Once you stop trying to cram parallel agents into one shared checkout, the whole pattern gets a lot less stressful - and the bottleneck quietly moves somewhere you didn't expect.

Why parallel agents collide

The instinct, when you want two agents working at once, is to open two terminals in the same folder and let them both go. It breaks fast. A git checkout has exactly one working tree and one index. Two agents pointed at the same directory are editing the same files, running the same test command against the same on-disk state, and competing for the same branch. One stages a change, the other reverts it. One switches branches mid-task and the other's edits vanish. You don't get a clean error - you get silent corruption of work that looked fine a second ago.

The fix is not "be careful." The fix is to stop sharing the working tree at all. Each agent needs a directory it owns, with its own files and its own branch, while still being the same repository underneath so the history and remote stay shared. That is exactly what a git worktree is for.

What a git worktree is

A git worktree is a second working directory linked to your repository. It has its own checked-out files, its own branch, and its own HEAD and index - but it shares the repo's object database, history, and remotes with your main checkout. In plain terms: one .git, many folders, each on a different branch. A normal clone duplicates the entire repo; a worktree is far lighter, because the heavy shared part - the history - isn't copied.

That is the whole trick for parallel agents. Give agent A a worktree on feature-auth and agent B a worktree on tests, and their edits live in physically separate folders. Neither can clobber the other, because there is nothing shared to clobber on the working-tree side. When each is done, you commit on its branch and merge like any other branch - no special ceremony.

Set one up (with git worktree add)

The core command has been stable in Git for years. From inside your repo, create a new worktree on a brand-new branch:

git worktree add ../feature-x -b feature-x

That makes a sibling folder named feature-x next to your repo, checks out a new branch also called feature-x into it, and leaves your main checkout untouched. Point an agent at that folder - cd ../feature-x and launch your CLI there - and it has a fully isolated tree to work in. Spin up a couple more for the other tasks:

git worktree add ../tests -b tests
git worktree add ../bugfix-123 -b bugfix-123

You can also branch a worktree from an existing branch by dropping the -b flag and naming the branch as the final argument:

git worktree add ../hotfix existing-branch

See what you have, then remove a worktree when its task is merged:

git worktree list
git worktree remove ../feature-x

One thing the docs are blunt about and you should not skip: a worktree is a fresh checkout, so it does not carry your untracked files. Anything gitignored - .env, local config, an installed node_modules - isn't there. Initialize each worktree like a new clone: install dependencies and copy whatever local files your project needs before you turn an agent loose in it.

If you run Claude Code specifically, recent versions can manage worktrees for you instead of doing this by hand. There's a launch flag that starts a session in a fresh isolated worktree, you can ask it to "work in a worktree" mid-session, and you can set isolation: worktree on a custom subagent so each one runs in its own checkout and is cleaned up automatically when it finishes without changes. The exact flag names and cleanup rules change over releases, so treat the Claude Code worktrees docs as the source of truth rather than memorizing a version. Either way - manual git worktree add or the built-in path - the underlying isolation is the same.

The 3-to-5 agent sweet spot

Once worktrees take file conflicts off the table, the natural next question is "how many agents?" In practice most people settle around three to five concurrent agents, and that ceiling is not about Git. Worktrees scale fine; you can have a dozen folders on a dozen branches without the repo breaking a sweat. The limit is you.

An AI coding agent is not a batch job. It pauses. It stops for a permission prompt, asks a clarifying question, hits an ambiguous decision, or just finishes and waits. Each agent you add is one more process that will, at some unpredictable moment, need a few seconds of your attention - and then nothing for ten minutes. Below roughly three, you can keep the whole thing in your head. Above five, the gaps between "needs me now" events get short enough that you're never not context-switching, and the quality of your decisions drops. Three to five is where the leverage is real and the chaos is still manageable.

The way to push that number up is to pick tasks that need few decisions - the same logic behind pre-approval policies that let an agent run a known-safe set of commands without stopping. The fewer times each agent has to stop, the more of them you can supervise at once. For the broader case for running a fleet at all, see run multiple AI agents at once.

The real problem becomes watching them

Here is the part nobody warns you about. You spend a day learning worktrees, you get five agents running with zero file collisions, you feel like a wizard - and then you discover the bottleneck just moved. It is no longer about files. It is about windows and attention.

Five worktrees mean five terminals (or five panes, or five tabs). They all look the same. A pane that's busy compiling looks identical to a pane that stopped sixty seconds ago waiting for you to approve a command. So you scan. You rotate through them looking for the one that stalled, and the answer is reliably "the one you weren't looking at." Tools like tmux are genuinely good at keeping the processes alive in one window - what they fundamentally cannot do is tap you on the shoulder when one of them needs a decision. The processes run; the signal never finds you. This is the same wall people hit trying to run Claude Code in the background, and it gets worse linearly with every agent you add.

Solving file conflicts with worktrees and then drowning in terminal-switching is a real anticlimax. The parallelism you built is correct. The interface for supervising it is what's missing.

An overlay as the cockpit

What actually scales isn't more screen real estate - it's routing attention. Three things have to be true at once for a fleet of worktree-isolated agents to stay sane:

• One surface, many agents. Every agent lives in a single window as a tab, each pinned to its own worktree, instead of being scattered across the desktop behind your editor and browser.
• Each tab keeps its own context. A tab is its worktree - its branch, its scrollback, its task. Switching tabs is switching projects cleanly, with no "wait, which agent was this" reload.
• Attention is per-tab, not global. When the bugfix-123 agent hits a permission prompt, its tab lights up - an accent ring, a chime - while the other four keep running silently. You don't scan; the agent that needs you raises its hand.

Get all three and the math flips. Instead of your attention being divided across N agents, it's pulled to exactly the one that needs it, exactly when. With Claude Code that signal comes from its lifecycle hooks - roughly a notification event when an agent wants attention, a stop event when it finishes, and a pre-tool event before it runs something - which an overlay can turn into a per-tab ping. That's the difference between babysitting five terminals and supervising a team; we draw the line in stop babysitting your AI coding agent. And if you're still deciding which CLI to drive these worktrees with, the best AI coding agent in 2026 roundup is a reasonable place to start.

Frequently asked questions

What is a git worktree, in one sentence?

A git worktree is a second working directory checked out from the same repository on its own branch, so two agents can edit files at the same time without touching each other's checkout.

How do I create a git worktree for an agent?

Run git worktree add ../feature-x -b feature-x from inside the repo. That makes a sibling folder on a brand-new feature-x branch; point an agent at that folder and it has its own isolated tree.

How many parallel agents can I realistically run?

Most people land on three to five. Past that the limit stops being file conflicts - worktrees solve those - and becomes attention: you cannot watch five terminals at once and notice which one is blocked.

Does Claude Code create worktrees on its own?

Recent versions can. You can pass a worktree flag at launch, ask it to "work in a worktree" mid-session, or set isolation: worktree on a custom subagent so each one runs in its own checkout. See the Claude Code worktrees docs for the current flags.

Where Backgrind fits

Backgrind is the cockpit for exactly this setup: an always-on-top overlay with a tab per agent, each running your real CLI - Claude Code, Cursor, or Grindy - in its own git worktree, kept alive by a background daemon so closing the window never kills the work. When one agent needs a decision or finishes, only that tab pings with a ring and a chime; the rest run on. You set up your worktrees with plain git worktree add, and Backgrind handles the part that actually breaks at scale - watching them. Backgrind Pro lifts the cap so you can run unlimited parallel agents instead of bumping into a tab limit. Watch the loop in the live demo.