How to Make Claude Code and Codex Work Together on One Repo

The instinct is to treat Claude Code and Codex as separate tools that need gluing together with a plugin. The better model is to treat them as two remote engineers in different time zones. They never chat in real time. They coordinate entirely through files and git — a task board, a status note, review comments, and the commit history. It is async by design, and nothing is lost when one stops and the other picks up.

The key move is to stop thinking of one agent as the driver and the other as an assistant that only stages work. Set up correctly, they are peers: both build, both review, and both ship. Here is the whole thing — drop it into any repo.

The one file that runs both

Each tool reads its own config from the repo root: AGENTS.md for Codex, CLAUDE.md for Claude Code. Do not maintain two rulebooks — they drift within a week. Put the full working agreement in AGENTS.md, then make CLAUDE.md a single line that points at it: "Read AGENTS.md. It is the shared source of truth for every agent. Follow it exactly." Now both agents are governed by one file.

That working agreement is the block below. It is the only thing you truly have to paste in; the rest of this article just explains why each part is there.

# AGENTS.md  —  working agreement for the AI agents on this repo
# Codex reads AGENTS.md automatically. Make CLAUDE.md a one-line pointer to it:
#   "Read AGENTS.md. It is the shared source of truth for every agent. Follow it exactly."
#
# The rule for both agents: we are PEERS. Both build, both review, both ship.
# We never talk live — we coordinate through these files and the git history.

FILES WE SHARE
  todo.md        the task board, with an owner + branch on every in-progress task
  STATUS.md      the current state of play, kept up to date at all times
  lessons.md     corrections + gotchas, so one agent's mistake teaches both
  decisions.md   the "why" behind choices, so neither silently reverts the other
  /review/       a branch's work put up for the other agent to check

ON START  (every single run)
  1. Read STATUS.md, todo.md, lessons.md, decisions.md, then run:  git log -20
  2. Pick a task no one owns, or pull one from "Ready" in todo.md.
  3. Claim it in todo.md with your name and a branch:
       - [ ] (claude, branch claude/auth) move auth to sessions
  4. Work on that branch only. Never touch a task another agent owns.

WHILE WORKING
  - Tick items off todo.md as you finish them.
  - Append every correction you receive to lessons.md.
  - Log any real architectural decision in decisions.md (date + one-line why).

WHEN YOU STOP
  1. Update STATUS.md — what you did, what's next, what's blocked, what NOT to touch.
  2. Push your branch. If it is ready for review, add /review/<branch>.md with a note:
       "Review this branch. Focus on the Redis client and the retry logic."
  3. Commit with your name tagged so the log stays legible:
       claude: add session middleware (#auth)
       codex:  rate-limit /api at 100/min (#ratelimit)

SHIPPING  (this is what makes them peers, not a boss + an intern)
  - Whoever OWNS a task merges it — but only after the OTHER agent has reviewed
    and approved it in /review/. No self-merges straight to main.
  - Review flows both ways: Codex reviews Claude's work as readily as the reverse.

RUNNING BOTH AT ONCE
  Give each agent its own working copy so they can't edit the same file live:
       git worktree add ../repo-claude claude/work
       git worktree add ../repo-codex  codex/work
  Two folders, one repo, one shared history. They merge through review, never mid-edit.

Why it works as peers, not a boss and an intern

Two things turn this from "one builds, one stages" into two genuine peers. The first is parallel branches. Each task claims its own branch — claude/auth, codex/rate-limit — so the agents build at the same time without ever touching the same file. The second is mutual review. When a branch is ready, its owner does not merge it alone; the other agent reviews and approves it first, in a note under /review/. Because that review flows in both directions, Codex checks Claude's work exactly as readily as the reverse. Remove either piece and you are back to a hierarchy.

The status file is the handoff

Live agents have no memory of each other. STATUS.md is where that memory lives. Whoever stops updates it, so the next agent is oriented in ten seconds: what was just done, what is next, what is blocked, and — critically — what not to touch because the other agent is mid-refactor there. When Codex opens the repo and reads the status note plus the last twenty commits, it knows precisely where Claude left off, and vice versa.

Shared memory: lessons and decisions

lessons.md is where a correction becomes permanent. The moment you tell one agent "never edit prod.config, it is hand-managed," it writes that down, and both agents read it on their next start. Correct a mistake once, teach both agents forever. decisions.md is the companion: a short log of the architectural "why," so one agent does not quietly undo a choice the other made on purpose. "Chose sessions over JWT — need instant revoke. Do not revert without raising it." Two agents with no shared hallway conversation, so you write the hallway down.

Running both at the same time

If you want them literally working in parallel, give each its own checkout with a git worktree — two folders backed by one repository and one history. They edit different files in different folders, and everything still merges through the same review loop. No live collision is even possible.

The repo is the harness

That is the entire trick: no plugin, no MCP server, no integration. Four shared files, one working agreement, parallel branches, mutual review, and a git log that reads like a conversation. Build it once and reuse it on every project — and the next time someone asks how to get Claude and Codex to talk to each other, the answer is that they already do, through the repo.