Git

Parallel Worktrees + Clash-Style Conflict Prediction: Catch Overlapping Agent Edits Before the Merge Queue Breaks

Sahil Kathpal

• 3 min read

Git worktrees make it easy to run several coding agents in parallel. They do not make the resulting branches compatible. If three agents edit the same files, the merge queue becomes the first place you discover the collision.

A lightweight "clash predictor" can catch overlapping edits earlier by comparing each agent branch's changed files, hunks, symbols, and dependency areas before review.

The short version

  • Worktrees isolate working directories, not product intent.
  • Predict conflicts before merge by comparing changed paths and diff hunks across agent branches.
  • File overlap is a useful first signal; hunk and symbol overlap are better.
  • Run the predictor continuously and post warnings to PRs or the task board.
  • The goal is not perfect prediction. It is earlier rerouting of agents and reviewers.

Why worktrees need coordination

A worktree gives each agent its own checkout and branch:

git worktree add ../app-agent-a -b agent/a main
git worktree add ../app-agent-b -b agent/b main
git worktree add ../app-agent-c -b agent/c main

That is enough to prevent filesystem races. It is not enough to prevent semantic races. Agent A might rename a function while Agent B adds a call site. Agent C might update tests based on the old behavior. All three branches look fine alone and fail together.

Humans solve this with communication: "I'm touching billing limits; don't refactor billing today." Agents need a mechanical version.

Start with changed-path overlap

The simplest predictor compares branch diffs against a common base:

base=origin/main
for branch in agent/a agent/b agent/c; do
  git diff --name-only "$base...$branch" | sort > "/tmp/$branch.files"
done

comm -12 /tmp/agent/a.files /tmp/agent/b.files

If two branches edit the same file, flag it. This catches many real conflicts and is cheap enough to run on every push.

But file overlap is noisy. Two agents can safely edit different sections of a large test file. Conversely, two branches can edit different files and still conflict semantically.

Use path overlap as a yellow flag, not a red light.

Compare diff hunks

A better predictor compares line ranges. Parse git diff --unified=0 for each branch and record changed intervals:

branch: agent/a
file: packages/billing/src/limits.ts
changed: 42-58, 91-93

branch: agent/b
file: packages/billing/src/limits.ts
changed: 55-70

Overlapping or nearby hunks should trigger a stronger warning than same-file overlap. "Nearby" matters because agents often insert helper functions or imports close to each other, producing conflicts even when ranges do not exactly overlap.

A practical scoring model:

+10 same file
+30 overlapping hunk
+15 hunks within 20 lines
+20 both modify imports in same file
+25 both modify package lockfile
+40 one branch renames a symbol the other touches

Anything over a threshold gets posted as a clash warning.

Add symbol-level signals

For TypeScript, Python, Go, Java, and similar languages, symbol overlap is often more useful than line overlap. Use Tree-sitter, language server output, or a simple parser to map changed hunks to functions/classes.

Example warning:

Potential clash: agent/a and agent/b both modify BillingLimitService.checkLimit
- agent/a changes archived project counting
- agent/b changes Enterprise override behavior
Recommended action: merge agent/a first, rebase agent/b, rerun billing tests.

This gives reviewers a routing decision instead of a vague "conflict likely."

Detect semantic collision zones

Some files are natural collision magnets:

  • lockfiles;
  • generated API clients;
  • database schema files;
  • routing tables;
  • central type definitions;
  • monorepo package manifests;
  • snapshot files;
  • migration directories.

Maintain a clash-zones.yml file:

high_risk:
  - package-lock.json
  - pnpm-lock.yaml
  - packages/api/src/routes/**
  - db/migrations/**
  - packages/shared/src/types/**

owners:
  packages/billing/**: billing
  packages/auth/**: security

If two active branches touch the same high-risk zone, warn even without same-file overlap.

Feed the predictor into the workflow

The predictor is most useful before PR review. Run it when:

  • an agent opens a draft PR;
  • an agent pushes new commits;
  • a task moves to "ready for review";
  • a merge queue entry fails due to conflicts.

Post a concise comment:

### Clash warning
This PR overlaps with `agent/billing-refactor`.

Shared files:
- `packages/billing/src/limits.ts` overlapping hunks around lines 50-70
- `packages/api/test/projects.test.ts` same file, non-overlapping hunks

Suggested order:
1. Merge this PR first.
2. Rebase `agent/billing-refactor`.
3. Rerun `npm test -- billing projects`.

Do not block every warning. Use labels such as clash:low, clash:medium, and clash:high so teams can choose policy.

Gotchas

Git merge conflicts are not the only failures. Two clean merges can still break behavior. Pair clash prediction with tests that cover integration boundaries.

Generated files create noise. Prefer comparing source inputs when possible and regenerate after merge.

Long-running branches become stale quickly. Rebase agent branches frequently or have agents start from the current integration branch.

The predictor must know active branches. Delete old worktrees and close abandoned PRs or the warning system becomes useless.

We're building Grass for this kind of parallel agent workflow, where isolated sandboxes make it easier to run work concurrently while still bringing results back for review. Conflict prediction and reviewable outputs matter because throughput only helps if the merge path stays sane. You can try Grass at https://codeongrass.com.

Conclusion

Worktrees unlock parallel agent throughput, but they move coordination problems to merge time. A clash predictor gives you an earlier signal by comparing paths, hunks, symbols, and high-risk zones across active branches. It will not prove merges are safe, but it will keep the merge queue from being your first conflict detector.

Sources

  • Git worktree documentation and common parallel-agent workflows
  • Engineering reports on using worktrees for parallel AI agent execution