How to hand a task from Claude Code to Codex without starting over

To hand a task from Claude Code to Codex, put 3 things in the repository before you switch: the project's rules in AGENTS.md, which both agents read; the work so far in a git commit; and a short HANDOFF.md that says where the task stands and what comes next. Then start Codex with a prompt that tells it to read the hand-off first. Neither agent can read the other's conversation, so anything that is not in the repository is lost at the switch.

The usual reason to switch is a limit. Claude Code stops halfway through a refactor, the reset is hours away, and Codex is right there on another plan. Without a hand-off, Codex starts cold: it reads the code, guesses the goal, and often takes the approach you already tried and dropped an hour ago.

Why the next agent starts with nothing

Each Claude Code session begins with a fresh context window, and a Codex session is the same. What an agent knows when it starts is what it reads: its instruction files, then whatever you point it at. The plan you agreed in chat, the test that failed 3 times, and the reason you dropped the first approach all live in the old conversation, and the new agent never sees it.

So the hand-off is the work of moving that knowledge from the conversation into files. There are 3 kinds of it, and each has its own place.

Share the rules once, in AGENTS.md

Codex reads AGENTS.md: a global one in ~/.codex, then one file per folder from the repository root down to where you are working. Claude Code reads AGENTS.md too, but only when the repository has no CLAUDE.md. If you already have a CLAUDE.md, add a line @AGENTS.md to it so Claude Code imports the shared file, and keep only Claude-specific notes in CLAUDE.md. Our AGENTS.md vs CLAUDE.md guide covers the setup and the traps when both files exist.

Don't put the task in AGENTS.md. It loads in every session for every task, and Codex stops adding instruction files once they reach 32 KiB by default. The task state is temporary and belongs in its own file.

If you also want Codex's MCP servers, skills and commands on the Claude Code side, /import codex in Claude Code copies that configuration across. Run it with --dry-run first to see what it would bring.

Write the hand-off before the limit hits

The hand-off has to be written by the agent that did the work, so it has to happen while that agent can still answer. In Claude Code, /usage shows how much of your plan's limit is used; in Codex, /usage shows your account's token usage. Check it when a task runs long, and ask for the hand-off with room to spare rather than at the last message.

A good hand-off is short. Under 60 lines is plenty, because the code and the git history already say what changed. What they cannot say is why: the goal behind the change, the choices made, and the dead ends. Those are what the brief is for.

Pick the direction you are switching and where your task stands, and copy the 3 steps.

Try itBuild the hand-off for your task

Claude Code to CodexCodex to Claude Code

Where the task stands

·Planned, not started·Halfway through a change·Stuck on a failing test·Done, needs a check

1. 1. Ask Claude Code for the brief

   Copy

   Before you stop, write HANDOFF.md in the repository root for another coding agent (Codex) that has not seen this conversation. Keep it under 60 lines. Use these headings:
   Goal: what the task is for, in 2 sentences.
   Done: what is finished and committed.
   Now: Every file you changed or meant to change, what is finished in each and what is still missing.
   Decisions: choices made and why, so they are not reopened.
   Don't: approaches that failed, and files not to touch.
   Check: the commands that show the work is right.
   Next: the open steps, in order.
   Write only what the code and git history cannot show. Do not paste code or logs longer than 10 lines.

2. 2. Put the work in git

   Copy

   git add -A
   git commit -m "WIP: handoff, see HANDOFF.md"

3. 3. Start Codex on it

   Copy

   codex "Read HANDOFF.md, then git log -5 and git diff HEAD~1. Then finish the first file marked unfinished. Ask before changing anything listed under Don't."

The "Don't" part of the brief does more work than it looks. An agent that starts cold reaches for the obvious fix first, and the obvious fix is often the one that already failed. One line saying "raising the timeout does not fix the flaky test; the cause is the shared fixture" saves the next agent from repeating it.

Why not paste the whole conversation?

Claude Code's /export writes the conversation to a text file, and it is tempting to hand Codex all of it. It is the wrong trade. A long session runs to many thousands of words: every file read, every tool result, every wrong turn. The next agent reads all of it into its context, spends its own limit on it, and has to work out for itself which parts still hold. A long conversation is also what drains a plan's limit in the first place.

Keep the export for yourself, as a record. Give the next agent the brief.

Start Codex on the task

Both agents take a first prompt on the command line. codex "..." starts Codex with the prompt already sent, and claude "..." does the same for Claude Code. The prompt in the widget's step 3 asks for 3 things in order: read HANDOFF.md, look at the last commits and the diff, then take the next step. Reading git as well as the brief matters because the brief can be wrong about a detail and the diff cannot.

If Codex is already open, /mention HANDOFF.md attaches the file to the chat instead. Before you let it edit anything, ask it to say in a few lines what it thinks the task is and what it will do first. If that summary is off, fix the brief, not the conversation, so the next switch gets it right too.

Switching back to Claude Code

When your Claude Code limit resets, the same steps run the other way: Codex updates HANDOFF.md, you commit, and Claude Code starts on the brief.

You can also return to the old Claude Code conversation with /resume or claude -c. It still has the long history, which is useful, but it holds only what happened in it. It does not know what Codex changed while you were away. Tell it to read HANDOFF.md and git log before anything else, or it will work from the code as it was.

Keep the file small

A hand-off file that lives through 5 switches grows into a second AGENTS.md. Have each agent rewrite it rather than append to it, so "Now" and "Next" always describe the present. When the task is merged, delete the file. Anything in it that should outlast the task, a convention you settled on or a command everyone needs, moves into AGENTS.md.

Claude Code's own sessions, /resume and /branch are covered step by step in our guide to Claude Code sessions, and project instructions covers CLAUDE.md and imports. If you are still deciding between the agents, Claude Code vs Cursor vs Codex compares them on the same job.