Running parallel agents safely with git worktrees.

Guides

Two agents editing one working tree will eventually clobber each other. One runs a checkout or a stash to get a clean test run and the other loses its work. A git worktree gives each agent its own folder and branch over the same repository history, which removes that failure. It does not remove all of them, so this guide covers both halves.

Create a worktree per writer

# Claude Code: a new worktree and branch under .claude/worktrees/
claude --worktree feature-auth

# Plain git, works with any agent: a sibling folder on a new branch
git worktree add ../my-repo-billing -b billing-fix
git worktree list

# When the lane is landed and clean (no --force)
git worktree remove ../my-repo-billing

Claude Code's --worktree flag creates the folder under .claude/worktrees/<name>/ on a branch named worktree-<name>, and you can run it again with another name in another terminal. Add .claude/worktrees/ to .gitignore. A .worktreeinclude file (gitignore syntax) copies untracked files such as .env into each new worktree. A subagent can run in its own worktree too, with isolation: worktree in its frontmatter. A worktree is a fresh checkout, so install dependencies in it.

What a worktree does not isolate

It separates files and the git index. It does not separate databases, ports, package caches or external services, and the .git directory is shared. Two lanes running the same test suite against one local database will produce intermittent failures that look like bugs. Give each lane its own test data and port, or serialise those steps. Cap heavy work too: one full build at a time, with focused tests in the other lanes.

Decide ownership before you start

  • Split by a clear interface or deliverable, not by slices of one file.
  • Write down each lane's directory, owned files, read-only dependencies and expected handoff.
  • Include generated outputs and fixtures. Two lanes can collide through a generated index even when their source files are separate.
  • Give shared manifests, lockfiles and route registries one owner. A lane that needs another lane's file stops and asks.

Brief the lanes

Every brief carries the same line, even with separate worktrees, because an agent can still switch branches or run a clean in the wrong place:

Git: do not run any git command that writes, including add, commit,
     checkout, restore, reset, stash, clean, merge, rebase or worktree changes.

Tell each writer that others are active and that unexpected changes are not theirs to revert. The briefing guide has a full template.

Integrate, then retire

  • Read the actual diff, including unexpected files, and rerun the checks the merge affects. A lane's passing tests describe that lane, not the combined tree.
  • Commit with explicit pathspecs for that lane's files, never a blanket add.
  • Retire a worktree only when its status is clean and its work is landed. Use git worktree remove without --force. Ignored files found nowhere else count as unique work.
  • Do not glob-delete inside a worktree, and do not soft-reset a lane onto a newer main to land it.

The kit's parallel-lanes and hygiene protocols are this checklist written for agents, and its shell guard reads a worktree's HEAD file to check branch rules without launching git. Claude Code also blocks edits and git redirects that reach the main checkout from an isolated session, which helps but does not replace the brief.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides