PricingSign inDownload

Blog / claude code

How to connect Codex and Claude Code

To connect Codex and Claude Code, keep rules in AGENTS.md imported by CLAUDE.md, then give both agents one task list, decision log and handoff note.

On this page
  1. Why don't Claude Code and Codex share context?
  2. How do I make Claude Code and Codex read the same instructions?
  3. How do I share live context between the two agents?
  4. How do I hand off work from Claude Code to Codex?
  5. How do I check that the other agent understood?
  6. When this is not enough
  7. Frequently asked questions
  8. Does Claude Code read AGENTS.md?
  9. Should I symlink CLAUDE.md to AGENTS.md or import it?
  10. How do I hand off a task from Claude Code to Codex?
  11. Can Claude Code and Codex share memory automatically?
  12. Try it with your team

Claude Code and Codex read different instruction files, so the simplest way to share context between them is one AGENTS.md that holds your rules and a CLAUDE.md that imports it. That covers the static layer: conventions, test commands, what never to touch. The live layer, meaning who is working on what, what was decided today and what was handed over, needs a task list and a decision log that both agents read before they start, plus a short handoff note whenever work moves from one agent to the other.

Why don't Claude Code and Codex share context?#

Because nothing connects them except the repository. Switch agents mid-task, for a review pass or a second opinion on a bug, and the new one starts with an empty head. It has not read the conversation, and it does not know what was tried, what you ruled out, or why the obvious fix is wrong. Anything you want both to know has to be written into a file, a commit, or a place both are told to read.

It helps to split that context into two layers, because they change at different speeds and live in different places:

LayerWhat it holdsWhere it livesHow often it changes
StaticRules, test commands, naming, what never to touchAGENTS.md, imported by CLAUDE.mdEvery week or two
LiveWho owns which task, today's decisions, handoffs, open questionsA task list, a decision log, the pull requestEvery hour

Most advice stops at the first row. Most of the frustration in threads about running both tools comes from the second.

How do I make Claude Code and Codex read the same instructions?#

The two tools start from different files. Claude Code reads CLAUDE.md, and its memory docs say that recent versions read AGENTS.md too, but only when the project has no CLAUDE.md. Codex reads AGENTS.md: it walks from the repository root down to your working directory, and in each directory it looks for AGENTS.override.md, then AGENTS.md, then any fallback names you configure.

So a repo with only CLAUDE.md is invisible to Codex, and a repo with both files gives each tool only its own half of the rules. The least painful fix is one source of truth and one line of glue. Put the real rules in AGENTS.md, and make CLAUDE.md import it:

md
@AGENTS.md

## Claude Code
- Use plan mode for anything under `src/billing/`.

Claude Code expands @path imports when a session starts, so it sees the same rules Codex sees, plus anything you add for it alone. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but it needs extra permissions on Windows, and the import doesn't.

Everything stable belongs in this file: how to run the tests, the naming rules, which directories are off limits. If you use other agents too, check which file each one reads before you assume it sees AGENTS.md; setting up Claude Code for a team lists them.

How do I share live context between the two agents?#

Live context changes during the day, so it doesn't belong in a file meant to stay true for weeks. Give it its own small files, and tell both agents how to use them in the shared instructions:

md
## Working with other agents
- Before starting, read TASKS.md and DECISIONS.md.
- Write your name and branch on a task before you touch code.
  If it already has an owner, pick something else.
- When you settle something other code depends on (an API shape,
  a library, a naming rule), add one line to DECISIONS.md with the date and why.
- When you stop mid-task, write a handoff note on the pull request.

Because the rule sits in AGENTS.md, Codex reads it directly and Claude Code reads it through the import. One rule, two agents. It is the same claim-first habit that keeps parallel Claude Code sessions out of each other's way.

How do I hand off work from Claude Code to Codex?#

Start with a commit, not a working tree. The most common failure fits in one sentence: "continue where I left off", said to an agent that is looking at a different directory. Uncommitted changes live in one working tree, so the handoff starts with a commit on a pushed branch:

bash
git add src/export/ tests/export.test.ts
git commit -m "wip(export): CSV streaming works, quoting bug open"
git push -u origin feat/csv-export
git rev-parse --short HEAD

A work-in-progress commit is fine; squash it when the work lands. A hash is a fixed point both agents can agree on.

Then write the note. Think of it as the conversation compressed to what the next agent can act on:

  1. Where. Branch and commit.
  2. The goal in one sentence, as a result someone could check.
  3. State. What works, what doesn't, and what is only assumed.
  4. The next step, singular and concrete.
  5. How to verify. The exact command that fails now and should pass.
  6. Decisions and dead ends. What was settled and why, and what was tried and failed.

People skip the last item, and it is the one that stops the new agent repeating a failed attempt. An example:

md
## Handoff: CSV export
Branch `feat/csv-export` at `a41c9e2`.

Goal: `GET /orders.csv` streams every order for a shop, under 200 MB of memory.

State: streaming works and handles 1M rows in the benchmark. Quoted cells
containing commas are still wrong (see the failing test). Not started: the
UI button.

Next: make `tests/export.test.ts > quotes commas` pass by fixing
`escapeCell` in `src/export/csv.ts`.

Verify: `npm test -- export`

Decided: streaming via `Readable.from`, not building the string in memory.
The first approach (buffer then send) passed tests and ran out of memory at
300k rows, so don't go back to it.
Tried, failed: the `csv-stringify` package; it dropped the BOM Excel needs.

Open question for a human: should refunded orders be included? Default
if nobody answers: include them with a `refunded` column.

Notice what isn't there: the agent's reasoning, a summary of the whole session, adjectives. If it can't change what the next agent does, leave it out.

The agent that did the work is best placed to write the note. Keep a standing prompt:

Write a handoff note for the next agent. Include: branch and commit
(commit and push first), the goal in one sentence, what works and what
doesn't, the single next step, the exact command to verify it, decisions
made with the reason, anything tried that failed, and open questions with
a default. Keep it under 200 words. Don't summarise the conversation.

Read it for unverified claims, such as "tests pass" when nobody has run them since the last edit. Put the note in a draft pull request's description: the next agent and the reviewer both read it, and it goes away with the branch.

How do I check that the other agent understood?#

Before Codex changes anything, ask for the next step in its own words and a run of the verify command. If the command doesn't fail the way the note says, the note or the checkout is wrong, and you learn that in a minute rather than after twenty minutes of edits.

This is also a cheap test of the shared instructions. If Codex restates the plan and gets a rule wrong, the rule is missing from AGENTS.md, and you fix it once for every future session in both tools.

When this is not enough#

Everything above works for one person moving between tools at one desk. If that is you, the files and a pull request are all you need, and adding another tool buys you nothing. Handing work to a teammate instead? Handing off a Claude Code session to a teammate covers that case.

It gets harder when the agents belong to different people. A DECISIONS.md only reaches a teammate's agent after a push and a pull, two agents can claim the same task in the same minute, and the handoff note has to arrive in the other agent's context without anyone pasting it in. That is what Joxo is for: the team's agents share one task board and one set of decisions, and a handoff carries the branch, the commit and the note into the receiving agent's next turn. Each person keeps the agent and plan they already use. The comparison page sets out when a team chat, notes in the repo or a shared memory server is the better fit, and coordinating AI coding agents across a team covers the people side.

Frequently asked questions#

Does Claude Code read AGENTS.md?#

Only when the project has no CLAUDE.md. Recent versions of Claude Code read AGENTS.md as the project instructions in that case; once a CLAUDE.md exists, Claude Code reads that instead. To keep both and have them follow the same rules, keep the rules in AGENTS.md and add a line to CLAUDE.md that imports that file. Claude Code expands the import when a session starts, so both agents read one source of truth.

Either works. An import is a one-line CLAUDE.md that pulls in AGENTS.md, and it lets you add a few rules that only Claude Code should follow. A symlink makes the two names point at one file, but on Windows it needs extra permissions. If anyone on the team works on Windows, the import is the safer choice.

How do I hand off a task from Claude Code to Codex?#

Commit and push the work in progress, then write a short note: branch and commit, the goal, what works and what doesn't, the single next step, the command that proves it, and the decisions and dead ends so far. Ask the outgoing agent to draft it. Before Codex edits anything, have it restate the next step and run the verify command.

Can Claude Code and Codex share memory automatically?#

Their instruction files can be shared, so standing rules reach both. Neither reads the other's conversation, though, so anything decided during a session reaches the other only if it is written down: in a decision log, a task list or a handoff note. A shared board that delivers those updates to each agent on its next turn saves copying them by hand.

See also: Joxo with Codex for connecting the two agents across a whole team, and Joxo with Claude Code.

Something missing or wrong? Support reaches a person.