Migrate Claude Code to Codex (2026): 12 Configs, 1 Dead End

You can move nearly your whole Claude Code setup to Codex in about 20 minutes. Here is the decision before you scroll:

Almost everything moves, because the two tools solve the same problem with different file formats. The migration is largely a translation between two dialects.

Here is the full surface map. Save this table; it is the whole migration in one screen.

Rows 9 and 11 are cosmetic. You will not miss outputStyle, and ConfigChange only matters if you built automation that reacts to a config file changing mid-session. Row 12 is the one that stops people, and it has a clean fix most migration guides skip.

Migrate when your work is task-shaped and you want tighter sandboxing; stay on Claude Code when your work is conversation-shaped and hook-driven. The two tools carry different mental models, and the config differences follow from that.

Before you touch config, confirm the four prerequisites below. A stale Codex is the most common reason /import and the [features] blocks silently do nothing.

• Codex CLI 0.140.0 or newer. Check with codex --version. The /import command landed in 0.140.0; this guide was tested on 0.142.5.
• Your existing Claude Code project, with its .claude/ directory and CLAUDE.md intact. Do not delete it until the migration is verified.
• An API key for whichever provider will drive Codex. OpenAI by default, or a gateway key if you are keeping Claude models.
• Write access to ~/.codex/. Codex reads ~/.codex/config.toml on every invocation and, in trusted projects, .codex/config.toml at the repo root.

Run the automated importer first, then walk the five surfaces it cannot fully handle. Do not skip the manual passes — the importer is honest about what it leaves behind, but it does leave things behind.

Step 1: Run the Importer

Start Codex in your project and import. Codex 0.140 added /import for selectively pulling setup, project configuration, and recent chats from Claude Code. Pick the surfaces you want.

cd my-project
codex
# then, inside the session:
/import

Expected result: a populated ~/.codex/config.toml, an AGENTS.md draft, and a short report listing anything it skipped or flagged as a conflict.

Step 2: Instructions, CLAUDE.md to AGENTS.md

Codex reads AGENTS.md, not CLAUDE.md. If the importer did not already create one, either rename your file or tell Codex to keep reading the old name.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768

Expected result: your repo-level instructions load into Codex context on the next run. The content carries over unchanged; only the filename and load path differ — which is why the AGENTS.md convention exists across tools in the first place.

Step 3: MCP Servers, JSON to TOML

The MCP processes are identical. Only the declaration changes shape. A Claude Code .mcp.json entry like this:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

becomes a TOML table in ~/.codex/config.toml:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

Expected result: codex lists the github MCP tools on startup. If a server needs environment variables, add them inline: env = { "GITHUB_TOKEN" = "..." }. Both transports carry over: Codex accepts the same STDIO command-based servers you ran in Claude Code, and it also takes streaming HTTP servers in the same table, so a remotely hosted MCP endpoint moves without spawning a local process.

Step 4: Subagents to .codex/agents/

Claude Code stores subagents as Markdown in .claude/agents/. Codex stores each subagent as its own TOML file, one file per agent, under ~/.codex/agents/ (personal) or .codex/agents/ (project-scoped). Subagents are enabled by default, so there is no feature flag to flip.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
developer_instructions = """
Review the diff for correctness and style. Cite file and line for each issue.
"""

Expected result: the reviewer role becomes available through Codex's subagent workflow, which Codex invokes only when you explicitly ask for it. The prompt body from your old Markdown file moves into developer_instructions; the wrapper is what changes. If you had many subagents, this is the most tedious manual pass, but it is mechanical.

Step 5: Permissions to Sandbox and Approval

This is the surface that genuinely breaks, because the two tools model safety differently. Claude Code uses a per-command allowlist with glob rules. Codex uses two coarse dials: a filesystem sandbox and an approval policy. There is no clean one-to-one mapping, so you port intent, not rules.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Expected result: Codex runs freely inside the repo and asks before touching anything outside it or reaching the network. The granular per-command control you had in Claude Code does not survive; if you relied on a long, precise allowlist, accept that Codex's model is blunter by design.

Step 6: Hooks

Codex has hooks now, enabled by default, and they cover most of Claude Code's events. You declare them as array-of-tables blocks in config.toml; to turn the whole system off you would set [features] hooks = false.

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"          # same idea as Claude Code's PreToolUse matcher

  [[hooks.PreToolUse.hooks]]
  type = "command"
  command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"

Expected result: PreToolUse, PostToolUse, SessionStart, Stop, and even PreCompact/PostCompact fire as they did in Claude Code, once you translate the JSON handler into TOML. The one gap is ConfigChange, which has no Codex event — any automation you built to react to a config file changing mid-session is the one part of your hook setup that does not come along.

The single migration step with no native answer is keeping your Claude models, because vanilla Codex authenticates against OpenAI and drives OpenAI models such as gpt-5.5 and gpt-5.4. There is no built-in switch that selects Claude Opus or Sonnet. If you migrated to Codex for its sandbox and workflow but still want Opus writing your code, you need a bridge.

The bridge is a custom model_provider. Codex will talk to any OpenAI-compatible gateway, so you register one and point a profile at a Claude model. Add the provider to ~/.codex/config.toml:

# ~/.codex/config.toml — register an OpenAI-compatible gateway

[model_providers.gateway]
name = "your gateway"
base_url = "https://your-gateway.example/v1"
env_key = "GATEWAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Two details trip people up. Both are about how Codex negotiates the wire protocol, not about the gateway itself.

Then create a profile file at ~/.codex/claude.config.toml:

model = "anthropic/claude-opus-4.8"
model_provider = "gateway"

Run it with codex --profile claude. Now Codex's task loop and sandbox drive Anthropic's anthropic/claude-opus-4.8, and swapping model = "openai/gpt-5.5" in a second profile lets you A/B the two without changing auth. This is the one migration surface where a gateway is not a convenience but the only way to keep what you came for.

Six failures cover almost every stuck migration. The pattern is the same each time: a Claude Code assumption that Codex does not share.

If a project's .codex/config.toml is being ignored entirely, check that the project is marked trusted. Codex only loads project-scoped config in trusted directories, and it will not let a project file override provider, auth, or profile selection.

For a team, the migration is cleaner than the solo case, because Codex collapses two Claude Code files into one committed config. In Claude Code you shipped a .claude/settings.json for the team and let each developer keep a gitignored .claude/settings.local.json. In Codex, you commit a single .codex/config.toml at the repo root and let each developer select a profile.

The team payoff is the same gateway trick from the dead-end section, applied once. Register one model_provider in the committed config, hand every developer the same gateway key scheme through your secret manager, and the whole team routes through one endpoint with one billing view — whether they run openai/gpt-5.5 or anthropic/claude-opus-4.8. That single-endpoint routing is the concrete reason a shared gateway beats per-developer provider keys.

Profiles are where Codex pays back the migration effort, because they replace the Claude Code habit of juggling settings.json against settings.local.json. A profile is a separate file under ~/.codex/, and you select it per run with --profile. Nothing changes globally until you decide it should.

Create three files for three risk postures. The base config.toml holds the shared pieces — providers, MCP servers, and hooks; each profile overrides only the two or three keys that differ. That single-file discipline is what makes the Codex setup easier to reason about than the Claude Code scope stack, once the migration is behind you.

# ~/.codex/ci.config.toml

model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"

Run automated review in CI with codex --profile ci, and it can read everything but change nothing. Keep a local.config.toml at workspace-write for day-to-day work, and the claude.config.toml from the dead-end section that swaps the driver to anthropic/claude-opus-4.8 when you want Anthropic's model on a hard problem.

Most migration guides sell the rename. The real lesson is that your tooling config is not the tool — it is a contract, and Codex's contract is blunter and more composable than Claude Code's.

When a surface "breaks," it usually means the new tool chose a coarser abstraction on purpose. Codex's two-dial sandbox replaces a per-command allowlist because coarse dials survive a team of twenty developers touching the same repo; a hand-tuned allowlist does not. That is a trade-off, not a bug.

The dead end is the honest part. No vendor is going to make it trivial to run a competitor's model inside their CLI. The fact that the fix is a single model_provider block — and not a fork or a wrapper script — tells you Codex treats providers as pluggable. The migration that matters is the one that keeps your options open.

Migrating your tooling to Codex should not mean giving up the models you migrated for, and with one provider block it doesn't.

The migration that matters isn't the rename — it's the one that keeps your models pluggable, your sandbox honest, and your options open.

• OpenAI Codex Configuration Reference
• OpenAI Codex Changelog
• OpenAI Codex Hooks Reference
• Claude Code Settings Reference

About FACTA

FACTA is an AI consulting firm. We design agent systems, build the workflows around them, and help teams adopt AI without betting the farm on a single vendor.

We write these guides because the hardest part of AI tooling is rarely the model — it is the config, the sandboxing, and the contracts you sign with your tools. A migration is a good time to look at those contracts instead of just renaming them.

If you are weighing a Claude Code → Codex migration, or want a vendor-neutral agent stack that keeps your options open, we can help.

Vendor-neutral by design. Pluggable by habit.