Last updated: 2026-10-09

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.

A community pattern, not a product feature

Neither Anthropic nor OpenAI documents a Claude Code–Codex handoff feature. This is a convention you set up with git. For parallel work inside Claude Code itself, see its documented worktree workflows and dynamic workflows. To bring a Codex setup's instruction files, MCP servers, commands, subagents and skills into Claude Code, /import codex (v2.1.213 or later) does that, but it moves configuration, not work in progress, and isn't available on Amazon Bedrock, Google Cloud, Microsoft Foundry or Claude Platform on AWS. Checked 2026-10-09.

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.

Developers have shared this pattern of agents carrying on a "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