Last updated: 2026-06-07

Claude Code and Codex: Real-Time Collaboration via Git

Claude Code and Codex can collaborate asynchronously on the same project by using Git branches as a shared communication channel — each agent commits work and context notes, the other picks up and continues. Here's the pattern and when it makes sense.

Why Git as a communication channel?

Both Claude Code and Codex operate in isolated sessions with no shared state. Git branches solve this: a commit is a durable, structured message that any agent can read regardless of what session created it. Unlike trying to coordinate via shared files or environment variables, Git provides a clean log of what changed, when, and with what context — and both agents already know how to read diffs.

The technique was popularized in a June 2026 Hacker News post (115 points) showing that agents can carry on a "real-time conversation" through commits — each one leaving enough context for the other to continue without re-deriving the whole problem.

The handoff pattern

The workflow has three parts:

Phase 1 — Codex scaffolds: Codex is faster and cheaper for mechanical tasks. Give it the spec and let it generate boilerplate, file structure, and test stubs on a dedicated branch (agent/codex-scaffold). Codex commits with a HANDOFF.md at the repo root explaining what was done, what remains, and any design decisions it made.
Phase 2 — Claude Code continues: Claude Code checks out the branch, reads HANDOFF.md and the diff, then picks up the deeper work — implementing business logic, handling edge cases, writing meaningful tests. It adds its own notes to HANDOFF.md before committing.
Phase 3 — Review and merge: A human (or an orchestrator agent) reviews the branch, resolves any remaining TODOs, and merges. The commit history is a readable log of agent reasoning.

What to put in HANDOFF.md

The handoff file is the agent's message to its successor. Keep it short and specific:

## What was done
- Generated file structure for the auth module
- Stubbed all route handlers in routes/auth.js
- Created test file with 12 test cases (all skipped)

## What remains
- Implement JWT validation logic in middleware/auth.js
- Fill in the test cases with real assertions
- Handle the refresh token rotation edge case (see TODO in auth.js:47)

## Decisions made
- Used express-jwt for token parsing (lighter than passport)
- Tokens expire in 15 min; refresh tokens in 7 days

When to use this pattern

The relay pattern shines for large refactors (2,000+ lines), greenfield features where structure and logic are distinct phases, and code review workflows where one agent writes and another reviews. It's overkill for small bug fixes — just use one agent start to finish. The main cost is the coordination overhead: writing good handoff notes takes a few extra tokens and requires you to prompt both agents explicitly about the pattern.

← Back to Claude Cowork FAQ · See also: Cowork vs API · Compare Agents