Migrating from Codex CLI to Claude Code: commands, config, agents, and hooks

July 29, 20269 minClaude Code, Codex CLI, OpenAI, Anthropic, AI, Developer Tools, CLI, Migration

Codex CLI (OpenAI) and Claude Code (Anthropic) solve the same problem: having a coding agent inside the terminal that reads your repo, edits files, runs commands, and hands control back to you when something needs your eye. The difference is in the details — and the details are what break your flow when you migrate without thinking it through.

This guide is for developers who already use Codex CLI and want to move to Claude Code (or evaluate it in parallel) without losing the work they already did: the AGENTS.md you wrote, the config.toml with your sandbox and approval policy, the external scripts you run as wrappers. We map commands one-to-one, translate the config, show how to convert a long AGENTS.md into a reusable agent, and close with a real example of a lifecycle hook.

When NOT to migrate. If you depend on Assistants API, GPT Store, OpenAI fine-tunes, or any feature specific to the OpenAI ecosystem, Claude Code does not cover that. For those cases, Codex CLI is still the right choice. This guide assumes your usage is CLI-level (agent in the repo), not API-level (embedded product).

Install + setup (5-10 min)

Codex CLI:

install-codex.sh
# macOS / Linux
npm install -g @openai/codex
# or
brew install codex

# Sign in (OAuth auth in the browser)
codex login

Claude Code:

install-claude.sh
# macOS / Linux / WSL
npm install -g @anthropic-ai/claude-code

# Sign in
claude
# follow the OAuth browser instructions

Config paths after install:

• Codex: ~/.codex/config.toml + AGENTS.md (project)
• Claude Code: ~/.claude/settings.json + ~/.claude.json + CLAUDE.md or .claude/CLAUDE.md (project) + .claude/settings.json (project)

Day-to-day command mapping

The three operational differences you will notice most:

1. Codex CLI has no /compact or /clear. If the context grows, Codex relies on the model's automatic summarization; Claude Code gives you explicit commands to reset or compact manually.
2. Codex CLI has no native commit command. The usual pattern is codex exec "commit the staged changes with a conventional message". Claude Code has claude commit which drafts the message by reading the diff, the same way cz commit or git cz works.
3. /init exists in both but the destination file changes: Codex generates AGENTS.md, Claude Code generates CLAUDE.md with the project structure it detected from the repo.

Persistent config: TOML to JSON

Codex CLI:

~/.codex/config.toml
model = "gpt-5"
model_provider = "openai"
approval_policy = "on-failure"
sandbox = "workspace-write"

[providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
wire_api = "responses"

Claude Code:

~/.claude/settings.json
{
"model": "claude-sonnet-5",
"permissions": {
  "defaultMode": "acceptEdits",
  "allow": ["Bash", "Edit", "Read"],
  "deny": ["Bash(rm -rf:*)"]
},
"env": {
  "ANTHROPIC_API_KEY": "sk-ant-..."
}
}

Field-by-field mapping:

The mental model shift: Codex separates sandbox (what can touch disk) from approval_policy (when to ask for confirmation). Claude Code unifies both into permissions with defaultMode and allow/deny lists per tool. defaultMode can be acceptEdits (edit without asking, but Bash commands require permission) or bypassPermissions (everything passes) or plan (only proposes, does not execute).

Custom commands and agents

Codex CLI has no user-defined slash commands. The closest thing is your AGENTS.md, which the agent reads as a persistent system prompt per project. If you wanted a custom command ("review only performance"), you built it as a shell script that called codex exec with a pre-assembled prompt.

Claude Code has two separate primitives:

1. Slash commands (simple, no own tools): a .md file at ~/.claude/commands/foo.md, invokable as /foo. Ideal for prompts you want to reuse with a short name.
2. Sub-agents (with their own system prompt and restricted tools): a .md file at ~/.claude/agents/foo.md with frontmatter for name, description, and tools. The main agent invokes them via the Task tool when they fit.

Typical migration: your long AGENTS.md.

If your AGENTS.md has 200 lines with mixed sections ("repo rules", "reviewer persona", "naming conventions"), split it in Claude Code:

CLAUDE.md (project root)
# Repo rules

- Language: strict TypeScript
- Tests: Vitest, not Jest
- Style: Prettier + ESLint with the repo config
- Commits: conventional commits, no co-author

.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews PRs flagging only security and performance issues
tools: Read, Grep, Glob, Bash
---

You are a strict code reviewer. Your job is to read the diff and report:

1. Security vulnerabilities (injection, XSS, hardcoded secrets).
2. Performance issues (avoidable O(n²), N+1 queries, memory leaks).
3. Nothing else. Do not comment on style or naming.

Report format: numbered list with file:line and concrete fix.

.claude/agents/refactor-planner.md
---
name: refactor-planner
description: Proposes refactor plans for legacy code without touching anything
tools: Read, Grep, Glob
---

When invoked, read the file or directory given and return a
refactor plan in numbered steps. Each step: (a) what changes,
(b) which files it touches, (c) how to verify nothing broke.

Do not modify files. Only the plan.

The main agent now invokes code-reviewer when you ask it to "review this PR" and refactor-planner when you ask it to "make me a plan to refactor X". It is a natural mapping of what used to be an external script with a pasted prompt.

Hooks and automation

Codex CLI: no hooks. The only automation is AGENTS.md (static instructions) plus external scripts you invoke manually.

Claude Code has lifecycle hooks declared in settings.json. Each hook is a shell command that receives the event context as JSON on stdin.

~/.claude/settings.json (excerpt)
{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "~/.claude/hooks/block-dangerous.sh"
        }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "~/.claude/hooks/format-on-write.sh"
        }
      ]
    }
  ]
}
}

Real example: hook that formats TypeScript with Prettier after each edit.

~/.claude/hooks/format-on-write.sh
#!/usr/bin/env bash
# Receive the tool context as JSON on stdin
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')

# Only act on TS/TSX files
case "$file_path" in
*.ts|*.tsx)
  npx prettier --write "$file_path" 2>/dev/null
  ;;
esac

exit 0

Available events:

• PreToolUse: runs before each tool call. You can block (exit 2 = reject).
• PostToolUse: runs after. Useful for formatting, logging, metrics.
• UserPromptSubmit: runs when the user sends a message.
• SessionStart / SessionEnd: session start and end.
• Stop / SubagentStop: when the main agent or a sub-agent finishes.
• PreCompact: before compacting the context.
• Notification: when Claude Code sends an OS notification.

The "do it by hand in Codex" equivalent is a shell wrapper that runs codex exec with a prompt that includes "after each edit, run prettier". It works but loses precision — the Claude Code hook runs at a specific point in the lifecycle, not depending on the model remembering the instruction.

Common troubleshooting

• "Permission denied" when running a Bash command. Claude Code has an allowlist per tool. Fix: add the pattern to the permissions.allow array in settings.json, or set defaultMode: "bypassPermissions" if you want to skip confirmation.
• "Model not found". Model names change between releases. Check with claude doctor and use the short alias (claude-sonnet-5, claude-opus-4-8) instead of the long ID.
• MCP server not loading. Claude Code reads .mcp.json from the project. If it does not start, run claude with --debug to see the server spawn error.
• Unexpected costs with thinking models. If you enable extended thinking on Opus 4.8, thinking tokens are billed as input. To keep costs low, use Sonnet 5 with thinking only on long tasks.
• Codex and Claude Code running in parallel duplicate context. If you have both installed and both read your repo, they do not break each other, but you are paying for double inference. Pick one as default and use the other only for specific tasks.
• Your AGENTS.md is not being read. Claude Code does not read AGENTS.md by default — it reads CLAUDE.md. Rename or symlink: ln -s AGENTS.md CLAUDE.md.

Closing

Codex CLI is still a solid coding agent, and migrating is not mandatory. The real decision is which one gives you a better time-to-result ratio for your workflow. If your flow depends more on custom slash commands, reusable agents, and lifecycle hooks, Claude Code wins. If you depend on features specific to the OpenAI ecosystem (Assistants API, GPT Store, fine-tunes), stay with Codex CLI.

Most developers who migrate end up using both in parallel — Codex for code review or one-shot generation in projects where it is already tuned, Claude Code as the main day-to-day agent. That is a valid configuration and both support it.

Official docs: Codex CLI and Claude Code.