How to Use Claude Code and Codex Together on One Repository

I built a German-for-work practice app with Claude Code and Codex taking turns on the same repository. It worked, after one realization that shaped everything else: the two agents can't read each other's chats or memory. Git and one handover file are the only state they share. Everything else, like a decision made in a Claude Code chat or a preference stored in Codex's memory, is invisible to the other agent.

So using Claude Code and Codex together isn't really about the tools. It's about making the repository itself carry the context: one rulebook, one handover file, clear lanes, and a rule for who works when.

Why use two coding agents at all?

Not because one is "better". There's no honest universal answer to that, and it changes with every model release. The practical reasons are more mundane:

• Availability. When you hit a usage limit or an outage in one tool, the work can continue in the other, if the repository carries the context.
• A second opinion. A fresh agent reviewing a diff isn't biased toward code it just wrote. Anthropic's own best-practices guide recommends a writer/reviewer split for exactly that reason.³
• Different strengths for different tasks. Each tool has its own features: Claude Code has skills, hooks and subagents; Codex has its own skills, cloud tasks and integrations. Use whichever fits the task.

All three only work if switching is cheap. That's what the rest of this setup is for.

CLAUDE.md vs AGENTS.md: which file is the rulebook?

Each tool reads its own instruction file at the start of a session:

• Claude Code reads CLAUDE.md files in your working directory and above it.¹ Since version 2.1.277 it can also read AGENTS.md directly, but by default only when there's no CLAUDE.md in your working directory or above it.¹
• Codex reads AGENTS.md: a global one in its home directory, then one per directory from the project root down to where you're working, with files closer to your working directory taking precedence.²
• AGENTS.md is an open format, now stewarded by the Agentic AI Foundation under the Linux Foundation, and supported by tools including Codex, Cursor, GitHub Copilot's coding agent and Gemini CLI.⁴

The trap is ending up with two rulebooks that slowly disagree. Pick one file as canonical and make the other a pointer:

The setup in this site's coding-agent pack uses the first option: CLAUDE.md is the canonical guide and AGENTS.md is a thin pointer. The import option is just as good. What matters is that a rule exists in exactly one place.

Put "current work" at the top of the guide

The first section of the canonical guide should answer the questions any agent asks when it arrives: which branch, which plan, which handover file, and who owns what. For example:

## 0. Current work and handover
- Branch: feature/practice-cap. Never work on main.
- Plan: docs/plan.md. Handover: docs/handover.md (newest entry first).
- Read the newest handover entry and `git log` since it before any edit.
- One agent at a time. End every session with a commit and a handover entry.
- Fenced: src/data/ and the prompt contract. No push without the owner's OK.

Because Claude Code loads CLAUDE.md at launch and Codex loads AGENTS.md,^{1 2} both agents see this before they do anything.

Choose an operating model

There are only three ways two agents can share a project, and one of them doesn't work:

The handover rules both agents follow

With alternating sessions, the handover file carries everything. The rules that kept it reliable:

1. One agent at a time. Start from a clean tree that matches the remote. If you find uncommitted work you didn't make, stop and ask.
2. Read before working: the newest handover entry, then git log since it.
3. One concern per batch, ending with verification, a commit and a new handover entry.
4. Every entry opens with a plain summary for the owner: what changed in the product, what needs to be running, what to try.
5. Decisions go in the plan file, dated and attributed, never only in a chat.
6. Say what you ran on the owner's machine, and stop what you started before handing over.
7. New settings go in .env.example. Secrets never appear in chat, docs or commits.

The entry template and the start-of-session preflight are covered in the Claude Code handover guide and the two-minute session checklist. Both are free skills in this site's starter kit, and they work in Claude Code and Codex alike.

Fence the dangerous parts

Two agents means twice as many chances for a confident mistake. Write the boundaries down:

• Fenced files: the data model, the prompt contract, another track's folder. Name them in the guide.
• Branches: name the working branch, and never merge main into it unless told to. Turn on branch protection for main.
• Destructive operations such as deleting branches, force-pushing or switching production run only from a written runbook, on the owner's explicit go.
• Deploys: on platforms like Vercel, a push to a non-production branch builds a preview deployment.⁵ Treat a push as a deployment.
• Ports: note which dev-server port belongs to which agent.

In Claude Code you can turn the most important of these into hooks, which run deterministically, unlike instructions in CLAUDE.md.³

Use the second agent as a reviewer

The most underrated benefit of two agents is review. Anthropic's best-practices guide describes a writer/reviewer pattern: one session implements, a second session with fresh context reviews the change, and the first addresses the feedback. It notes that a fresh context improves review "since Claude won't be biased toward code it just wrote".³

Across tools, the same pattern works with even more distance: Codex reviews what Claude Code wrote, or the other way round. Give the reviewer the diff, the plan and the criteria ("every requirement implemented, edge cases tested, nothing outside the task changed"), and ask it to report gaps rather than style preferences.

Check the setup in one minute

Start a fresh session in each agent and ask the same question: "What are you allowed to change, and where do you hand over?" Both should answer the same thing, from the files. If they don't, one of your guides is out of date, and you found out before it cost you a session.

FAQ

Which is better, Claude Code or Codex?

It depends on the task, the model versions of the month and your usage limits, and any ranking goes stale quickly. Try both on a real task in your own repository. With the setup above, switching is cheap enough that you don't have to pick one. If you do have to pick, my Claude Code vs Codex comparison puts the plans, usage limits and benchmarks side by side.

Can Claude Code and Codex work at the same time?

Yes, in separate checkouts: separate repositories or separate git worktrees, each on its own branch and dev-server port. Not in the same working tree.

Do I need both CLAUDE.md and AGENTS.md?

No. Claude Code can read AGENTS.md when there's no CLAUDE.md,¹ so one AGENTS.md can serve both. Keep a CLAUDE.md if you use Claude-specific instructions, and make one of the two files point to the other.

Does this work with Cursor too?

Yes. Cursor supports AGENTS.md,⁴ and it reads skills from .claude/skills/ and .agents/skills/, so the same guide, handover file and skills work there as well.