Git Worktree for Agent Isolation

Git worktree agent isolation stops several agents from sharing one clone’s single working directory. Adding a linked worktree to the same repository lets you check out more than one branch at once, each with its own HEAD, index, and tree. No pricing, plans, or token counts.

This post covers only creating worktrees, branch rules, and pre-merge checks. Grounded in the git-worktree documentation. Branch naming, review gates, path allowlists, and PR splitting belong to the separate multi-agent-pr-workflow axis. Here the focus is working-tree isolation.

How do you create a worktree?

One-line answer: From the main worktree, run git worktree add with a path and branch. New branch → -b; existing branch → path (plus commit-ish); throwaway experiments → -d / --detach.

Per git-worktree, a repo has one main worktree (from clone/init) and zero or more linked worktrees. Linked worktrees share objects and most refs/; only per-worktree files such as HEAD and the index stay separate.

Common patterns:

# 1) New topic branch + linked worktree
git worktree add ../wt-agent-a -b feat/TICKET-agent-a

# 2) Existing branch into a new path
git worktree add ../wt-agent-b feat/TICKET-agent-b

# 3) Detached HEAD for experiments
git worktree add -d ../wt-scratch

# 4) Inspect
git worktree list
git worktree list --verbose

Convenience rules the docs emphasize:

  1. git worktree add <path> alone creates a branch named after the path basename (like -b) from HEAD.
  2. If <commit-ish> is a branch already checked out in another worktree, add refuses. Two paths on the same branch are not allowed by default (--force is the exceptional, risky override).
  3. When finished, git worktree remove <path>. Deleting the folder by hand can leave admin files under $GIT_DIR/worktrees until prune.
  4. For paths on removable or network mounts, git worktree lock blocks automatic prune.

Open each agent session with cwd fixed to that agent’s worktree path. If several agents flip checkout in the main tree, they overwrite each other. Worktrees cut that conflict by path.

Even when Orca/Cursor wrap worktrees in UI, the floor is still git worktree add. Confirm real paths and branches with git worktree list before trusting a tool panel.

What are the branch rules?

One-line answer: One agent = one worktree = one branch. Keep main/main for humans; agents only check out their assigned branch. Do not commit on another agent’s branch or a shared integration branch.

Rules to pin on the worktree axis:

RuleWhy (git-worktree)
One dedicated branch per worktreeSame branch may be checked out in only one worktree by default
Name includes role / ticket / agent idOwnership is obvious from list
Main stays human / integrationAgents do not commit or push directly to main
Treat -B / --force as exception processResetting or dual-checkout invites accidents
Always remove when doneOrphaned worktrees waste disk and leave stale admin metadata

Name examples:

../wt-a  →  feat/TICKET-123-api-auth     (agent-A)
../wt-b  →  feat/TICKET-123-ui-login     (agent-B)
../wt-c  →  chore/TICKET-123-ci-cache    (agent-C)

One-liners for prompts / AGENTS.md:

  1. cwd — edit only the assigned worktree path.
  2. branch — commit only when git branch --show-current matches the assignment.
  3. forbidden — other worktree paths, main, peer agent branch checkout/push.
  4. base — fetch origin/main (or agreed base), then -b off that.

Boundary vs multi-agent-pr-workflow: that post covers PR units, review approval, path allowlists, and conflict prevention. This post’s branch rules fix which directory holds which branch via worktrees. Use both for “isolation (worktree) + review (PR).”

Use -d detached worktrees only for experiments. Merge candidates should live on a named branch; commits piled only on detached HEAD are costly to recover.

What are the pre-merge checks?

One-line answer: Inside that worktree, finish status, diff, tests, and rebase/merge onto base, then open a PR. Remove only clean worktrees; leave merge authority to a human (or required checks).

Per-worktree pre-merge checklist:

  1. Location — pwd and git rev-parse --show-toplevel match the assigned worktree.
  2. Branch — git branch --show-current and git worktree list show the expected branch on that path.
  3. Cleanliness — no surprise untracked/modified in git status. remove also requires a clean tree by default (unclean needs --force).
  4. Base sync — git fetch origin, then rebase or merge onto origin/main (agreed base). Resolve conflicts in that worktree.
  5. Local verify — run the project’s agreed tests/lint/build in that path. Do not proxy results from the main tree.
  6. Scope — git diff origin/main...HEAD file list matches the agent’s area (detailed allowlists → PR workflow post).
  7. PR / review — push, open PR. Approve/merge = human/CODEOWNERS. Agents do not approve each other as final gate.
  8. Cleanup — after merge (or abandon), git worktree remove ../wt-…. If you only deleted the folder, git worktree prune from main. After moves, use git worktree repair as documented.

Dangerous shortcuts:

  • Briefly checking out another agent’s branch in the main worktree to “gather” a merge.
  • Repeated --force remove on unclean trees while work is in flight.
  • Forcing the same branch into two worktrees so indexes and commits diverge.

Superprojects with submodules still have incomplete multi-checkout support per the docs. Prefer shrinking submodule boundaries or separate clones before heavy agent parallelism.

Frequently asked questions

How is this different from multiple clones?
Worktrees share the object store and add linked trees. Disk and fetch cost are usually lower than N full clones. Isolation is still by directory and HEAD.

Does this overlap multi-agent-pr-workflow?
Shared vocabulary (branch, agent), different axis. PR workflow = review, paths, conflict prevention. This post = git worktree add/list/remove for working-tree isolation.

Can two agents share one branch?
Default add refuses. Do not --force; split the branch instead.

I deleted the folder by hand.
Stale entries may remain under $GIT_DIR/worktrees. Run git worktree prune, and use remove next time.

What should you remember?

Agent isolation = linked worktree + dedicated branch. Create with git worktree add (-b / existing / -d), rule 1 agent · 1 path · 1 branch, pre-merge status · base · tests in that path, then human review. PR/review detail lives in multi-agent-pr-workflow.

Where are the official sources?

  • git-worktree — add / list / remove / lock / prune / repair
  • Same page DESCRIPTION — main vs linked worktree; refusal of duplicate branch checkout
  • Same page EXAMPLES — temporary worktree for an emergency fix, then remove