Switching Guides

Practical, no-nonsense references for moving between tools.

All guides › Claude Code to Codex CLI

Claude Code to Codex CLI

The day-to-day loop is the same — describe work, watch the agent read, edit and run things, approve what matters — so the adjustment is mostly about where configuration lives and how permission is expressed. Codex splits safety into two independent controls (what the agent can do, and when it must ask), which is more explicit than Claude Code's single permission mode once it clicks. The costs are real too: no plan mode, no subagents, and settings that move from layered JSON to a single TOML file with profiles.

Verified against docs current in August 2026 — both tools ship weekly, so treat version-specific details as a starting point. Sources: Codex approvals & security and Codex skills.

Do this first: /import

Codex can read your existing Claude Code setup. Inside the Codex TUI, run /import (a slash command, not a codex subcommand — added in v0.140.0 and broadened in v0.145). It scans for Claude Code skills, hooks, MCP servers, subagents, instruction files and recent session history, and shows only what isn't already configured. Existing Codex settings are preserved — values merge additively rather than overwriting.

Your CLAUDE.md maps onto AGENTS.md, with Claude-specific terminology rewritten but operational rules kept. Rules that assumed Claude Code tooling — references to specific tool names, or hook-driven behaviour — come through as literal text, so read the generated AGENTS.md before relying on it.

Everyday equivalents

Claude Code concepts and their Codex CLI counterparts. Scroll sideways on narrow screens.
In Claude Code In Codex CLI
Install and launch: npm install -g @anthropic-ai/claude-code (or the native installer), then claude. npm i -g @openai/codex, or brew install codex, then codex. There's a VS Code extension too, plus Codex cloud for running work remotely from the ChatGPT app. Note the IDE extension doesn't read the .codex folder the way the CLI does, so local config won't carry into it.
Project instructions: CLAUDE.md, layered as ~/.claude/CLAUDE.md → ./CLAUDE.md → CLAUDE.local.md, nearest wins. AGENTS.md, resolved ~/.codex/AGENTS.override.md → ~/.codex/AGENTS.md → then git root down to the working directory, with AGENTS.override.md ahead of AGENTS.md at each level. Same nearest-wins idea, more layers. /init scaffolds one from the codebase. Since Claude Code also reads AGENTS.md, a repo shared by both tools can standardize on that filename.
Config files: .claude/settings.json (committed), .claude/settings.local.json (git-ignored) and ~/.claude/settings.json, layered most-specific-wins. A single ~/.codex/config.toml, with -c key=value for one-off overrides at launch. Flags and -c beat config files. The shift is from splitting config by scope to splitting it by profile — worth planning before you migrate, because per-repo committed settings don't have a clean equivalent.
Per-project settings committed to the repo so the whole team inherits them. Profiles in config.toml — [profiles.ci], [profiles.dev] — activated explicitly with --profile ci or CODEX_PROFILE=ci. They're per-machine, so team-wide defaults have to travel through AGENTS.md and documented profile snippets rather than a committed settings file.
Permission model: one --permission-mode (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) plus allow/ask/deny rules for individual tools and commands. Two independent axes. --sandbox sets capability: read-only, workspace-write (default) or danger-full-access. --ask-for-approval sets prompting: untrusted, on-request or never. You compose them — for example read-only capability with no prompts for a safe analysis run. Coarser than Claude Code per-tool rules, but the filesystem boundary is enforced rather than negotiated.
acceptEdits: edits apply without prompting, other tools still ask. The Auto preset: --sandbox workspace-write --ask-for-approval on-request. Codex reads, edits and runs commands inside the working directory freely, and asks before touching files outside the workspace or reaching the network. Without flags, Codex checks for version control and suggests Auto for tracked repos, read-only for untracked folders.
Cycling modes mid-session: Shift + Tab, with /permissions for the rule editor. /approvals switches presets during a session. There's no equivalent to Claude Code's granular allow/deny rule list — you can't pre-approve Bash(npm test) while still gating Bash(git push), so expect either more prompts or a broader grant than you're used to.
Removing all guardrails: --dangerously-skip-permissions. --yolo, which is danger-full-access plus never. Same rule of thumb in both tools: disposable containers only.
Plan mode: investigate and draft an approach with no file writes, present it, then execute on approval. No dedicated mode — this is the most-missed feature in this direction. The workable substitute is --sandbox read-only with an explicit "propose a plan, don't implement" prompt, then switch to Auto via /approvals once you've agreed. Mechanically stricter than plan mode, but it's two steps you have to remember rather than one keystroke.
Headless / scripted runs: claude -p "task" with --output-format text|json|stream-json. codex exec "task", with --json for structured events and -o output.md to write results to a file. Watch out in CI: codex exec --full-auto was removed in v0.147.0 after long deprecation, so older scripts now error — replace it with --sandbox workspace-write plus an explicit approval flag or a profile.
Resuming work: claude -c, claude -r <id-or-name>, /resume. codex resume --last for the most recent session, or codex exec resume <SESSION_ID> for a specific one in headless mode.
Skills: .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/ (personal); invoked as /skill-name or selected automatically. Same SKILL.md format and the same progressive-disclosure model, different paths and sigil: .agents/skills in the current directory, $REPO_ROOT/.agents/skills, $HOME/.agents/skills, and /etc/codex/skills for machine-wide defaults. Invoke explicitly with $skill, or let Codex pick on relevance. Note the initial skills list is capped (roughly 8,000 characters or 2% of context), so keep descriptions tight.
Custom commands: .claude/commands/name.md → /name, now merged into skills. Custom prompts in ~/.codex/prompts/, invoked as /prompts:name, supporting description and argument-hint frontmatter plus $1 / $ARGUMENTS placeholders. Only top-level .md files are scanned, and they're per-machine rather than shared through the repo. These are deprecated in favour of skills — port to skills directly rather than to prompts.
Subagents: .claude/agents/*.md with their own model, tool allowlist and optional isolated worktree, spawned for parallel or fan-out work. No first-class CLI equivalent. Codex's /import will read your subagent definitions, but there's no delegation primitive to run them the same way. Plan to fold that work back into the main session, split it across separate codex exec invocations, or use Codex cloud for parallel remote runs.
Hooks: PreToolUse, PostToolUse, Stop and friends in settings.json, enforced by the harness. Lifecycle hooks configured through Codex config. In managed environments an admin can set allow_managed_hooks_only = true — note that this only works in requirements.toml; putting it in config.toml does nothing. Check current docs for the event names, since this area is younger than the Claude Code equivalent.
MCP servers: claude mcp add, a shared .mcp.json at the project root, /mcp to inspect and authenticate. TOML blocks in config.toml: [mcp_servers.my-db] with command, env and timeout_secs. Manage with codex mcp, list active tools in-session with /mcp. Because servers live in your personal config rather than a committed project file, team-shared MCP setups need documenting rather than checking in.
Choosing a model: /model or --model with an alias (opus, sonnet, haiku, fable); --effort for reasoning depth. /model in session, or model = "gpt-5.3-codex" in config.toml. Reasoning effort is a config setting rather than a launch flag, so it's a natural thing to bind to a profile.
Context management: /compact [instructions], /context for a usage breakdown, /clear. /compact to summarize and /new to start a fresh conversation. There's no direct analogue to /context's visual breakdown, so keep an eye on session length yourself and start clean more often.
Undoing a bad run: /rewind or Esc Esc to roll back code and conversation to a checkpoint. No built-in checkpoint rollback. Lean on git: commit or stash before handing over a risky task, and use git checkout plus /new to reset. This is the change most likely to bite you in the first week.
Reviewing changes: /code-review over a diff, branch or PR, with --fix and --comment; /security-review alongside it. /review analyses the working tree, and the IDE extension adds /review plus /cloud, /local, /auto-context and /status for switching between local and cloud execution.
Referencing files: @path mentions, --add-dir to widen filesystem access. @path works the same. Filesystem reach is governed by the sandbox instead of an explicit directory list — workspace-write means the working directory, and anything beyond it triggers an approval prompt under on-request.

Common problems observed

What actually trips people up

Going the other way? See Codex CLI to Claude Code.

← Back to all guides