Codex CLI to Claude Code
Both tools are terminal coding agents with the same basic loop — you describe work, the agent reads and edits files and runs commands, you approve what matters. The friction is in the surrounding machinery: your instructions file changes name, your config moves from TOML to JSON, and Codex's clean two-axis safety model (sandbox × approval) is replaced by a single permission mode plus a rule list. This maps each piece across, and flags the places where the model genuinely differs rather than just renaming things.
Do this first: /import
Claude Code can read your existing Codex setup directly. Inside a session:
/import codex --dry-run
It picks up instruction files, MCP servers, commands, subagents and skills, and
merges rather than overwrites. Run it with --dry-run first to see
what it would write, then re-run without the flag. Requires Claude Code v2.1.213+
and isn't available on Bedrock, Google Cloud's Agent Platform, Microsoft Foundry,
or Claude Platform on AWS. It won't translate everything — Codex-specific
operational rules survive as literal text, so read the resulting
CLAUDE.md before trusting it.
Everyday equivalents
| In Codex CLI | In Claude Code |
|---|---|
Install and launch: npm i -g @openai/codex (or Homebrew), then codex. |
npm install -g @anthropic-ai/claude-code, then claude. There's also a native installer, a desktop app for Mac and Windows, a web version at claude.ai/code, and VS Code and JetBrains extensions. Same idea: run it from the repo root. |
Project instructions: AGENTS.md, resolved from the git root down to the working directory, with ~/.codex/AGENTS.md and AGENTS.override.md layered on top. |
CLAUDE.md, with the same nearest-wins layering: ~/.claude/CLAUDE.md for personal cross-project rules, ./CLAUDE.md committed for the team, and CLAUDE.local.md for personal per-repo notes. /init generates a starting file by reading the codebase, exactly as codex /init does. Note Claude Code also reads AGENTS.md if present, so a shared repo can serve both tools. |
Config file: ~/.codex/config.toml, TOML, with -c key=value for one-off overrides. |
.claude/settings.json (project, committed), .claude/settings.local.json (project, git-ignored) and ~/.claude/settings.json (personal, all projects) — JSON, layered most-specific-wins. The mental shift is that Claude Code splits config by scope where Codex splits it by profile. |
Profiles: [profiles.ci] blocks in config.toml, activated with --profile ci or CODEX_PROFILE=ci. |
No direct equivalent. The closest patterns are per-project .claude/settings.json committed to each repo, plus --permission-mode and --model flags at launch. If you relied on profiles to switch between a cautious local setup and a permissive CI one, express that as CI-only flags on the claude -p invocation instead. |
Safety model: two orthogonal axes — --sandbox (read-only, workspace-write, danger-full-access) controls capability, --ask-for-approval (untrusted, on-request, never) controls prompting. |
One axis plus a rule list. --permission-mode takes default, acceptEdits, plan, auto, dontAsk or bypassPermissions; on top of that, allow/ask/deny rules in settings govern individual tools and commands (for example, allow Bash(npm test) but ask for Bash(git push)). This is finer-grained than Codex per tool, but coarser about filesystem reach — there's no read-only sandbox that mechanically prevents writes. |
The Auto preset: --sandbox workspace-write --ask-for-approval on-request — edit freely in the workspace, ask before leaving it or touching the network. |
--permission-mode acceptEdits is the nearest equivalent: file edits apply without prompting, other tools still ask. Scope the filesystem with --add-dir / /add-dir to grant directories beyond the working one, and use deny rules for anything that must never run unattended. |
Switching modes mid-session: /approvals. |
Shift + Tab cycles permission modes inline, and the current mode shows in the status line. /permissions opens the rule editor for allow/ask/deny and working directories. |
Removing all guardrails: --yolo (equivalent to danger-full-access plus never). |
--dangerously-skip-permissions, equivalent to --permission-mode bypassPermissions. Same warning applies in both tools: containers and throwaway VMs only, never a machine holding credentials you care about. |
Plan before acting: no dedicated mode — you approximate it with --sandbox read-only and ask for a plan. |
Plan mode is first-class. Enter it with Shift + Tab or --permission-mode plan: Claude investigates and drafts an approach without touching files, then presents the plan for approval before any edits happen. This is the feature switchers most often say they didn't know they wanted. |
Headless / scripted runs: codex exec "task", with --json and -o output.md. |
claude -p "task", with --output-format text|json|stream-json. Combine with --permission-mode and explicit allow rules for CI. For anything more involved than a one-shot prompt, the Claude Agent SDK is the supported path to building custom agents around the same engine. |
Resuming work: codex resume --last, or codex exec resume <SESSION_ID>. |
claude -c continues the most recent conversation; claude -r <id-or-name> resumes a specific one; /resume opens a picker inside a session. Name sessions as you go with -n "auth-refactor" or /rename so the picker stays readable. |
Reusable workflows: skills in .agents/skills/, $REPO_ROOT/.agents/skills, $HOME/.agents/skills and /etc/codex/skills; invoked with $skill or picked implicitly. |
Skills in .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/ (personal). Same SKILL.md shape, same name and description frontmatter, same progressive disclosure — the description is always in context, the body loads only when used. Invoke with /skill-name or let Claude select on relevance. Concepts port almost directly; the directory and sigil change. |
Custom prompts: Markdown in ~/.codex/prompts/, invoked as /prompts:name, with $1 / $ARGUMENTS placeholders. Now deprecated in favour of skills. |
.claude/commands/name.md gives you /name, and still works — but custom commands have been merged into skills, so .claude/skills/name/SKILL.md is the forward path and gains supporting files and frontmatter control over who invokes it. Both ecosystems made the same move at roughly the same time; port straight to skills rather than to commands. |
| Delegating to another agent: no first-class subagent system in the CLI. | Subagents are defined as Markdown with frontmatter in .claude/agents/*.md (or ~/.claude/agents/), each with its own model, tool allowlist, and optionally an isolated git worktree. Claude spawns them via the Agent tool for fan-out work — broad codebase searches, parallel investigations — so the main context stays clean. Worth learning after you're comfortable with the basics; it's the biggest structural addition. |
Hooks: lifecycle hooks configured in config.toml, with admins able to lock them down via allow_managed_hooks_only in requirements.toml. |
Hooks live in settings.json under event names — PreToolUse, PostToolUse, Stop and others — each running a shell command that can inspect, block or annotate a tool call. Use them for the "every time X happens, do Y" rules that don't belong in CLAUDE.md, since the harness enforces hooks while instructions are only guidance. /hooks shows what's configured. |
MCP servers: [mcp_servers.name] blocks in config.toml with command, env and timeout_secs; codex mcp to manage, /mcp to list. |
claude mcp add to register, .mcp.json at the project root to share servers with the team, and /mcp to inspect and authenticate. OAuth-based servers are authorized interactively through /mcp rather than by pasting tokens into config. |
Choosing a model: /model, or model = "gpt-5.3-codex" in config.toml. |
/model, or --model with an alias (opus, sonnet, haiku, fable) or a full ID like claude-sonnet-5. Reasoning depth is a separate knob: --effort takes low, medium, high, xhigh, max or ultracode. |
Context management: /compact to summarize, /new to start clean. |
/compact [instructions] summarizes and accepts focus instructions; /context renders a grid of what's actually consuming your window, which is the faster diagnostic; /clear starts fresh. Rules, skills and memory files survive compaction. |
Undoing a bad run: git checkout and a new session. |
/rewind (or Esc Esc) rolls back both the code and the conversation to a checkpoint, so you can retry from before the agent went sideways without losing the useful part of the thread. |
Reviewing the working tree: /review. |
/code-review reviews the current diff, a branch, or a PR number, at an effort level you choose, with --fix to apply findings and --comment to post them inline on a PR. /security-review covers the security pass separately. |
Referencing files and images: @path mentions in the prompt. |
@path works the same way, with completion as you type. Paste or drag images in directly. --add-dir extends file access beyond the launch directory when you're working across sibling repos. |
Sharing a setup across a team: commit AGENTS.md; config and skills are largely per-machine under ~/.codex. |
Commit CLAUDE.md, .claude/settings.json, .claude/skills/, .claude/agents/ and .mcp.json, and keep personal overrides in .claude/settings.local.json (git-ignored by default). Plugins bundle skills, agents, hooks and MCP servers together for distribution via a marketplace — /plugin to manage. |
Common problems observed
What actually trips people up
-
Expecting a mechanical read-only sandbox. This is the real
model difference, not a renaming. Codex's
--sandbox read-onlymakes writes impossible; Claude Code's plan mode is a strong behavioural constraint plus permission checks, not an OS-level jail. If you were relying on the sandbox as a hard boundary — reviewing untrusted repos, say — reproduce it with a container or a VM rather than assuming a mode does it for you. -
Putting automation rules in
CLAUDE.md. "Always run the formatter after editing" in an instructions file is a suggestion the model may skip under load. The same rule as aPostToolUsehook is executed by the harness every time. Anything phrased "from now on, whenever X" belongs insettings.json, not the Markdown. -
Letting
CLAUDE.mdsprawl. It loads on every single turn, so long procedures there cost tokens continuously. A skill's body loads only when invoked. Rule of thumb: facts and constraints go inCLAUDE.md, procedures go in a skill. -
Assuming
/importfinished the job. It's deliberately conservative and skips anything ambiguous rather than half-translating it. Codex-specific phrasing survives verbatim intoCLAUDE.md, and hooks and profiles are the least portable pieces. Read the diff. - Missing plan mode for weeks. Coming from Codex there's no habit that leads you to Shift + Tab, so people keep approving edits one at a time on tasks where a plan-then-execute pass would have been far cheaper. Try it on the next multi-file change.
-
JSON settings with no schema in your head. After TOML profiles,
the three-file JSON layering is the fiddliest part of the move. Editing
settings.jsonby hand invites silent mistakes — use/permissionsand/hooks, or just ask Claude to make the change, rather than guessing at key names. -
Forgetting the config is layered, not merged by profile. A rule
in
.claude/settings.local.jsonquietly beats the committed project setting. When behaviour doesn't match the file you're looking at, check the more specific scope first.
Going the other way? See Claude Code to Codex CLI.