How to move your workflow from Claude Code to Codex (and back)

Short answer: most of your workflow is already portable, because it lives in the repository rather than the tool. What travels by itself: project instructions, scripts, tests and conventions. What needs translating: the instruction filename, custom commands and MCP server configuration. Budget an hour, not a week.

What travels effortlessly

Everything that belongs to the project. Both AI agents read your repository files, run your commands and follow your conventions. If your workflow rests on a verification script, a test suite and a document explaining the house rules, it is already portable and you will barely notice the switch.

Good argument for investing in the repository over the tool configuration: the first survives a switch, the second does not.

What needs translating

• The instruction file. Claude Code reads CLAUDE.md, Codex reads AGENTS.md. Do not copy the content: have one point at the other, or they drift within two weeks.
• Custom commands. Each tool has its own format and folder. Mechanical rewriting, and where the hour goes.
• MCP servers. Same protocol, different configuration file. The server itself works in both.
• Hooks and automation. Different formats, same idea.

What does not travel at all

Conversation history. Sessions belong to the tool and there is no shared format. If you depend on a long conversation full of context, switching costs restarting it: worth writing into the repository whatever was decided there, before you switch.

Do you have to choose?

No, and that is what many people find out late. Both tools read the same repository and can coexist. Running both gives you something switching does not: ask the same review of models from different companies and the points where they disagree map what deserves your attention.

What if I run both at once?

Then one real precaution applies: they must not edit the same files at the same time. Two AI agents in one directory overwrite each other with no error on screen. Give each its own copy of the project, on a separate branch, with git worktree.

Worth trying before committing?

Yes, and it is cheap: install the second tool, point its instruction file at the one you already have, and hand it a real task. A real task tells you more than any comparison, including this one.