Migrating from Claude Code to Codex

If you have built a workflow around Claude Code and you are looking at OpenAI's Codex CLI, the good news is that the two tools rhyme. Both are terminal coding agents that read your codebase, edit files, run commands, and talk to Model Context Protocol (MCP) servers. The concepts you already know mostly carry over. What changes is the vocabulary and, in a few important places, the safety model.

This is a practical migration map, checked against the current Codex documentation as of mid-2026. It walks the four things people actually get stuck on: the permission flags (especially the dangerous one), the headless mode you script against, whether your skills and instructions come with you, and where the config lives. A caveat up front: Codex moves fast, and a couple of specifics below are flagged as worth confirming against your installed version. Verify before you wire anything load-bearing to it.

The mental map

Codex CLI today is an open-source coding agent, rewritten in Rust, that runs in your terminal with OS-level sandboxing. It has nothing to do with the old 2021 Codex model that shared the name. You install it with npm install -g @openai/codex, brew install --cask codex, or the install script, and on first launch it prompts you to authenticate, either by signing in with a ChatGPT plan (best for interactive use) or with an API key (better for scripts and continuous-integration jobs, where billing on the API surface is what you want).

At a high level the pieces line up like this:

Most rows are a rename. Two rows, the permission model and the subagent format, are genuine differences you have to think about. Start with the one that matters most for safety.

Permissions: the dangerous flag and its safer alternative

In Claude Code, --dangerously-skip-permissions is a single switch that turns off the approval prompts. It is one lever, and the name is the whole warning.

Codex splits that single lever into two independent axes, which is the most important thing to understand in the whole migration:

• `--sandbox` controls what the operating system will let the process touch: read-only, workspace-write (the default: read, edit, and run inside the working directory, but not outside it and not on the network), or danger-full-access.
• `--ask-for-approval` controls when Codex pauses to ask you: untrusted, on-failure, on-request (the default), or never.

The sandbox is enforced by the OS, not by the model's good intentions. On macOS it runs under Apple's Seatbelt via sandbox-exec; on Linux it uses bubblewrap with seccomp, and newer builds lean on Landlock. Network access is blocked inside the sandbox by default. This is a real containment boundary, which is exactly why splitting it out from the approval prompts matters.

The direct analog to --dangerously-skip-permissions is `--dangerously-bypass-approvals-and-sandbox`, aliased --yolo. It disables both axes at once: no approvals and no sandbox. As with the Claude Code equivalent, that is appropriate only inside a throwaway container you have already isolated, and reckless pointed at anything you care about.

Here is the part the two-axis design buys you, and the honest answer to "what's the alternative to running with no guardrails." You do not have to trade all safety for autonomy. You can keep the OS sandbox on and loosen only the *approvals*:

bash codex --sandbox workspace-write --ask-for-approval never "refactor the auth module and run the tests"

That runs the agent autonomously, without stopping to ask, while the operating system still confines it to the workspace with no network. You get hands-off execution and a hard containment boundary at the same time, the middle ground that --yolo throws away. This is the safer default for CI and for long autonomous runs, and it is a genuine improvement on a single all-or-nothing bypass. (--full-auto is shorthand for a similar low-friction, still-sandboxed combination.)

Headless mode: codex exec in place of claude -p

If you script against `claude -p`, the equivalent is codex exec (alias codex e): run Codex non-interactively, stream the result to stdout, and exit. The shapes you rely on all have counterparts.

bash codex exec "summarize the open TODOs in this repo" # prompt as an argument echo "explain this failure" | codex exec - # "-" reads the prompt from stdin codex exec --json "review the diff" # newline-delimited JSON events codex exec -o out.txt "draft release notes" # write only the final message to a file

The reflexes transfer cleanly. --json gives you JSONL (one JSON event per state change) for when a script needs to consume the run rather than a person reading it, the same role --output-format json plays in Claude Code. --output-last-message (-o) writes just the assistant's final message, which is usually the clean thing to capture in CI. And the global flags compose, so a typical pipeline step reads:

bash codex exec --sandbox workspace-write --json --output-last-message output.txt "run the test suite and fix failures"

Same idea as before: settle the sandbox and approval posture up front, because a headless run has no one at the keyboard to answer a prompt.

Skills, instructions, and subagents: what actually migrates

This is the section that has changed the most, and mostly in your favor. The honest per-piece breakdown:

• Project instructions carry over by copy-paste. Codex reads AGENTS.md automatically, the same role CLAUDE.md plays. It discovers them from the repo root down to your working directory and concatenates them, with closer files overriding, up to a byte budget (32 KiB by default). Moving your project memory across is a rename and a paste.
• Skills map almost one-to-one. Codex now has a real Skills system built on the same shape as Anthropic's: a directory containing a SKILL.md with YAML frontmatter (name and description) plus optional scripts and references. Codex can invoke them explicitly (via a /skills command or $skill-name) or select them implicitly when your task matches the description. The concept ports directly. One caveat worth stating plainly: the formats are close and both reference an open skills standard, but OpenAI does not promise binary drop-in compatibility, and the exact directory Codex scans for skills differs across documentation versions, so confirm the path against your installed CLI rather than assuming.
• Subagents have to be rewritten. Both tools support subagents, but the file format differs: Claude Code uses Markdown with frontmatter, Codex uses TOML files (under ~/.codex/agents/ or a project's .codex/agents/), each declaring name, description, and developer_instructions. These do not carry over automatically; you re-author them, though it is mechanical work.
• Old-style custom prompts should become skills. Codex still reads Markdown prompt files but now marks them deprecated and steers you toward Skills instead. If you have a library of custom prompts, convert them; Codex ships a skill-creator skill to do exactly that.
• MCP servers carry over. Codex is a full MCP client (and can run as an MCP server itself). Add one with codex mcp add <name> -- <command> [args...] for a local stdio server, or --url for a streamable HTTP server, and manage them in-session with /mcp. If you have already done the work of defining an MCP server, that authority boundary moves with you rather than being rebuilt.

Config lives where you would guess: ~/.codex/config.toml for user settings and .codex/config.toml for a trusted project, with model, approval_policy, sandbox_mode, and [mcp_servers.*] blocks as the keys you will touch most. Per-invocation -c key=value overrides win, and named profiles layer on top.

Do you even need to migrate?

Often, less than you would expect. Your AGENTS.md is a paste of your CLAUDE.md. Your skills map onto Codex skills with the same SKILL.md shape. Your MCP servers reconnect with one command each. The two things that require real work are re-authoring subagents into TOML and converting any deprecated custom prompts into skills, both mechanical, neither large.

The judgment call is not mechanical, though. Moving coding agents is worth doing when the model, the pricing, or the sandbox model genuinely fits your work better. Codex's OS-level sandbox and its two-axis permission design are real advantages for autonomous and CI runs. Churning tools for its own sake is not. If your Claude Code setup is serving you, the rename table above is mostly a reason to stay put with confidence, not a reason to churn. The right move is the one your actual workflow rewards, which is the same test we would apply to any tool.

How XY Space thinks about it

XY Space treats the coding agent as a replaceable component, not a religion. What we care about is the structure around it, where authority is granted, where a run is contained, and where a human stays in the loop, because that structure is what makes automation safe regardless of which agent is executing. The reason the Codex migration is mostly painless is that the durable parts (instructions, skills, MCP boundaries) are portable by design, and the parts that differ (the permission model) are exactly the parts worth thinking hard about anyway.

That is the lens we bring to every system we build: the tool underneath should be swappable, and the guardrails (least-privilege permissions, real sandboxing, verification at the consequential steps) should be the constant. Codex's split between sandboxing and approvals is a good example of that principle showing up in a product, and it is the same discipline behind every agentic workflow we deploy. If you want help building automation that outlasts whichever agent is in fashion, talk to us.

Sources

• OpenAI Codex CLI (GitHub)
• Codex CLI documentation
• Agent approvals and security
• Codex developer command reference (`codex exec`)
• Custom instructions with AGENTS.md
• Build skills for Codex
• Model Context Protocol in Codex