Git as the Communication Layer for AI Agents

A year ago "multi-agent" meant one model in a loop. Now it means a Claude Code session writing a branch while Codex reviews it, a third agent runs the long task, and a human steps in to redirect — often on different machines, rarely all awake at the same second. The hard part is no longer making one agent competent. It is getting several of them to coordinate without losing the thread: who asked for what, which risk was already flagged, who owns the next step, what counts as done.

Most teams answer this with the chat window. That works until the session ends. The ask, the review note, the "I already handled that" — all of it lives in a transcript that is not attached to the branch it was about, and is gone the moment the context resets. Coordination state that does not survive the session is not coordination state; it is a conversation you have to reconstruct.

This article makes a narrower claim than "use Git for everything." It is that the coordination channel for asks, reviews, risks, and handoffs should live next to the artifact — the branch, the commit, the file — and that a single Git ref, written with compare-and-swap and reconciled with union-merge, gives you a lossless multi-writer mailbox with no server to run. You already know Git's basics; the part worth your attention is why those two mechanics turn an append-only ref into a mailbox, and where that trade is wrong. Git-native handoffs are also one of the coordination pillars inside an auditable workspace: every ask, review, risk, and handoff recorded in the repo, provable after the fact.

Why a ref is the substrate, not a server

Strip the messaging idea down and you are choosing where coordination state lives. The candidate properties you want: it travels with the code, it survives a machine or a session, it cannot be silently rewritten, and it needs no always-on service. A Git ref has all four, and you did not have to build any of it.

• It travels with the code. A ref is part of the repository. Clone the repo, fetch the ref, and the coordination history comes with it — on a laptop, in CI, in a sandbox. The conversation is co-located with the branch it is about, not in a separate product that has to be cross-referenced by hand.
• It is content-addressed. Every message commit is identified by the hash of its contents. Tampering is detectable by construction; "what did the reviewer actually say" has a cryptographic answer, not a vendor's word.
• It is append-only by discipline. The log only ever grows. Nothing in the normal write path edits an earlier message, which is exactly what makes the history replayable and exactly what makes the next mechanic safe.
• It needs no central service. Two agents on two machines coordinate through the same remote they already push code to. There is no broker to provision, secure, scale, or page someone about at 3am.

h5i builds on this directly: cross-agent messages live in refs/h5i/msg as an append-only messages.jsonl (one JSON message per line) plus an agents.json roster. They move with h5i share push and h5i share pull — they are not carried by a plain git push, which only moves refs/heads/*. (For the on-the-wire field layout — version, kind, reply_to, thread_id, priority, focus, risk, links — see the i5h protocol deep dive; this post stays at the substrate altitude.)

A Git ref as a lossless multi-writer mailbox

Here is the part that is not obvious. A single ref looks like a single-writer thing — it points at one commit, and a naive "read tip, write new commit, move ref" loses data the moment two agents do it at once. The trick is two mechanics working together: compare-and-swap on write, union-merge-by-id on reconcile.

Compare-and-swap on send

A send does not blindly move the ref. It reads the current tip, builds a new commit that appends one line to messages.jsonl off that tip, and then moves the ref only if it still points where it was read. If a concurrent writer in the same clone moved the tip first, the swap fails; the sender re-reads the new tip and retries. h5i's append_message_cas loops this up to 64 times — a writer would have to lose that many consecutive races to error — so bursty concurrency (several agents sending into one clone at once) never silently drops an append. This is the standard optimistic-concurrency pattern, applied to a ref instead of a database row: no locks, no broker, and no lost write under contention within a clone.

Union-merge-by-id on pull

Compare-and-swap solves contention inside one clone. It does nothing for two agents on two machines who both committed off the same tip and pushed — that is a genuine divergence, and a fast-forward-only push would reject one of them. Here the append-only discipline pays off. Because no message is ever edited, the two messages.jsonl blobs are two sets of immutable lines, and reconciliation is set union keyed by message id. h5i's union_merge_commits takes the union of both message sets (de-duplicating by id), then sorts the result into a stable (timestamp, id) order; the two rosters merge by keeping the latest last-seen per agent. Neither side's messages are clobbered — you end up with both.

Why this is lossless: a message is identified by its id, and union never discards a line that exists on either side. Two agents can write blind to each other and, after a pull, both messages are present. What it costs is precise, and worth stating plainly:

• You must pull to see new mail. There is no push from the ref to you. Delivery is eventual — a message exists the instant it is committed, but you observe it only after a fetch + merge. This is eventual consistency, not real-time.
• Ordering is per-id merge, not a global clock. The merge sorts by timestamp, but timestamps come from independent machines with independent clocks. There is no total order you can trust for causality. If message B is a reply to A, the only reliable way to know that is the data itself — which is why every message carries thread_id and reply_to, so causal order rides on explicit links, not on wall-clock luck.

In practice the command surface hides all of this. You send typed messages — ask, review, risk, handoff, and the typed replies reply, ack, done, decline — addressed to one agent or broadcast to all. Identity comes from $H5I_AGENT (Claude Code sets it to claude), so no --from is needed in the common case.

$ h5i msg review --branch auth --focus src/auth.rs codex "review token refresh edge cases"
$ h5i msg risk --priority high all "billing cache crosses tenants"
$ h5i msg done 1 "fixed in 8f21c3a"
$ h5i share push   # refs/h5i/msg does not ride a plain git push

How it fails, and why those failures are acceptable

A substrate is only as good as its failure modes are understood. The Git-native ones are real and bounded.

• No real-time push. This is the headline cost. An idle agent is not woken by a message landing in the ref. h5i works around it rather than pretending it away: a Stop-hook (h5i msg hook) surfaces new mail between turns, and an agent that has sent a request and is waiting on a reply launches a background h5i msg wait --timeout N that exits when a reply arrives; h5i msg watch is the human-side dashboard. If your workflow needs sub-second delivery to an agent that is otherwise sitting idle, this substrate is a poor fit — poll-or-wake is the model.
• Ref growth. The log is append-only, so it grows without bound. For task handoffs across a project's life this is small text and rarely a concern, but it is not zero — a high-frequency firehose of messages is the wrong thing to put here, both for size and for readability.
• Merge is by id, not causality. As above, you cannot infer "happened-before" from the merged order. Threads must be explicit (thread_id/reply_to) or you lose the conversation structure.
• Pulled content is untrusted. A message can arrive from another clone carrying attacker-influenced text — control characters or escape sequences aimed at the terminal that renders it. h5i runs pulled display fields through a sanitize_display pass that neutralizes terminal-injection in untrusted fields. Treat an incoming message as input to evaluate, never as an instruction to obey, even when a hook delivers it automatically.

None of these is fatal for the use case the substrate is chosen for: durable, low-frequency coordination events. They would be disqualifying for live chat. That is the whole point — pick the substrate to match the traffic.

Git-native versus the alternatives

The honest way to argue for a substrate is to say what it gives up. Here is where a Git ref wins and where it does not.

• vs. a chat app / ChatOps (Slack, Discord). Excellent for humans and for ambient awareness. But it is not tied to a branch or commit, it is ephemeral relative to the repo, and it is not auditable as part of the code's history. When the coordination signal is "review this file on this branch," a separate chat product is the wrong home for it. Git-native keeps the message co-located with the artifact; chat keeps it co-located with people.
• vs. a message bus (Kafka, NATS). A bus gives you real-time delivery and a strong, partition-ordered log — genuinely better on latency and ordering. The cost is a server (or cluster) to run, secure, and scale; messages that live in infrastructure, not in the repo; and no audit trail unless you build one. A bus is the right answer for high-throughput event streams between services. It is overkill, and off to the side, for "agent A hands branch X to agent B."
• vs. MCP (Model Context Protocol). MCP is a tool/transport protocol that connects one agent to its tools and data sources. It is not a durable, shared, multi-writer log of coordination between agents — different layer entirely. You might use MCP tools and a Git message ref; they do not compete. (h5i in fact exposes its own operations as MCP tools.)
• vs. agent-to-agent RPC (e.g. Google's A2A). A2A and similar protocols let agents call each other live, in real time, with presence — strictly better when both endpoints are up and you want a synchronous exchange. The constraint is exactly that: both endpoints must be up. A Git ref works asynchronously and offline; an agent can hand off to one that does not exist yet, and the message waits in the ref until that agent is spawned and pulls. The two are complementary — live RPC for synchronous collaboration, a durable ref for asynchronous, auditable handoffs.

The pattern across the comparison: every alternative that beats Git on latency or presence loses to it on durability, code-adjacency, or zero-infra — and vice versa. There is no free lunch, only a fit. For asks, reviews, risks, and handoffs, the Git-native trade is the right one. For a live operator chat or a high-rate event stream, it is not.

What goes in a message versus a context trace

Choosing the substrate is half the discipline; the other half is what you put on it. The failure mode of any durable channel is that it becomes a dump of everything, at which point it is as useless as no channel. The line h5i draws: messages are coordination events; routine observation is a context trace.

A trace records what an agent did and saw — the work. A message records a decision that requires another party: an ask that expects a response, a risk that the next agent must inspect, a review request scoped to a file, a handoff that transfers ownership, an acknowledgement that closes a loop. If a line does not change what someone else should do, it is a trace, not a message.

That keeps the channel both readable and searchable after the session is gone. A good message is self-contained: it names the branch, the file or behavior at issue, the response expected, and the evidence already known. "Review auth retry behavior in src/auth.rs; concern is duplicate refresh after timeout" survives the loss of its chat window. "Look at this" does not.

The handoff case is where this earns its keep. Multi-agent work fails most often not from a bad change but from ambiguous ownership — two agents redoing the same task, or both assuming the other handled a risk. A handoff message makes ownership explicit: who owns the next step, what result counts as done, whether a reply, review, or fix is expected. That small structure, recorded durably next to the branch, is the difference between coordination and two monologues.

Conclusion: pick the substrate for the traffic

There is no universal coordination layer for AI agents, and the useful question is not "real-time or durable" in the abstract — it is which trade matches the traffic in front of you. Asks, reviews, risks, and handoffs are low-frequency, high-consequence, and inherently tied to a branch or commit. For that traffic, a Git ref written with compare-and-swap and reconciled with union-merge-by-id is a lossless multi-writer mailbox you already have the infrastructure for: it travels with the code, it cannot be silently rewritten, it works offline and across clones, and it costs you a server you never have to run. The price — eventual delivery, poll-or-wake instead of push, no global causal clock — is real, well understood, and acceptable exactly where this channel is used.

Where it is the wrong tool — live operator chat, sub-second streams, synchronous RPC between two agents that are both awake — reach for a bus or an A2A-style protocol and let them complement the durable log rather than replace it. Use the chat window for the conversation with the human; use the ref for the coordination that has to outlive it.

FAQ

Is Git fast enough for AI agent messages?

For durable task handoffs, reviews, and risk notes, yes. A Git ref trades sub-second latency for durability and auditability: an agent must pull to see new mail, so delivery is eventual, not real-time. h5i bridges the gap with a Stop-hook that surfaces new messages between turns and an h5i msg wait background waiter that wakes on arrival. It is the wrong substrate for live, sub-second chat and the right one for asks, reviews, risks, and handoffs.

How does a plain Git ref avoid lost messages with many writers?

Two mechanisms. A send is a compare-and-swap against the ref tip: build a commit off the tip you read, then move the ref only if it still points there; retry on contention. Across clones, pulls union-merge the append-only messages.jsonl by message id, so two agents pushing from different machines reconcile into the union of both message sets instead of one clobbering the other. The cost is eventual consistency: ordering is a per-id merge, not a global clock, so causal order rides on thread_id and reply_to.

Should every agent thought become a message?

No. Routine observation belongs in context traces. The message channel is reserved for coordination events — asks, reviews, risks, handoffs, acknowledgements, and completion — so it stays readable and searchable after the session ends.

How does Git-native messaging compare to a message bus like Kafka or to MCP?

A message bus gives real-time, ordered delivery but is a server to run and is not code-adjacent or auditable by default. MCP is a tool/transport protocol for one agent's tools, not a durable multi-agent log. Live agent-to-agent RPC protocols such as Google's A2A need both endpoints up at once. A Git ref is complementary: it works async and offline, travels with the code, and is auditable by construction — at the cost of presence and server-push.

Can humans read the messages?

Yes. The ref is plain text under refs/h5i/msg, and the point is an auditable channel that both agents and humans can inspect — including in a PR body, where relevant message history can be surfaced for human review.

Sources and verification

This article avoids vendor-specific claims that were not checked against primary docs or local h5i CLI behavior.

• h5i agent-to-agent messaging
• h5i collaboration guide