10 Essential Git Configs for Parallel AI Coding Agents

Title

10 Essential Git Configs for Parallel AI Coding Agents

Meta Description

When multiple AI coding agents run in parallel, Git worktrees share the same config file by default, causing identity and settings to pollute each other. Based on official Git docs, this article covers 10 must-set configs including identity isolation, conflict readability, push strategy, rebase stacked branches, and worktree cleanup.

Article Content

When multiple AI coding agents run in parallel in separate Git worktrees, an easily overlooked fact is that by default, all worktrees share the same repository config file. The first agent that runs git config user.email rewrites the identity for all three tasks. Based on official Git documentation, this article compiles 10 config options that should be set before launching parallel coding agents, covering identity isolation, conflict readability, push/pull behavior, and worktree cleanup.

Why Worktree Configs Need Special Handling

The Git worktree documentation says only one thing about this: "By default, the repository config file is shared across all worktrees." This means config set for one task leaks into all tasks. Even more troublesome is that agents usually don't check this proactively—they just run git config as usual and continue working.

The solution is to enable the extensions.worktreeConfig extension, after which config written with the --worktree flag is stored in $GIT_DIR/config.worktree and overrides same-named settings in the shared file. This way each task can have an independent commit identity, and git log --author=codex can precisely find a specific agent's commits. Two things to note: if the shared config contains core.bare or core.worktree, move them to the main worktree's config.worktree first; also, older Git versions will refuse to access repositories with this extension enabled.

`extensions.worktreeConfig` is a repository-level extension config introduced in Git 2.20 to enable the `config.worktree` file. Once enabled, Git loads config in order: the shared `.git/config` and then each worktree's own `.git/worktrees/<id>/config.worktree`, with same-named keys in the latter overriding the former. Note that once this extension is enabled, older Git versions (below 2.20) will outright refuse to operate on the repository, so in team collaboration or CI environments you must confirm all nodes have a sufficiently new Git version. Additionally, the `core.bare` and `core.worktree` keys conflict with the worktree mechanism itself, and Git docs explicitly require migrating them from the shared config to the main worktree's `config.worktree`, otherwise path resolution anomalies may occur.
# Run once per repository
git config extensions.worktreeConfig true

# Inside a specific task's worktree
git config --worktree user.name "Codex (fix-login)"
git config --worktree user.email codex@example.com

Making Agent-Generated Conflicts Easier to Read

Conflict Style: zdiff3

The default merge conflict style only shows "your version" and "their version", dropping the original text. When two agents rewrite the same function, the original version is exactly the key to judging who changed what. zdiff3 builds on diff3 by further trimming identical lines on both edges of the conflict, focusing the diff. Files already in conflict state can regenerate markers with git checkout --conflict=zdiff3.

Diff Algorithm: histogram

Git's ort merge strategy uses histogram alignment for changes by default, but regular diff still defaults to the Myers algorithm. This means the diff you see when reviewing code may pair lines differently from how the actual merge lands. Empirical research (Nugroho, Hata, Matsumoto in Empirical Software Engineering) indicates that Histogram is better suited than Myers for presenting code changes in patch application scenarios. Setting diff.algorithm to histogram makes review and merge use the same logic.

Duplicate Conflicts: rerere

When two agent branches touch the same lines, the same conflict may need to be resolved repeatedly across trial merges, rebases, and the next rebase. rerere.enabled records the first resolution and automatically replays it afterward. The cache lives in the rr-cache directory, which is shared across the repository, so a conflict resolved in one worktree can be reused in others. Default cleanup is after 60 days; if a record is wrong, undo it with git rerere forget <file>.

rerere stands for "reuse recorded resolution" and is Git's built-in conflict resolution caching mechanism. Its workflow: when a merge or rebase produces a conflict, Git uses a normalized hash of the conflict region as the key and stores the manually resolved result as the value in the rr-cache directory; when the same hash conflict appears later, the recorded resolution is applied automatically. rerere.enabled only enables recording and auto-replay; if you want resolved files auto-staged (saving manual git add), also set rerere.autoUpdate true. rr-cache lives under the shared .git directory, so it naturally works across worktrees—highly relevant to the parallel agent scenario emphasized in this article.

Push and Pull Without Interrupting Agents

Each task branch is newly created with no upstream tracking branch. Under the default push.default=simple, an agent's first plain git push will fail, and it has to figure out --set-upstream itself. With push.autoSetupRemote enabled, pushing when the current branch has no upstream automatically establishes tracking.

Agent branches are short-lived. After a PR merges and the server deletes the branch, the local clone still keeps refs like origin/hermes/fix-login. Over weeks, git branch -r fills up with remote branches that no longer exist. fetch.prune cleans up these stale refs on every fetch.

Handling Stacked Tasks and Viewing the Latest Branch

Task B sometimes starts from task A's branch rather than main. After rebasing B, A remains on the old commit. rebase.updateRefs is equivalent to enabling --update-refs by default, forcing updates to branches pointing at rebased commits. But the docs immediately note: "Branches checked out in a worktree will not be updated this way." If A's worktree is still open, A won't advance. You need to finish or remove A's worktree first, or use git -C ../task-a switch --detach to detach it.

git branch sorts by name by default, so just-finished tasks get buried in the middle of the hermes/* list. Setting branch.sort -committerdate sorts by commit time descending, putting the latest work first. In the list, * marks the current branch and + marks branches checked out in other worktrees.

rebase.updateRefs corresponds to the git rebase --update-refs option, available since Git 2.38. When enabled, rebase detects which local branches' tip commits fall within the rewritten commit range and, after rebase completes, moves those branch refs to the corresponding new commits, preventing stacked branches from still pointing at old history after their base changes. However, for safety Git won't automatically move branches currently checked out in any worktree—because moving the ref would make that worktree's HEAD inconsistent with its working tree contents. This is exactly what the docs mean by "branches checked out in a worktree will not be updated this way," and it's why stacked tasks need extra handling in the parallel agent scenario.

Creating and Cleaning Up Worktrees

worktree.guessRemote

If an agent pushed fix-login on another machine and you want to check it out in a local worktree, a plain git worktree add ../fix-login will create a same-named branch from the current HEAD, completely missing the agent's commits. worktree.guessRemote makes Git find a remote tracking branch that "uniquely matches the new branch name" and check it out with upstream set. Note it matches by folder basename, so names with slashes like hermes/fix-login won't match and require explicitly specifying the branch name.

Cleaning Up Stale Records

Deleting worktree folders with rm -rf instead of git worktree remove leaves admin files in .git/worktrees, and git worktree list will still show them marked as prunable. By default git gc runs git worktree prune --expire 3.months.ago, so these records linger for three months. Setting gc.worktreePruneExpire to a shorter period cleans them up faster. Pruning only deletes Git's records, never actual files. For worktrees mounted on external drives, you can lock them with git worktree lock to prevent accidental cleanup; locks also block move and remove operations.

git worktree prune cleans the admin directories under .git/worktrees/, not the actual files in the working tree. Each worktree has a directory under .git/worktrees/<name>/ containing a gitdir pointer; when the worktree folder is manually deleted, that pointer becomes invalid and the corresponding record becomes "prunable". The --expire parameter sets the expiration threshold, only cleaning records whose last modified time is older than that threshold, controlled by gc.worktreePruneExpire by default (three months). Setting gc.worktreePruneExpire to now cleans all stale records immediately on each git gc; 2.weeks.ago keeps a two-week buffer, suitable for scenarios where parallel agents frequently create and destroy worktrees.

One-Time Setup Script

The following nine items are set globally, and the first item is run per repository:

git config --global merge.conflictStyle zdiff3
git config --global diff.algorithm histogram
git config --global rerere.enabled true
git config --global push.autoSetupRemote true
git config --global fetch.prune true
git config --global rebase.updateRefs true
git config --global branch.sort -committerdate
git config --global worktree.guessRemote true
git config --global gc.worktreePruneExpire 2.weeks.ago

# Per repository
git config extensions.worktreeConfig true

This configuration doesn't depend on any specific tool. Whether you use Hermes IDE, Claude Code, or another agent framework, as long as agents work in worktrees, the shared config problem exists and these settings will apply. The author of Hermes IDE noted in the original article that when a task starts it creates an independent hermes/<name> branch and worktree—these are ordinary Git structures, so the configs apply as usual when manually diffing, rebasing, and merging.

One-line Summary

Parallel AI coding agents share Git config and overwrite each other's identity; use worktreeConfig to isolate and adjust nine global settings.

Paragraph Summary

When multiple AI coding agents work in parallel in separate Git worktrees, they share the same repository config by default, causing identity, push, and other settings to overwrite each other. Based on official Git docs, this article compiles ten configs to set before launching agents: use extensions.worktreeConfig with --worktree for per-task identity; use zdiff3 conflict style, histogram diff algorithm, and rerere to improve conflict readability and reuse; use push.autoSetupRemote and fetch.prune to fix first-push failures and remote branch buildup; use rebase.updateRefs for stacked tasks (but checked-out branches won't update automatically); use branch.sort to order branches by commit time; use worktree.guessRemote to correctly check out remote branches; use gc.worktreePruneExpire to shorten retention of stale worktree records. A one-time setup script is provided at the end, emphasizing the solution doesn't depend on any specific agent tool.