Workflow
Hand off a task from Claude Code to Codex without losing context
You've hit your Claude limit halfway through a refactor, or you want a second opinion. Here's what has to travel to the next agent, and three ways to get it there.
Quick answer
Neither agent loads the other's transcript, so you carry the task across with a brief: the goal and your last instruction, the plan, the files touched, and the git state, with the code itself on disk. Keep shared rules in AGENTS.md, commit or git stash create your work in progress, then write the brief yourself, generate it with a tool like hop, or let an app such as Maude build it when you switch.
You can switch from Claude Code to Codex in the middle of a task without starting over, but neither agent will pick up the other's conversation by itself. What carries a task across is a short brief: the goal, the plan, the files touched, the git state and your last instruction, plus the code on disk. You can write that brief by hand, generate it with a small tool, or use an app that builds it for you when you switch.
Why hand off a task between coding agents
- You hit a limit. This is the most common reason. Your Claude plan runs out of usage in the middle of a refactor, and your ChatGPT plan still has room. Waiting for the reset costs hours, and starting fresh in Codex costs the context.
- A second opinion. One agent has gone round in circles on a bug. A different model reading the same code with a clean context often spots what the first one stopped seeing. Asking one agent to review another's diff before you commit is also cheap.
- Different strengths. People use one agent for planning and another for long mechanical edits, or keep one for a language or framework it handles well for them. Which is better at what changes with every model release, so treat it as your own judgement, not a rule.
Can Codex read Claude Code's session?
Not on its own. Both agents keep full transcripts as JSONL files on disk. Claude Code writes them to ~/.claude/projects/<project>/<session>.jsonl (Claude Code docs), and Codex to dated rollout-*.jsonl files under ~/.codex/sessions/. Each one resumes its own sessions (claude --resume, codex resume), but neither documents loading the other's. Claude Code's /import command brings over another agent's configuration, such as instruction files, MCP servers and skills. It doesn't bring the conversation.
You could point the new agent at the raw transcript file. In practice that's a poor brief: it's long, full of tool output, and buries the one thing the new agent needs, which is where you are and what comes next.
What context has to travel
| Context | Why it matters | Where it comes from |
|---|---|---|
| Goal and last instruction | The new agent has to know what "done" means and what you asked for most recently | Your last prompt, word for word |
| Plan / todo list | It stops the agent re-planning work that's already scoped | The departing agent's todo list |
| Files touched | It tells the agent where to read before it edits | The edits in the transcript, plus git status |
| Git state | Branch, HEAD and uncommitted changes. Without them, the new agent may redo work or commit over it | git status, git diff --stat |
| Decisions and dead ends | So the new agent doesn't retry an approach that already failed | The recent conversation, or a written summary |
Project conventions, such as build commands and code style, shouldn't be in the brief at all. They belong in instruction files that both agents already read.
DIY: shared instructions with AGENTS.md and CLAUDE.md
Codex builds its instructions from AGENTS.md files, from ~/.codex/ and from the git root down to your working directory (Codex AGENTS.md docs). Since v2.1.277, Claude Code reads AGENTS.md too, but by default only when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above it (Claude Code memory docs). The simplest setup that both agents read: keep shared rules in AGENTS.md, and if you need Claude-only rules, start your CLAUDE.md with an import:
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/.The other direction works too. Codex's project_doc_fallback_filenames setting in ~/.codex/config.toml lets it read additional filenames when no AGENTS.md is present.
DIY: a handoff doc and git
Before you switch, ask the departing agent to write the brief while it still has the context, if it has any usage left:
Write HANDOFF.md for another coding agent taking over this task:
the goal, what is done, what is in progress or broken, decisions
and dead ends, files touched, and the exact next steps.
Don't change any other file.Then make the code state unambiguous. Committing work in progress to a branch is the clearest option. If you'd rather not commit, git stash create records the uncommitted tracked changes as a commit object without touching your working tree, which gives you a fixed point to diff against if the next agent goes wrong. Start the other agent in the same directory and tell it to read HANDOFF.md and re-read files before editing.
Tools that automate it
hop (MIT) does this in one command: hop codex for Claude Code to Codex, hop cc for the reverse. It reads the source agent's session files directly, so it works even when that agent is out of quota. You can run ! hop codex from inside a stuck Claude Code session. It writes a handoff doc with your instructions, the git branch and the recent conversation, within a size budget (48 KB by default), and opens the other agent in a new terminal tab. Similar projects include cli-handoff and session-handoff.
| Approach | Works when out of quota | Effort per switch | Carries the conversation |
|---|---|---|---|
| Shared AGENTS.md only | Yes | None, but it carries conventions, not task state | No |
| Agent-written HANDOFF.md + git | Only if the departing agent still answers | A prompt and a commit | As a summary |
| hop and similar CLIs | Yes | One command | Recent turns, budgeted |
| An app with built-in switching | Yes | One tap | Depends on the app |
How handoff works in Maude
Maude runs your agents on your own server, and a session isn't tied to one agent. While a session is idle, you can switch it from, say, Claude Code to Codex (or OpenCode, Grok Build or Antigravity) from the phone. The daemon on the server builds the brief from the session's own record, not from a summary written under pressure:
- a frame telling the new agent it's taking over, that the files on disk are the source of truth, and that it should re-read before editing
- your last instruction, pinned
- the current plan or todo list
- the files touched, from the agent's edits plus the files git reports as changed
- the git state: branch, HEAD, short status and diff stat. Uncommitted work is also snapshotted with
git stash createand kept under a ref, without touching your working tree - the recent conversation, verbatim, up to about 120,000 characters
- a pointer to the full transcript, exported as markdown to
.maude/handoff/in the project and kept out ofgit status
The brief goes in front of your next message to the new agent, and the chat shows a divider you can expand to read exactly what was sent. Because the brief is built from the session record, it doesn't depend on the departing agent being able to answer, which matters most when it has just hit its limit.
Switching back is different. If the agent you return to has already worked in this session and supports resuming, Maude resumes that agent's own conversation and sends only what happened while it was away. It doesn't get a second full brief.
Maude isn't the only app that does this. Happier lets you change the engine mid-conversation and gives the new agent tools to read the earlier transcript. AgentsRoom builds a handoff summary of modified files, session activity and the last response when you switch providers. We compare the trade-offs in Maude vs Happier. To choose which agents to pair, see Claude Code vs Codex vs OpenCode.
Frequently asked questions
Can Codex read Claude Code's session?
~/.claude/projects/, and Codex doesn't load them. You carry the task across with a brief: write it yourself, generate it with a tool like hop, or use an app that builds it when you switch.Do AGENTS.md and CLAUDE.md conflict?
AGENTS.md only when there's no CLAUDE.md. To share one file, keep your rules in AGENTS.md and put @AGENTS.md at the top of CLAUDE.md. Codex reads AGENTS.md natively.What if I hit my Claude limit mid-task?
Does switching agents lose my uncommitted changes?
git stash create first gives you a fixed point to compare against if the next agent goes wrong.
