What crosses, and what doesn't. Going from one agent to another carries a handoff transcript, not native session state or a raw execution log. Codex opens a new session with the conversation and source-marked failed tool calls.
Keeping the prompt small
A long refactor produces a transcript larger than you want to spend context on. Trim it before it is handed over:
--since-compact— only the tail after Claude Code's last compaction. Usually the right default after a limit.--last 20— only the last 20 exchanges.--model <name>— launch Codex on a specific model, passed through as-is.
Handing over a session that isn't the newest
By default catchup takes the most recent Claude Code session in the current directory. To choose another one, find it first:
That lists recent sessions here across every agent. -q "rate limit" filters by keyword, claude/3 selects the third-newest Claude Code session, and --id <id> takes an exact one. See finding an older session.
Crossing machines instead of agents
The transcript is just text on stdout, so a file or a pipe is the transport:
--from accepts a file, - for stdin, or an http(s) URL, so the session Claude Code wrote on one machine can seed Codex on another.
Going the other way, and every other pair
The direction is symmetric — swap the two agent names:
Any supported agent can supply the session. Claude Code, Codex, Copilot CLI, Cursor, Cline, Antigravity (agy), OpenCode, and Pi Agent can be launched as the target. Kimi, ZCode, and DeepSeek Harness need a saved transcript because their CLIs cannot open an interactive session with a seed prompt.
Restarting the same agent cleanly
If the context is spent but the work isn't, and you want Claude Code itself to carry on with a fresh, smaller context rather than its accumulated one, point --into back at the same agent:
That restarts it clean, seeded with just the recent work. To instead resume with Claude Code's real session state, drop --into and run catchup fork claude — see the comparison.
Questions
Does Codex get the real Claude Code session state?
No. Codex starts a fresh session with the handoff transcript: the conversation plus source-marked failed tool calls. Native state is preserved only when you resume the same agent with catchup fork claude.
What if the Claude Code session is too long to paste into Codex?
Trim it before it is sent. --since-compact keeps only the tail after the last compaction, and --last <N> keeps the last N exchanges. Both work with --into.
Do I need Claude Code and Codex installed on the same machine?
For the one-command form, yes: catchup reads Claude Code's local history and launches the codex binary. To cross machines, write the transcript to a file with catchup claude > handoff.md, move it, then run catchup fork --into codex --from handoff.md on the other side.