Git Worktrees for AI Coding Agents: A Practical Setup Guide

Why worktrees beat a shared checkout

Two agents editing one checkout are not collaborating. They are taking turns changing the floor while the other one is walking on it. A formatter can rewrite files under a second agent, a branch switch can invalidate an active test, and a cleanup command can erase work nobody realized was uncommitted.

Full clones avoid that class of collision, but they duplicate repository setup and make branch discovery harder. Git worktrees keep one shared object database while giving each agent a separate checkout, index, and branch. You can see every active workspace with one command and remove it deliberately when the task is actually over.

1. Start every task from one reviewed base

Fetch first. Then record the commit that all parallel work should start from. If one agent starts from yesterday's main and another starts after a schema migration, their independence is fake; the integration conflict is merely delayed.

git fetch origin --prune
git rev-parse origin/main
# Example base: ff4f3380856aff63624f58ab0fa50690f16dafcc

The exact hash belongs in the task handoff or orchestration state. Human-readable branch names are useful; immutable commit hashes are what make the result auditable.

2. Create one outcome-named worktree per editing agent

Name branches after the change: feat/add-session-replay, notclaude-2. The model may change halfway through the task. The outcome should not.

git worktree add .worktrees/session-replay -b feat/add-session-replay origin/main
git worktree add .worktrees/session-tests -b test/add-session-replay-coverage origin/main
git worktree list

Keep worktrees under one visible parent so a human can inspect ownership without hunting through temporary folders. The path is disposable. The branch and commit are the durable parts.

3. Give each worktree a runtime manifest

Worktrees do not isolate the operating system. Two Next.js agents can still fight over port 3000. Two migration agents can still mutate the same database. Two browser suites can still reuse one authenticated profile and make every screenshot untrustworthy.

# .agent-runtime.local — keep this ignored
AGENT_SLOT=02
APP_PORT=3102
TEST_DATABASE=product_agent_02
CACHE_NAMESPACE=agent-02
BROWSER_PROFILE=agent-02
PROCESS_OWNER=feat/add-session-replay

Reusing a server is fine when its branch and state do not affect the check. Otherwise, isolation must be explicit. “I assumed nothing else was running” is not a resource model.

4. Put ownership rules in the agent contract

The agent should know its worktree, branch, files, validation scope, and cleanup boundary before it edits. The following contract is intentionally boring. Boring survives the seventh terminal pane.

You own this worktree and branch only.
Preserve unrelated edits.
Do not reset, clean, merge, move, or delete another worktree.
Run focused checks before handoff.
Record dirty files, commit, checks, owned processes, and next action.
Do not remove the worktree until the commit reaches the intended branch.

File ownership should also be real. If two tasks both need to rewrite the same central configuration file, either sequence them or make one agent responsible for the shared boundary. A second worktree cannot turn a logically coupled task into an independent one.

5. Validate locally, then integrate one declared snapshot

Each agent runs the cheapest checks that prove its change: a focused unit test, typecheck, formatter, or route validator. Broad builds and browser suites should run once against the combined commit set under a short-lived integration owner.

This is the part most worktree tutorials omit. Parallel implementation saves time; parallel claims about what passed destroy confidence. The full operating model—including immutable ready queues and validation leases—is in the parallel coding agents field guide.

6. Clean up without deleting somebody else's work

First prove the task commit is reachable from the intended branch. Then confirm the worktree is clean and stop only processes that task started. Run removal from the parent repository, never from a guessed path assembled by a cleanup loop.

git merge-base --is-ancestor <task-commit> origin/main
git -C .worktrees/session-replay status --porcelain
git worktree remove .worktrees/session-replay
git branch -d feat/add-session-replay

If the ancestry check fails, cleanup is not the next step. Shipping or recovery is. This single guard prevents a surprising amount of “finished” work from becoming archaeology.

Generate the setup instead of counting ports by hand

The parallel coding agent worktree planner turns task names, agent count, repository path, and a starting port into commands, runtime namespaces, and a handoff template. It runs entirely in the browser; nothing is uploaded.

Git worktree questions for coding agents