Git worktrees for AI coding agents: a safe workflow.
A Git worktree gives each task its own checked-out files and current branch while sharing the repository’s objects and refs. It is a practical way to compare parallel coding-agent attempts without making them edit the same working directory.
The short answer
Give each coding-agent attempt one linked worktree, one branch and one narrow task. Start both attempts from the same recorded base commit, run Codex, Claude Code, OpenCode, Cursor or another directory-capable harness inside its assigned folder, and keep the primary checkout for review. Require committed, reviewable results before comparing them.
Choose the result that meets the acceptance criteria, pause writers, confirm the target checkout is clean, and merge through the repository’s normal review and test gate. Worktrees reduce file collisions; they are not security sandboxes. Objects, most refs, remotes and any filesystem or network access granted to the shell remain shared or reachable.
1. Create one clean worktree per attempt
Begin in the primary checkout. Confirm it is clean, update or inspect the intended base, record that exact commit once, and create both task branches from it.
git status --short
git branch --show-current
BASE_COMMIT=$(git rev-parse HEAD)
git worktree add -b agent/task-a ../agent-task-a "$BASE_COMMIT"
git worktree add -b agent/task-b ../agent-task-b "$BASE_COMMIT"
git worktree listAssign each harness its matching folder and branch. Do not point two worktrees at the same branch, and do not let task A write inside task B’s folder. The recorded base makes later comparisons reproducible even if the remote branch moves.
A separate directory does not limit shell authority. Keep credentials and host permissions as narrow as the task allows, and use a separate approval boundary for Git writes that require human control.
2. Use the same acceptance criteria
Give both attempts the same task statement, tests, constraints and recorded base. Ask each agent to keep unrelated edits out and to commit the result on its own branch. An uncommitted working tree is harder to compare and easier to lose during cleanup.
Pause the agents before review. A worktree separates checked-out files, but a broadly permitted process can still alter shared refs, contact remotes or reach files outside its task folder.
3. Compare both attempts from the recorded base
Inspect status in both task folders, then compare each branch with the same base commit. Keep that base fixed for both logs and diffs.
git -C ../agent-task-a status --short
git -C ../agent-task-b status --short
git log --oneline "$BASE_COMMIT"..agent/task-a
git log --oneline "$BASE_COMMIT"..agent/task-b
git diff "$BASE_COMMIT" agent/task-a
git diff "$BASE_COMMIT" agent/task-bReview behavior, tests, changed files and scope. Completion alone is not a reason to merge. Prefer the attempt that satisfies the criteria with the smallest understandable change.
Do not merge both attempts by default. If useful ideas are split, cherry-pick a verified commit or prepare a clean combined branch and review that new result separately.
4. Merge the chosen result through the normal gate
Return to the clean primary checkout, select one reviewed branch, and use the repository’s usual non-fast-forward review path.
CHOSEN_BRANCH=agent/task-a
git status --short
git diff "$BASE_COMMIT" "$CHOSEN_BRANCH"
git merge --no-ff "$CHOSEN_BRANCH"Keep agent writers paused while merging. Stop on any conflict, inspect it, and resolve it through the normal review process; do not let the worktree workflow turn a conflict into an automatic choice.
Run the repository’s tests after the merge and before any push. Worktrees do not replace code review, CI, protected branches or human approval, and they do not prevent a separately authorized shell from pushing.
5. Clean up without force
Inspect both worktree folders and preserve every change you intend to keep before removing either linked checkout.
git -C ../agent-task-a status --short
git -C ../agent-task-b status --short
git worktree remove ../agent-task-a
git worktree remove ../agent-task-b
git worktree list
git worktree prune --dry-runRemove a worktree without force only when its status is clean or its remaining work was deliberately discarded. Keep the task branches after removal until the review is settled; deleting a folder and deleting a branch are separate decisions.
Preview pruning before changing administrative entries. A dry run shows stale records without removing them. If Git refuses normal removal, investigate the remaining changes or lock instead of overriding the safeguard.
Inspect submodule state separately
From the trusted parent repository root, replace deps/library with the actual path. Child commands require an initialized checkout. Stop on missing or conflicted state.
git submodule status -- deps/library
Run the status command first. A + prefix means the child commit differs from the parent index; - means uninitialized and U means a conflict. Stop on - or U before running child commands.
| State | Read-only command | Meaning |
|---|---|---|
| Parent commit gitlink | git ls-tree HEAD -- deps/library | The child commit recorded in the parent HEAD. |
| Parent index gitlink | git ls-files --stage -- deps/library | The child commit currently staged in the parent index. |
| Child checkout HEAD | git -C deps/library rev-parse HEAD | The commit actually checked out in the initialized child. |
Expect gitlink mode 160000 in the parent entries. Index stage 0 is the ordinary entry; stages 1–3 indicate a conflict. Stop if the entry is missing, the mode is unexpected or the index is conflicted.
git --no-optional-locks -C deps/library status --short
Matching commits do not prove the child is clean. Inspect its uncommitted changes separately; these commands do not initialize, fetch, stage, reset or publish anything.
Official Git sources
What worktrees separate, and what they still share
| Separated per worktree | Shared or still reachable |
|---|---|
| Checked-out files, working-tree changes and local build artifacts | Repository objects and most refs |
| Current branch plus per-worktree HEAD and index state | Remotes, credentials and shared repository configuration |
| Task directory used by the selected harness | Anything a broadly permitted shell can reach outside that directory |
Use worktrees for parallel files, clearer diffs and repeatable comparison. Use permissions, protected branches, review and approval controls to govern authority.
Compatibility depends on whether a harness can operate in a chosen directory and respect the task boundary. The workflow is suitable for directory-capable tools; it is not proof that every harness provides the same controls.
Official Git sources
Compare parallel attempts without giving up review control.
FluxGit can show linked worktrees and repository state, compare changes, and keep supported agent Git write proposals behind desktop approval. A separate shell keeps the access granted by its host.