Managing Agent Worktrees in Git

Running parallel AI coding agents across shared repositories via Git worktrees prevents duplicate cloning, but it exposes critical operational edge cases. When multiple automated workers operate simultaneously within the same repository infrastructure, subtle concurrency conflicts can compromise shared history. Managing safe cleanup and ephemeral lifecycles for these parallel AI coding agents without corrupting shared Git refs or reflogs requires strict boundaries between working tree modifications and global repository state. For a related implementation, see Shared Git State In Parallel Agent.

The Silent Hazard of Shared Git State

Git worktrees share the underlying object database and repository reflogs, even though they maintain separate working directories. When an agent runs a destructive command like git reset --hard or git branch -D, it silently mutates history that every sibling worktree and human developer observes. This creates insidious, invisible state drift that only surfaces during high-pressure rollbacks or post-mortems.

Furthermore, when multiple agents spawn simultaneously and attempt to claim branch names dynamically at runtime, they crash because Git strictly refuses to check out the same branch in more than one worktree at a time. Agents frequently produce broken code, failed test runs, or malformed diffs that require discarding, but giving an autonomous agent access to global reset commands gives it the power to destroy commit pointers across the entire shared repository.

The Command Boundary

To prevent reflog contamination, agents must be strictly prohibited from executing ref-mutating commands. Instead, agent tool definitions only permit scoped working tree operations that isolate changes to the local filesystem boundary. Whitelisting specific recovery commands protects the underlying repository while still giving workers the ability to clear their scratchpads.

git restore .
git clean -fd

Running git restore . reverts modified tracked files back to the current HEAD of that worktree without touching commit history or reflogs. Meanwhile, git clean -fd purges untracked build artifacts and scratchpad directories. This guarantees that local mistakes cannot leak beyond the worktree boundary or pollute the shared audit trail.

The Cattle Pattern for Agent Worktrees

When an agent encounters a catastrophic error requiring a full structural rollback across multiple commits, the agent does not attempt in-place recovery. The central orchestrator treats the worktree as disposable cattle rather than a persistent environment.

When a failure occurs, the orchestrator terminates the agent, forcefully deletes the worktree, prunes worktree metadata, and provisions a fresh worktree from a verified canonical commit.

# Orchestrator-managed cleanup from outside the worktree
git worktree remove --force agent-task-742
git worktree prune

This external destruction pattern isolates failures completely. By executing these commands from the parent control plane, the system avoids leaving dangling locks or corrupted references in the .git/worktrees/ directory.

Deterministic Scheduling

To completely eliminate branch checkout races, branch naming must be removed from the agent’s responsibility entirely. If agents generate branch names at runtime, simultaneous requests inevitably collide.

The orchestrator should instead generate deterministic, collision-free branch names before any worktree is created. By assigning namespaces using a predictable format such as agent/<task-id>/<timestamp>, the system ensures zero runtime conflicts during parallel initialization. For a related implementation, see Audit Macos System Data Before Deleting.

Conclusion

Safely scaling parallel AI coding agents inside Git worktrees requires shifting away from manual developer habits. By separating scoped working tree cleanup from global reference mutations, treating broken worktrees as disposable cattle, and pre-allocating branch namespaces centrally, engineering teams can maintain clean reflogs and reliable auditability without sacrificing execution speed.