Claude Code to Codex: what actually carries over

The half that is a file, and therefore moves

Instructions are the solved part, and they are solved because somebody standardised them. AGENTS.md is a cross-tool convention that a long list of agents read, so the usual first step of a migration is to copy CLAUDE.md across, or symlink one to the other and maintain a single file. The formats are close enough that most of it works unchanged.

MCP servers move too, though not by copying: each tool declares them in its own config, in its own format, and Codex in particular will not forward environment variables to a server unless they are named explicitly in that declaration. It is a re-typing job rather than a design job.

What is genuinely Claude Code's own - its hooks, its slash commands, its subagent definitions - does not have an equivalent to move to, and this is the part worth checking against current documentation rather than a guide, because it is where the tools differ most and change fastest.

• Moves with a copy: the instruction file, once renamed.
• Moves with a re-declaration: MCP servers, per tool, per format.
• Does not move: hooks, slash commands, and anything else with no counterpart on the other side.
• Never needed moving: your shell, your aliases, your worktrees.

The half that is not a file, and therefore does not

Ask what your agent knows that you never wrote down. That one module is a minefield and why. Which of the three obvious approaches was tried in March and abandoned. That the flaky test is flaky for an understood reason and is not worth chasing. Why a dependency is pinned. None of that is in CLAUDE.md, because it is not an instruction; it accumulated inside sessions, and it is the reason the agent had become useful.

That material is held by whichever vendor you were using, in a store no other vendor reads. Nothing about the migration is technically wrong when it disappears - it was never portable in the first place, and it would have been just as lost had you stayed and simply started a new session.

This is why migrations feel worse in week two than on day one. The configuration is done, the agent runs, and then you hit the first task that needed something the old setup had absorbed. There is nothing to copy across, because nobody wrote it anywhere.

Where the second half can live instead

The fix is not a better instruction file - putting findings there is exactly what makes CLAUDE.md unmaintainable, and it means paying context for them on every session regardless of relevance. The fix is a place outside both agents that either can read and write.

That is what a Thread is in Forkbench. One job gets its own folder, its own plan, its own notes and its own keys. An agent working in that Thread lists and reads the notes when it needs them, and files what it works out as it goes. Because the notes belong to the Thread rather than to the agent, quitting Claude Code and starting Codex in the same pane gives the new agent the same notes and the same board, with no migration step at all.

The notes are sealed on your Mac before they are stored, which is the part that makes this bearable to write down honestly: what makes the material portable between your agents does not make it readable by us.

Consider running both rather than switching

Most people asking this question do not actually want to leave; they want to try the other one. That is a smaller and safer move: give each agent its own git worktree so their edits cannot collide, put them in the same Thread so they share the notes and claim from the same board, and let the comparison happen on real work over a fortnight.

It also removes the deadline. If the second agent turns out to be better at one kind of task, you have not migrated - you have two agents, and the thing they both need is a shared place to write.

How to know the migration is actually done

Not on the first prompt, which will look fine. The test is the first genuinely awkward job: a debugging session on unfamiliar ground, or a change that touches the module everyone avoids. That is when a setup reveals what it had absorbed and you had stopped noticing.

Keep the old configuration until you have run one of those. It costs nothing to leave in place, and it is the only honest comparison available.