Version Control for AI Coding Agents Starts Above Git

The first sign is usually a merge conflict nobody can resolve. Two agents, one shared checkout, both mid-refactor, and a diff entangled past any human's attention span. The second sign is the pull request: eleven files, 1,400 changed lines, one logical idea, opened four minutes after the last one merged. Version control for AI coding agents fails at moments like these, and the cause sits below tooling and below model quality. Git's unit of exchange is a file-scoped, line-based diff built for human review. Agents ship multi-file logical transformations at machine cadence, and the four things you need to trust that output (intent, isolation, environment state, provenance) all live outside Git's object model.

You can close those gaps this quarter with a layer assembled from stock Git and CI. Better still, the places where that layer leaks write the requirements spec for whatever eventually replaces Git. Diagnosis, stack, spec, in that order.

Why Git Strains as Version Control for AI Coding Agents

Most commentary skips a distinction that matters: Git's storage layer and Git's exchange layer disagree about what a change is.

Storage holds up. Git is a content-addressed database of snapshots; commits point to trees, trees to blobs, and every object is named by a hash of its contents, as the Git internals chapter lays out. Nothing about agent workloads breaks blobs and trees.

Exchange is where it hurts. Diffs, patches, pull requests, revert, cherry-pick, blame: nearly every artifact through which a team extends trust operates on textual, file-scoped deltas between those snapshots. A single logical change, say renaming a function and touching its 30 call sites, has no first-class object in this model. It exists as a scatter of per-file hunks plus a commit message hoping someone reads it. That is why git diffs break with AI coding agents in ways they never did with human contributors: people pre-chunked work into reviewable units because they had to persuade each other. Agents removed the human packing step and kept the human review step.

The sharpest public version of this diagnosis is O'Reilly's files-to-systems argument: agents reason over call graphs and syntax trees while Git versions flat text. Correct, as far as it goes. It also stops exactly where the engineering starts, which is the rest of this piece.

Four Mismatches Between Git and Agent Workflows

Version control for AI coding agents breaks along four seams where machine cadence meets a human-shaped exchange model. Each mismatch below pairs a design assumption with the failure mode it produces.

Line Diffs Versus Multi-File Logical Changes

Real fixes sprawl. The SWE-bench benchmark is built from 2,294 real issue and pull request pairs drawn from a dozen Python repositories, precisely because resolving a genuine issue means editing source, tests, and sometimes config together. Agents reproduce that shape, minus the human habit of splitting it into digestible commits. When one logical change lands as textual deltas across many files, every tool that reasons about deltas misfires at the logical layer.

Failure mode. An agent implements one idea across three commits that also carry unrelated tidy-up. git revert inverts the middle commit's textual patch and leaves the refactor half-landed. Reverting the files did not revert the change.

Review Units Sized for Human Attention

Google's small-changelist guidance tells engineers to keep changes small, with roughly 200 lines as a working threshold, because reviewers stop catching defects in large diffs. Agent-authored pull requests blow through that ceiling as a matter of course, and mainstream tooling industrializes the flow: GitHub's Copilot coding agent opens draft pull requests from assigned issues with no human in the write loop at all.

Failure mode. The review queue becomes the constraint. Every gain in agent capability raises demand on the scarcest resource in the loop, senior reviewer hours. Past a point, code review for AI agents, not agent quality, sets your throughput ceiling.

Environments and Tool State Outside Version Control

Git versions files. It does not version the installed toolchain, an applied database migration, a mutated container, or the agent's tool state. An agent run is generally not reproducible from the repository alone.

Failure mode. The agent's run passed because its sandbox had a newer compiler and a migration it applied by hand. CI fails, teammates fail, and "it worked in the agent's environment" becomes the new "it worked on my machine." That is a data-model gap, not a discipline gap.

No Provenance From Prompt to Commit

Nothing in the object model records which prompt, session, model, or tool call produced a commit. Postmortems can establish what changed and when.

Failure mode. You cannot answer which agent run caused a regression, whether the same prompt reproduces it, or what the agent tried and discarded along the way. You cannot audit what you cannot replay, and you cannot replay what you never recorded.

The Workaround Stack You Can Ship This Quarter

Practical version control for AI coding agents this year means a layer over Git, not a replacement for it. Five components, each deployable on its own, each closing one seam above.

1. Per-Agent Worktrees for Collision-Free Isolation

A git worktree per agent setup gives every agent its own working directory bound to its own branch inside one shared repository, using stock Git (2.5 and later) per the official git worktree docs:

git worktree add ../agents/retry-budget -b agent/retry-budget-731
# the agent works here; it cannot see or clobber another agent's checkout
git worktree remove ../agents/retry-budget

Git worktree isolation deletes the shared-checkout collision class entirely. Two concurrent agents cannot entangle uncommitted state because neither sees it. The cost is disk and branch hygiene, addressed below.

2. A Machine-Readable Change Manifest

Commit a manifest next to the change that states the logical layer explicitly: intent, file groupings, and evidence. The Conventional Commits spec got halfway there by making commit messages machine-parseable; a manifest finishes the job for multi-file changes.

{
  "run_id": "ar_8f31c2",
  "intent": "Add retry budget to the payment client",
  "groups": [
    { "name": "core",  "files": ["pay/client.go", "pay/retry.go"] },
    { "name": "tests", "files": ["pay/client_test.go"] }
  ],
  "evidence": { "command": "go test ./pay/...", "result": "pass" }
}

Review now starts from "one logical change in two groups" instead of eleven files of hunks. The manifest restores the intent boundary the diff layer drops.

3. Snapshot Checkpoints With a Pinned Environment

Instruct agents to commit a WIP snapshot before risky steps: before a rename cascade, before a migration, before "trying a different approach." Record the environment with each checkpoint, a lockfile checksum, container digest, or flake lock, so the snapshot means something. Declarative tooling such as declarative development shells pins the whole toolchain so two runs of one commit see the same compiler.

Snapshot checkpoints for agent runs turn "what did the agent try before this worked" from archaeology into git log. Squash on merge to keep main readable.

4. Run IDs and Prompt Hashes in Commit Trailers

Git trailers, the Key: value block at the end of a commit message, are the cheapest provenance mechanism in the ecosystem:

Agent-Run: ar_8f31c2
Prompt-SHA256: 9c1f44e0...
Model: <model-id>@<version>
Tools: <agent-version>

This is prompt-to-commit traceability: link agent prompts to commits, and every commit can answer what was asked and of which model. It is comparable in spirit to SLSA provenance attestations, with one caveat. Trailers report whatever wrote them, so verification belongs to CI.

5. CI Gates That Enforce the Contract

None of it survives contact with a rushed agent unless CI makes the contract load-bearing:

• Manifest present on agent branches, and its file list matches the actual diff
• Trailers present, non-empty, and consistent with the manifest's run ID
• Environment hash pinned and resolvable
• Declared test command executed, with the result recorded

Trust structure mechanically. Trust content only after review.

Where the Workaround Stack Leaks

Honest accounting, component by component, with the requirement each leak generates tagged on the end:

• Worktree sprawl. Every worktree is a full working tree. Ten concurrent agents on a large monorepo means real disk and real cleanup duty; git worktree prune belongs in a scheduled job. Feeds requirement 5, concurrency beyond branches.
• Manifest drift. CI can verify the manifest names exactly the files in the diff. It cannot verify that the intent summary is honest. A manifest written after the diff is a confession, not a contract. Feeds requirement 2, machine-first metadata.
• Checkpoint weight. WIP commits clutter branch history for anyone reading it raw, and snapshots capture only Git-visible state. A row the agent migrated in a database is in no snapshot. Feeds requirement 3, environments as versioned artifacts.
• Trailer trust. Trailers are as honest as the harness writing them. Provenance written by the agent is marketing; provenance written by the wrapper and verified by CI is evidence. Feeds requirement 4, provenance by default.
• Review stays the bottleneck. The manifest renders intent, and a human still judges it. Stacked diffs and machine pre-review help at the margins. This stack makes agent work auditable, not small. Feeds requirement 7, review decoupled from file counts.

Five leaks, five numbered requirements. The next section writes out all eight: these five lines supply five of them, and the mismatches above plus the substrate case at the end account for the other three.

A Requirements Spec for Agent-Native Version Control

Eight requirements for agent-native source control fall straight out of the leaks above. Steal this for a tool evaluation or an internal RFC:

#	Requirement	What it must guarantee
1	Logical change units	A change is addressed by intent, not file list; revert and cherry-pick operate on the whole logical unit
2	Machine-first metadata	Manifests and attestations are native objects; line diffs are rendered for humans on demand
3	Environments as versioned artifacts	Dependencies, migrations, and tool state are pinned and hashed per commit
4	Provenance by default	Every agent commit carries run ID, prompt hash, model, and tool versions
5	Concurrency beyond branches	Dozens of agents work one repository without branch algebra
6	Replayable runs	Commit plus environment plus prompt re-executes deterministically
7	Review decoupled from file counts	Review units are logical chunks, machine-prechecked and human-judged
8	Substrate compatibility	Content addressing and Git protocol interop survive, because the ecosystem will not migrate twice

Score any self-described Git replacement against all eight. Anything failing more than two is a prototype wearing a manifesto, and anything that passes was probably built by someone who ran the workaround stack first and felt every leak.

A 30-Day Rollout and What Git Still Gets Right

Week	Focus	Exit criterion
1	Worktree isolation	Every agent runs in its own worktree and branch; zero shared checkouts
2	Traceability	All agent commits carry trailers; spot-check ten commits resolve to prompts
3	Manifests plus CI gates	An agent PR without a consistent manifest cannot merge
4	Environment pinning and checkpoints	Agent branches carry an env hash; risky steps are preceded by a WIP snapshot

This is the AI coding agent workflow change you can land in a month, and it leaves Git's genuine strengths intact. Content addressing gives integrity and deduplication that successor designs quietly re-invent. Ecosystem gravity is real: every CI runner, IDE, and security scanner speaks Git. Even the platform layer is reinforcing that substrate rather than abandoning it, as GitHub's new storage architecture shows, re-engineered for write-heavy repository growth, the kind of traffic agent activity produces. Read that as an acknowledgment that agent workloads strain current assumptions, one that keeps the Git interface intact.

So no, replacing Git outright is not the near-term play. Layer agent-native semantics over the content-addressed substrate, run the layer until its leaks are familiar, and you will have written the real spec. When a candidate arrives promising to end the Git era, hand it the eight requirements and your own leak list. If it earns the migration, you will recognize it, because it will look like your layer with the leaks closed.