Claude Code + Codex: a multi-agent coding workflow

More teams now run two coding agents at once — Claude Code in one terminal, Codex in another, sometimes on the same branch. The moment they need to coordinate ("I changed the token cache, can you review the expiry path?") there's no channel. You become the message bus: copy output from one window, paste it into the other, and lose the thread the moment you close a tab.

The problem: no shared channel between agents

Chat windows are per-agent and ephemeral. Git tracks code but not the conversation about code. So multi-agent work today means a human relay, no durable record of who asked whom for what, and no way for an idle agent to be woken when a reply finally lands.

How h5i solves it: i5h over a Git ref

h5i ships i5h — an agent-to-agent message channel stored in refs/h5i/msg. Messages are typed work items (ASK, REVIEW_REQUEST, RISK, HANDOFF) appended as durable Git objects and merged by message id, so a conversation survives clones, machines, and branches. Each agent's identity is set once ($H5I_AGENT — claude for Claude Code), and replies thread back via reply_to.

You wire it once, then just ask

The only command you run yourself is the one-time setup. After that you never type a single h5i msg command — the agents send, read, and reply on their own. Wire Claude Code once (Codex just launches with H5I_AGENT=codex):

$ h5i msg setup           # sets identity + turn-delivery Stop hook
✔  identity: claude · Stop hook installed in .claude/settings.json

From then on you talk to your agent in plain language. Tell Claude "let's coordinate with Codex over h5i — send Codex a review request for the token refresh", and it issues the typed message itself; the Stop hook delivers Codex's reply back between turns. You stay the director, not the message bus.

How i5h works

Under the hood every handoff is one append-only JSON line on the Git ref refs/h5i/msg. Claude appends a typed request, Codex reads it and appends its replies, and the log is a grow-only set merged by id — so the conversation survives clones, machines, and branches, and h5i share push/pull moves it like any other ref.

Frequently asked questions

Do Claude Code and Codex need to share a terminal or a server?

No. Messages are appended to a Git ref (refs/h5i/msg) and merged by id, so the two agents only need to share the repo. There's no daemon, no server, and no shared terminal — h5i share push/pull moves the channel like any other ref.

How does each agent know which messages are theirs?

Identity comes from $H5I_AGENT — Claude Code uses 'claude', Codex launches with H5I_AGENT=codex. h5i msg inbox shows only messages addressed to you (or broadcasts), numbers them, and advances your local read cursor.

What message types are there?

i5h defines typed work items: ASK (a request expecting a response), REVIEW_REQUEST (code/design/security review with branch, focus, and risk fields), RISK (flag a hazard), and HANDOFF (transfer task ownership). Replies are typed too: ACK, DONE, and DECLINE, threaded via reply_to.

How does an idle agent get woken when a reply arrives?

Run h5i msg wait in the background; it blocks until a new message lands, prints it, and exits — which wakes the agent so it can run h5i msg inbox and act. The Stop hook also surfaces messages that arrive between turns.

Is the conversation auditable later?

Yes. Every message is a durable Git object, so h5i msg history (or h5i msg replay) reconstructs the full thread — who asked whom for what, and how it resolved — long after the sessions ended.