How to hand off a task from Claude Code to Codex (and back)

Claude Code and Codex are good at different parts of the same task. A split that works well: Claude Code writes the code, then Codex runs the smoke test. Codex has a Computer Use plugin that can open the built app on your Mac, click through it, and report what broke. For that to work, Codex has to know what was just built and what to check, without you explaining the whole task again.

The same goes for other reasons to switch: a usage limit halfway through a refactor, or a second opinion on a design.

Neither tool can open the other's conversations. What you can move is the context:

• Write a handoff note. Ask the current agent to put the goal, what's done, what's left, and the decisions so far into HANDOFF.md.
• Start the other agent from it. In the same directory, run codex "Read HANDOFF.md and continue the work described there.", or the same with claude.
• Share project instructions. Claude Code reads CLAUDE.md and Codex reads AGENTS.md. Put @AGENTS.md in CLAUDE.md so both see the same rules.
• The catch: the new agent starts a new session. It knows what the note says, not everything the first agent saw.

Why can't Codex just open my Claude Code conversation?

Each tool writes its own transcript format to its own folder. Claude Code uses ~/.claude/projects/, and Codex uses ~/.codex/sessions/. claude --resume only lists Claude Code sessions, and codex resume only lists Codex sessions. There is no import command in either direction.

So a handoff is never a transfer of the conversation. It's a new session that starts with enough context to keep going. The quality of the handoff comes down to what you put in front of the next agent.

What does the next agent need to know?

Less than the whole transcript, and more than the last message. A useful handoff answers five questions:

1. What's the goal, in one or two sentences?
2. What's done, and how was it checked?
3. What's left, in order?
4. Which decisions were made, and why? These are the ones the next agent would otherwise undo.
5. Which files matter, and what's still uncommitted?

The files themselves don't need to be in the note. Both agents work on the same directory, so the next one can read the code. What it can't read is your reasoning.

How do I write a handoff note?

Ask the agent that has the context to write it. It saw the dead ends and knows why things are the way they are. Paste this into the current session:

Write a handoff note to HANDOFF.md for another coding agent that will continue this work.
Include: the goal, what is done and how it was verified, what is left in order,
decisions we made and why, the files that matter, and anything uncommitted.
Be specific. Skip anything the next agent can read from the code.

For a smoke-test handoff, ask for the testing details too: how to build and launch the app, which flows changed, and what "working" looks like for each one. Then start Codex with a prompt that says what to do with the note, such as codex "Read HANDOFF.md and smoke-test the changes it describes."

Read the note before you hand it off. It's short, and it's the only thing the next agent knows about the conversation, so fix anything that's wrong or missing.

Commit HANDOFF.md or add it to .gitignore. Either is fine, as long as it doesn't slip into an unrelated commit.

How do I start Codex or Claude Code from the note?

Open a terminal in the same directory and pass the note as the first prompt:

# Claude Code → Codex
codex "Read HANDOFF.md and continue the work described there."

# Codex → Claude Code
claude "Read HANDOFF.md and continue the work described there."

Both CLIs take an initial prompt as an argument and start an interactive session with it. The new agent reads the note, looks at the files it names, and carries on. Watch the first few steps. If it starts redoing something the note says is finished, the note needs another line.

Stay in the same working directory. Both agents load project instructions and resolve paths from there, and a different checkout means different files.

Can the next agent read the full transcript instead?

It can, and sometimes that's useful for one detail the note left out. Tell it where the file is:

• Claude Code: ~/.claude/projects/<project>/<session-id>.jsonl
• Codex: ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl

Don't make it the main handoff. Transcripts are mostly tool output and metadata, they get large quickly, and the format is internal to each tool. A long session can fill much of the next agent's context before it does any work.

Claude Code's /export writes the current conversation as plain text. Pass a filename and it saves there, with the extension changed to .txt. That's easier for another agent to read than the JSONL, but it's still the whole conversation, not a summary.

How do I make both agents follow the same project rules?

Keep one file and point the other tool at it.

Option 1: import AGENTS.md from CLAUDE.md. Claude Code supports @path imports in CLAUDE.md. A CLAUDE.md that contains only this line makes Claude Code read your AGENTS.md:

@AGENTS.md

Option 2: let Codex read CLAUDE.md. If your rules already live in CLAUDE.md, add this to ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

Codex then uses CLAUDE.md in any directory that has no AGENTS.md. Without this setting, Codex doesn't see CLAUDE.md at startup.

What doesn't carry over in a handoff?

• The conversation. The next agent has the note, not the transcript. Anything it needs has to be in the note or in the code.
• Permissions and approvals. Each tool has its own settings. What you allowed in Claude Code isn't allowed in Codex.
• Tools and integrations. MCP servers, skills, hooks, and custom commands are configured per tool. Set them up on both sides if the task depends on them.
• The original session. It stays where it was. You can still resume it in its own tool, and you can hand off back later with a new note.

Can I hand off without writing the note myself?

Yes. PonyMux has a Handoff action on Claude Code and Codex sessions that have saved at least one exchange. With a Terminal selected, open the Inspector and click Handoff to Codex (or Handoff to Claude) in the Session section. The same action is also in each session's ⋯ menu in the Sessions panel.

The Inspector's Session section for a Claude Code session. Handoff to Codex sits under Fork Session.

PonyMux reads the session's transcript and writes a Markdown handoff file with:

• the session title and working directory
• a summary, when the session has one
• the last five exchanges, with a one-line note for each command, file read, or edit
• the path to the full transcript

It then starts the other agent in the session's working directory with a prompt to read that file. You choose where: Here ends whatever is running in the current Terminal and starts the new agent in its place. New Terminal opens one next to it in the same list and leaves the current one alone. The source session isn't changed, so you can still resume it.

It saves the copy-paste, not the judgment. The file holds recent turns, not a note written for the next agent, so for a long task it's still worth asking the agent for a proper handoff note first. Codex sessions saved in compressed .jsonl.zst form can't be handed off yet.

For the details of Resume, Fork, and Handoff, see the Sessions docs.

---

Originally published on ponymux.com, where the demos are interactive.