Aident AI
How to Migrate from Claude Code to Codex Without Losing Your Setup
Use OpenAI's official migrate-to-codex skill to scan your Claude Code setup, preview the mapping, run a dry migration, and validate the generated Codex files. Migrate instructions, skills, commands, hooks, subagents, and MCP configuration, but review every partial mapping before you delete or stop using the Claude Code source. Start a fresh Codex session with a short handoff document instead of assuming that a large Claude conversation can be resumed safely.
The practical rule is simple: migrate configuration as code, validate behavior, and keep the Claude setup as your rollback until the Codex project passes the same real task.
If you want a second-model review without moving the project, use Codex inside Claude Code for code review instead. The rest of this guide is for an actual project or user-configuration migration.
What Migrates and What Needs Review
The official migrator handles the common project surfaces, but the runtimes are not identical.
Claude Code source | Codex target | What to check |
|---|---|---|
|
| Claude-only commands, paths, and permission assumptions |
|
| Frontmatter, scripts, references, and permission guidance |
|
| Arguments, shell interpolation, file expansion, and routing |
|
| Tools, sandbox, model, skill preload, and delegation behavior |
|
| Transport, environment variables, headers, OAuth, and timeouts |
Hooks in Claude settings |
| Event coverage, matchers, blocking semantics, and async behavior |
Claude plugins and marketplaces | Manual migration | Bundled skills, agents, hooks, MCP servers, and plugin layout |
Some mappings are intentionally partial. For example, Codex does not treat a skill's allowed-tools field as a strict permission boundary, some Claude hook events have no Codex equivalent, and SSE MCP servers need a different transport. The migration report marks these cases for review.
Prerequisites
Before writing anything:
update Codex and confirm
codex --versionworks;install the official
migrate-to-codexskill;commit or back up the current project configuration;
identify whether you are migrating a project, global user configuration, or both;
list the real workflows that must still work, including hooks, subagents, and connected tools;
keep secrets out of copied config files and terminal output.
The commands below assume the skill is installed at .codex/skills/migrate-to-codex/ in the project. Adjust that path if you installed it globally.
Step 1: Scan Without Writing Files
Define the migrator command once:
Scan the project-level Claude configuration:
For global configuration, use:
Expected result: the report lists active and inactive instructions, commands, skills, hooks, agents, plugins, and MCP configuration without creating Codex files.
If expected files are missing, stop here. Confirm the source path and whether your MCP configuration lives in .mcp.json, project settings, or ~/.claude.json.
Step 2: Generate a Plan and Run Doctor
Preview the project targets:
Repeat with ~/.claude/ and ~/.codex/ if you also need the user-level setup.
Expected result: --plan names each generated path, while --doctor separates ready mappings from manual-review items and validation risks. Review the plan before running a write because project and global scopes can contain different instructions or MCP servers.
Step 3: Dry-Run Before the Real Migration
Run the same mapping without writing:
Inspect the proposed AGENTS.md, skills, agents, hooks, and config. In particular, check that the migration will preserve unrelated entries already present in .codex/config.toml.
Then run the migration:
Expected result: Codex artifacts are created or updated, and .codex/migrate-to-codex-report.txt records converted, partial, skipped, and manual-review items. Do not use --replace unless you deliberately want the migrator to remove orphaned generated skills or agents.
Step 4: Review Generated Files in Dependency Order
Review these files in order:
AGENTS.md.agents/skills/.codex/config.toml.codex/hooks.json.codex/agents/plugin and marketplace items in the migration report
That order keeps shared instructions and tool access stable before you evaluate specialized agents.
Instructions
OpenAI's AGENTS.md documentation explains how Codex discovers project instructions. Remove references that only make sense in Claude Code, such as Claude slash commands or .claude/agents/ paths. If the instructions are provider-neutral, keep one shared source instead of duplicating two documents that will drift.
Skills and commands
Codex discovers reusable workflows as skills. A Claude command may become a generated skill, but placeholders such as $ARGUMENTS, shell-output interpolation, model routing, and automatic file expansion can require a rewrite. Test a concrete invocation rather than trusting the converted text.
MCP servers
Codex stores MCP server configuration in config.toml. Confirm each command, URL, environment variable, header, and timeout. The official mapping supports stdio and Streamable HTTP, but not an SSE-only server. Environment-variable fallbacks and some OAuth fields also need manual work.
For a large catalog, do not make migration harder by loading every tool into every session. Reduce MCP token usage by narrowing the tool surface or discovering tools only when needed.
Hooks and subagents
Claude Code hooks and subagents do not map one-to-one. Verify what can block a command, which matchers still run, what sandbox a subagent inherits, and whether a skill that was previously preloaded now needs explicit instructions. Treat a generated hook or agent marked for review as disabled in your confidence model until its behavior is tested.
Step 5: Validate the Target
Run the official validator:
The validator checks configuration syntax, skill frontmatter, custom-agent fields, instruction size, and MCP command availability. Fix every actionable generated-artifact error, then rerun both validation and the dry-run:
Expected result: the target validates, and the second dry-run reveals no unexplained drift from the source.
Step 6: Test One Real Workflow End to End
Static validation does not prove that the migrated setup behaves the same. Choose one representative task that uses instructions, a skill or subagent, and an external tool. Record:
the prompt and expected result;
which instruction and skill Codex selected;
which tool or MCP server it used;
whether a hook allowed, blocked, or modified the action as intended;
the command, test, or external read that verifies the outcome.
Run the task in a disposable branch or staging-safe environment. Keep the Claude setup available and compare the results. The migration is complete only when the Codex result meets the same acceptance criteria, not merely when the files exist.
Preserve Session Context With a Handoff, Not a Blind Import
Configuration and conversation history are different migration problems. A July 2026 Codex issue about imported Claude sessions reported that very large compacted histories could exceed the model input limit after import. That is a specific reported failure, not proof that every session import fails.
For an active project, create a short handoff.md outside the permanent agent instructions with:
the current objective and accepted decisions;
files changed and commands already run;
unresolved errors or risks;
the next concrete step;
links to the issue, plan, or pull request that holds durable context.
Start a fresh Codex session, ask it to read the repository instructions plus the handoff, and verify its understanding against the current diff. Do not paste secrets, full chat logs, or stale exploratory detail into the handoff.
Common Migration Failures
Codex Ignores the Migrated Instructions
Confirm the file is named AGENTS.md, is in the expected directory hierarchy, and does not exceed the configured instruction limit. Remove Claude-only path assumptions, then start a new session so discovery runs again.
A Skill Exists but Behaves Differently
Inspect its frontmatter and any manual-migration block. Rewrite Claude runtime features as explicit Codex instructions or scripts, then test one invocation with known inputs and an observable result.
An MCP Server Does Not Start
Run the configured command directly, verify required environment variables exist, and check whether the source used SSE. Migrate SSE-only servers to stdio or Streamable HTTP, and compare the generated authentication fields with the provider's current documentation.
Hooks No Longer Block the Same Actions
Do not assume event names imply identical behavior. Check Codex's current hook coverage and exit-code contract, then test a harmless command that should be allowed and one that should be denied.
Existing Codex Configuration Was Overwritten
Restore the committed file, rerun --plan and --dry-run, and merge only the generated sections you reviewed. Avoid --replace unless removing generated orphans is the explicit goal.
Keep Tool Access Portable Across Claude Code and Codex
Instructions and skills can be stored in the repository, but provider credentials should not be copied between agent configuration files. Aident Loadout gives Claude Code and Codex a shared, scoped way to discover and run connected Actions while credentials remain outside prompts and project files.
Ask either coding agent:
Then connect one staging-safe integration and test the same read-only task in both agents. For the architecture tradeoff, see Local vs Remote MCP Servers and Connect Claude Code and Codex to Real-World Tools.
Use Aident Loadout to run the check. The measurable goal is one successful, equivalent read-only tool call from Claude Code and Codex without copying a provider secret into either configuration.
Sources
Refresh this guide when OpenAI changes the migrator's supported mappings, Codex hook coverage, plugin migration behavior, or session-import handling.
