Two AI agents in one Git repository without overwriting each other
We put Claude and Codex on the same small business repository. They have different sessions,
different tool access and no shared conversation. Both can commit to main.
The first useful result was not twice as much code. It was a protocol that stopped one agent from confidently finishing work against a repository the other agent had already changed.
This is what survived three real handoffs: one agent found 27 portability problems in a ZIP, the other fixed them, the first rebuilt the exact artifact in a clean directory and reduced the result to seven real failures, then the second fixed those and deployed the guide written by the first. No coordinator copied messages between them.
Git is the audit trail, not the shared brain
An agent does not know what another agent learned merely because a file appeared on disk. The same context gap is described in Claude Code issue 5812: a parent can know that a delegated task finished without receiving the contents and reasoning needed for the next step.
Git does not solve context propagation. It solves a smaller problem well: what changed, who changed it, and which exact state was tested. We pass only the durable artifact and the minimum handoff around it. Each agent re-reads what it actually needs.
The protocol
1. Fetch before choosing work
git pull just before a push is too late. The agent may spend an hour solving a task that
was already completed upstream. Every session starts with:
git fetch origin
git status --short --branch
git log --oneline HEAD..origin/main
If the local tree is clean, fast-forward. If it is not, inspect the changed filenames before touching anything. Never hide unknown work in a generic stash and hope the pop is sensible.
2. Give every mutable area one owner
Our boundary is deliberately boring. One agent owns operational state, reports, production deploys and social accounts. The other owns new guides, tools, portability checks and research notes. Both may read everything.
This matters more than model choice. Two excellent agents writing the same JSON file can produce a perfectly valid file that silently loses one update.
State gets an even stricter rule: one writer script per type. The cash ledger changes through the ledger command; the event journal changes through the journal command. Agents do not edit those files by hand.
3. Keep a tiny mailbox in the repository
We use one Markdown file with four sections:
## Agent A took
## Agent A delivered
## Agent B delivered
## Agent B asks
One line contains the date, concrete result and file or commit. A request says what evidence will close it. “Please investigate” is not a handoff. “Rebuild this ZIP in a fresh folder, run these two gates and record which of seven findings remain” is.
The mailbox is not project memory and not a transcript. Completed lines make duplicate work obvious; the source files and commits contain the detail.
4. Make small commits identify the agent
Our commits start with Codex: when Codex writes them. Claude uses its normal descriptive
prefix. The purpose is operational, not ceremonial: before editing a shared coordination
file, an agent can see whether the last change came from its partner and read that diff first.
A handoff commit should contain one reviewable result. Do not mix a new guide, a ledger correction and a scheduler rewrite because they happened in one session.
5. Let the receiver verify, not applaud
The second agent does not close a task because the first says a test is green. It repeats the test from the boundary a user will see.
For our toolkit that meant building the release ZIP, extracting it under a never-used path, copying only the files named by the README, using empty secrets and pasting every command literally. The first fix made the scanner green only after false positives were removed. The full sandbox then exposed a separate JSON regression. The handoff worked because “green” was an instruction to verify, not a fact to inherit.
6. Assign external side effects to the agent that can prove them
One agent had Cloudflare credentials; the other did not. The second prepared and committed a page, then requested a deploy. The first deployed and recorded the production URL, HTTP 200, expected title and indexing result.
Tool output saying “deployed” is not proof. The receiving agent fetched the public URL again. The same rule applies to comments, payments and emails: record an external identifier or read the resulting state before calling the action complete.
The conflict we actually hit
Both agents changed the mailbox while one branch was two commits behind. The safe resolution
was possible only because the local edit was known and tiny: discard that one local mailbox
change, fast-forward, then reapply the new line against the current structure. We did not
restore the whole repository, reset main or overwrite the remote file.
If both edits are substantial, stop using one shared branch. Give each agent a branch or worktree and merge through a review. Ownership reduces conflicts; it does not make concurrent edits to the same lines intelligent.
Minimum files
You do not need an orchestration framework. Start with:
AGENTS.mdor equivalent: permanent boundaries and commands;collaboration/TASKS.md: taken, delivered and requested work;- an append-only event journal written by one script;
- one automated check that both agents run before handoff;
- Git commits small enough to revert independently.
Add message queues and distributed locks only when the repository protocol fails under real load. Our first failure was not lack of infrastructure. It was a hard-coded path that both agents would have trusted if the second one had not installed the product as a stranger.
The metric that tells you whether two agents help
Do not count commits. Track duplicate tasks, merge conflicts, human interventions and the time from request to independently verified result. Two agents are useful when the second agent catches assumptions and shortens that loop. They are expensive theatre when they both produce artifacts and a human still has to reconcile every decision.