Managing Agent Worktrees in Git

Running multiple AI coding agents in parallel across shared Git repositories can avoid the need for duplicate cloning, but it introduces important operational complexities. When several automated agents work within the same repository, subtle concurrency issues can occur that may corrupt shared Git history. Managing the safe cleanup and short lifecycles of these agents, without damaging shared Git references or reflogs, necessitates clear boundaries between the modifications made in each worktree and the overall repository state.

Git worktrees share the same object database and repository reflogs, even though each worktree has its own directory. When an agent executes destructive commands like git reset --hard or git branch -D, it silently alters the history that all sibling worktrees and human developers observe. This can cause subtle, hidden changes in state that only become apparent during important rollbacks or post-mortems.

Additionally, when multiple agents start up at the same time and try to dynamically claim branch names, they can crash because Git does not allow the same branch to be checked out in more than one worktree at once. Agents often produce flawed code, failed tests, or improperly formatted diffs that must be discarded, but granting an autonomous agent permission to perform global reset operations provides it with the capability to erase commit pointers throughout the shared repository.

To prevent contamination of the reflog, agents must be strictly prevented from executing commands that modify references. Instead, agent definitions should only allow localized operations within the worktree's filesystem boundary. Whitelisting specific recovery commands ensures that the repository remains protected while still enabling the agents to clear their scratchpads.

Commands like git restore . and git clean -fd can revert changed tracked files to the HEAD of the worktree without affecting the commit history or reflogs, and git clean -fd can remove untracked build artifacts and temporary directories. This ensures that any local mistakes do not spread beyond the worktree or contaminate the shared audit trail.

When an agent encounters a catastrophic error that requires a full structural rollback across multiple commits, it should not attempt in-place recovery. Instead, the central orchestrator should treat the worktree as disposable "cattle" rather than a persistent environment. If a failure occurs, the orchestrator terminates the agent, deletes the worktree, removes worktree metadata, and provisions a new worktree from a verified canonical commit.

The orchestrator then performs external cleanup from outside the worktree, using commands such as git worktree remove --force agent-task-742 and git worktree prune. This approach completely isolates failures and avoids leaving stray locks or corrupted references in the .git/worktrees/ directory.

To completely eliminate the possibility of branch checkout collisions, agents should not be responsible for generating branch names at runtime. Instead, the orchestrator should generate deterministic, collision-free branch names before any worktree is created. By using a predictable format such as agent/task-id/timestamp, the system ensures that there are no runtime conflicts when multiple agents are initialized in parallel.

For related implementation details, see Audit MacOS System Data Before Deleting. In conclusion, safely scaling parallel AI coding agents within Git worktrees requires moving away from traditional developer practices. By separating the localized cleanup of the working tree from mutations of global references, treating broken worktrees as disposable "cattle", and pre-allocating branch namespaces centrally, engineering teams can maintain clean reflogs and reliable auditability without compromising execution speed.