Isolate parallel agents with git worktrees

Run two coding agents in one checkout of a repository and they fight over the same files: one agent's uncommitted edits get overwritten by the other, and a git restore from one session can wipe the other's work. The fix is a git worktreeA second working directory linked to the same repository, with its own checked-out branch but a shared .git per agent. Each agent gets its own folder and its own branch, all sharing one .git, so they never collide.

Why can't one checkout hold two agents?

A normal repository has one working directory. That directory has a single set of files on disk and a single active branch (HEAD). Everything that reads or writes those files is sharing one space.

When you run a single agent, that is fine. The agent edits files, you review, you commit. But the moment a second agent (or a second Claude Code session) starts working in the same folder, the two share that single set of files and that single HEAD.

The failures are concrete:

• Agent A is halfway through editing src/checkout/cart.ts. Agent B runs git checkout other-branch and the file on disk changes underneath Agent A.
• Agent B runs git restore . to undo its own experiment and silently discards Agent A's uncommitted edits in the same tree.
• Both agents commit to the same branch and produce an interleaved history that is hard to read and hard to split apart later.

None of this is a bug in the agents. It is what happens when two writers share one working directory. You need to give each writer its own directory.

What is a git worktree?

A git worktree is a second working directory attached to the same repository. Think of your repository as having one shared database of history and refs (the .git directory) and one or more working directories that check files out of it.

By default you have exactly one working directory: the folder you cloned into. git worktree add creates additional ones. Each new worktree:

• Lives in its own folder on disk, with its own copy of the files
• Has its own checked-out branch and its own HEAD
• Shares the same underlying .git (history, commits, remotes, stashes)

Because the history is shared, a commit made in one worktree is immediately visible to every other worktree. Because the files and HEAD are separate, an edit or a git restore in one worktree cannot touch another worktree's files.Common gotchaThe stash is part of the shared .git, not the worktree, so it is one pile across all of them: an agent that runs git stash pop can grab work another agent stashed.Tell each agent to commit on its own branch instead of stashing, so nothing ends up in that shared pile.

This is the key property: shared history, isolated files. Two agents can run flat out and never overwrite each other.

A worked example: two agents on an online store

Say you are building an online-store app and you want two agents working at once. Agent A reworks the checkout flow. Agent B improves product search. They touch different parts of the code, but if they share one checkout they will still trip over each other's uncommitted state.

Start from your main repository folder, on a clean branch. Create a worktree for each task.

# from inside your store repo, on main with no uncommitted changes
git worktree add ../store-checkout -b checkout-flow
git worktree add ../store-search -b search-feature

Each command does two things. It creates a new folder next to your repo (../store-checkout and ../store-search), and with -b it creates a new branch (checkout-flow, search-feature) and checks it out into that folder. The .. puts the worktree beside your main checkout rather than inside it, which keeps the trees from nesting.

Confirm what you have:

git worktree list

You get one line per worktree, showing the path, the current commit, and the branch:

/Users/you/code/store           a1b2c3d [main]
/Users/you/code/store-checkout  a1b2c3d [checkout-flow]
/Users/you/code/store-search    a1b2c3d [search-feature]

All three point at the same commit right now because the branches were just created. They will diverge as each agent works.

How do I run one agent per worktree?

Now point an agent at each folder. Open a Claude Code session whose working directory is the worktree, not the shared root. The cleanest way is to start the CLI from inside each worktree folder.

# terminal 1
cd ../store-checkout
claude
 
# terminal 2
cd ../store-search
claude

Each session sees only its own files and its own branch. Agent A in store-checkout can edit, run tests, and restore freely; nothing it does reaches store-search. The two run in true parallel because there is no shared working state to corrupt.Common gotchaA fresh worktree only checks out tracked files, so anything gitignored (node_modules, .env, a built .next) does not come with it and the agent's first test run dies on a missing module or config.Install dependencies and copy the env file in each new worktree before pointing an agent at it, or symlink node_modules so the agent is not left debugging a broken setup instead of doing the task.

Give each agent a brief scoped to its worktree so it does not wander into the other's territory.

The scope lines matter. Even with isolated files, you want each agent committing to its own branch and staying in its lane so the merge back is clean.

Commit often so the work is durable

Isolation protects an agent from the other agent. Committing protects the work from the agent itself. Uncommitted changes are fragile: an agent that runs git restore or git checkout to back out an experiment can discard work that was never committed.

The rule is simple. Each agent commits after every meaningful step, on its own branch.

# inside store-checkout, on branch checkout-flow
git add src/checkout/
git commit -m "Add saved payment method selection"

Frequent commits give you two things. The work survives any later restore or checkout, and you get a readable history you can review or revert step by step. If you want the agent to do this automatically, say so in the brief, as in the prompt above. For longer asynchronous runs, the same discipline is covered in briefing Claude Cowork.

Merge each branch back

When an agent finishes, its work lives on a branch in the shared history. You merge it the same way you would merge any branch. Do this from your main checkout.

# from your main store folder
cd ../store
git checkout main
git merge checkout-flow
git merge search-feature

Because the two agents worked on different parts of the app, these merges are usually clean. If both touched a shared file, you resolve the conflict once, in one place, with full context, instead of discovering mid-run that one agent silently overwrote the other.

Review each branch before merging. A quick diff against main tells you exactly what each agent produced:

git diff main..checkout-flow

Keeping one branch per worktree is what makes this table possible. Each unit of work is a clean, reviewable, mergeable branch.

How do I remove a worktree when I am done?

A finished worktree is a folder you no longer need. Remove it so it does not linger and confuse you later.

git worktree remove ../store-checkout
git worktree remove ../store-search

git worktree remove refuses to delete a worktree that still has uncommitted or untracked changes, which is a safety net: it stops you throwing away work you forgot to commit. If you are certain you want it gone anyway, git worktree remove -f <path> overrides that check. Commit or stash first when you can; the force flag should be rare.

If a worktree folder was deleted by hand (say you rm -rf the directory), git still has bookkeeping for it. Clear that out:

git worktree prune

This removes the leftover administrative records for worktrees whose folders no longer exist. It does not touch any branches or commits, only the stale tracking entries.

One rule worth knowing: no double-checkout

By default, git refuses to check out the same branch in two worktrees at once. If you try to git worktree add a path for a branch that another worktree already has checked out, the command fails.

This is deliberate and it protects you. Two worktrees on one branch would put you right back in the original problem: two writers sharing one branch's state. Give each agent its own branch and the restriction never gets in your way. You can override it with -f, but for parallel agents you almost never should.

When should I use a git worktree?

Worktrees shine when the work runs in parallel and the tasks are mostly independent.

• Use a worktree per agent when you want two or more agents working at the same time, each on a separate feature or fix.
• A single checkout is fine when you run one agent at a time, even across many branches, because nothing else is writing the tree.
• Prefer separate worktrees over separate clones because clones duplicate all of history and lose the shared refs and stashes; worktrees share one .git, so they are lighter and a commit in one is instantly visible to the others.

The short version

Parallel agents collide when they share one working directory. A git worktree gives each agent its own folder and its own branch over one shared .git, so edits and restores in one session cannot reach another. Add a worktree per task with git worktree add ../task -b task, run one agent in each, commit often, merge the branches back, and remove the worktrees when you finish.

For a wider view of running several agents at once, see how agents fan out and running agents in parallel. For keeping each agent's instructions tight and self-contained, see briefing Claude Cowork.