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.

Claude Code and Codex can't open each 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 or grok.
• Or let Grok Build read the session. In Grok, /resume-claude or /resume-codex reads a recent session from that tool, summarizes it, and continues from there.
• 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. Grok Build reads both.
• 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. By default, Claude Code uses ~/.claude/projects/, Codex uses ~/.codex/sessions/, and Grok Build uses ~/.grok/sessions/. claude --resume only lists Claude Code sessions, and codex resume only lists Codex sessions. Neither has an import command for the other's sessions. Grok Build is the exception: it can read Claude Code and Codex sessions, as described below.

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."

# Either one → Grok Build
grok "Read HANDOFF.md and continue the work described there."

All three 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. Each agent loads project instructions and resolves 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
• Grok Build: ~/.grok/sessions/<encoded project path>/<session-id>/chat_history.jsonl

These are the default locations. If you've set CLAUDE_CONFIG_DIR, CODEX_HOME, or GROK_HOME, the files are under that folder instead.

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. Grok Build's grok export <session-id> HANDOFF-full.md does the same from the shell, as Markdown. Either is easier for another agent to read than the JSONL, but it's still the whole conversation, not a summary.

Can Grok Build pick up a Claude Code or Codex session directly?

Yes. Grok Build ships two skills for it. Open Grok in the same project folder and type:

/resume-claude

Or /resume-codex for a Codex session. With no argument, Grok picks the newest session for the current directory. Add a few words that describe the session, or its ID, to pick a different one. If the words match more than one session, Grok lists them and asks which.

Grok reads the transcript with a bundled script and writes a short handoff: the goal, what's done, what's still open, and where the session stopped. Before changing anything, it checks the current branch, uncommitted changes, and the files the session named, because the transcript may be out of date. Then it carries on, or asks the question the old session ended on.

A few things to know:

• It's still a new session. Grok works from its own summary of the transcript, not from the original conversation.
• It doesn't follow the old session. Grok treats the transcript as history. It won't run commands or follow instructions it finds there.
• It can miss things. Grok reports records it couldn't read. A session whose format Grok doesn't recognize may come back thin, so read the summary before you let it continue.
• It only goes one way. Claude Code and Codex have no built-in way to pick up a Grok session. To hand off from Grok, write a note, or point the other agent at Grok's transcript as described above.

How do I make every agent 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.

Grok Build needs neither. It reads AGENTS.md and CLAUDE.md, including nested ones, and rules under .claude/rules/. grok inspect lists every rules file it picked up.

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. Grok Build picks up Claude Code's skills, commands, MCP servers, and hooks on its own, and /import-claude copies permissions and environment variables into its config.
• 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, Codex, and Grok sessions that have saved at least one exchange. With a Terminal selected, open the Inspector, click Handoff to… in the Session section, and pick Codex (or Claude, or Grok). The same action is also in each session's ⋯ menu in the Sessions panel, under Handoff to.

The Inspector's Session section for a Claude Code session. The Handoff to… menu sits under Fork Session and lists Codex and Grok.

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.