Claude Code to Codex

Migrate the user's Claude Code CLI setup into Codex CLI without silently dropping automation. Treat hooks, CLI MCP servers, plugins, and session history as first-class migration targets, not afterthoughts.

Ground Rules

• Preserve behavior first, then improve naming or structure.
• Separate Claude Code CLI configuration from Claude Desktop configuration. Do not read or migrate Claude Desktop MCP servers unless the user explicitly requests it.
• Do not copy secrets into chat, commits, or generated files. Inventory environment variable names only; ask the user to re-enter secret values in the target tool when needed.
• Prefer project-scoped Codex config for team-shared behavior and user-scoped Codex config for personal behavior.
• Verify current CLI syntax with claude --help, claude mcp --help, claude plugin --help, codex --help, codex mcp --help, and current official docs when exact flags matter.
• Keep original Claude files intact until Codex behavior has been verified. Prefer additive .codex/ files over destructive rewrites.

Inventory

Inspect these Claude Code CLI sources if they exist:

Report a short inventory before editing:

Claude Code migration inventory:
- Instructions: found/not found
- Hooks: count by event and source
- Claude Code CLI MCP servers: count by scope; Desktop imports excluded
- Plugins: installed/local/marketplace candidates
- Commands/subagents/output styles: count and recommended target
- Permissions/team policy: explicit rules and high-risk gaps
- Sessions: recent Claude sessions found; recommended handoff method
- Secrets: env var names only, values not read

Migration Workflow

1. Create or update AGENTS.md from CLAUDE.md.

   • Preserve concrete repo rules, build/test commands, permissions, and style guidance.
   • Remove Claude-only tool names or translate them to Codex equivalents.
   • If both files must coexist, keep shared human-readable policy aligned and put agent-specific details in clearly labeled sections.
   • Use Codex project discovery deliberately: global ~/.codex/AGENTS.md for personal defaults, repo AGENTS.md for shared rules, and AGENTS.override.md only for intentional temporary overrides.

2. Migrate custom slash commands and command recipes.

   • Inventory .claude/commands/ and plugin commands/.
   • Convert repeatable procedural commands into Codex skills when they have conditional steps, references, or scripts.
   • Convert short command snippets into AGENTS.md recipes if they are project-specific and not worth a standalone skill.
   • Preserve arguments explicitly. Claude command files often rely on text after the command name; Codex skills should say how to pass user-supplied arguments.
   • Flag interactive Claude built-ins with no direct Codex equivalent. Map workflow intent instead:

3. Migrate subagents and agent defaults.
   • Inventory .claude/agents/, plugin agents/, and the Claude agent setting that runs the main thread as a named subagent.
   • Convert agents that describe a reusable workflow into Codex skills.
   • Convert agents that need independent context, parallel execution, or a different model/instruction profile into Codex custom agents/subagents.
   • Preserve tool restrictions as sandbox/approval/rules guidance when Codex custom-agent tool scoping cannot express the same policy.
   • Remember that Codex only spawns subagents when explicitly asked. Add AGENTS.md guidance if the old Claude workflow expected automatic delegation.
   • Document whether the agent is direct, partial, or manual redesign:

4. Migrate permissions, approvals, sandbox, and rules.
   • Treat this as security-sensitive. Do not loosen behavior silently.
   • Map intent rather than syntax:

• Prefer Codex approval_policy = "untrusted" or "on-request" and sandbox_mode = "workspace-write" as conservative defaults.
• Use Codex rules for shell escalation prefixes. Rules are exact-prefix based, can be allow, prompt, or forbidden, and load from rules/ under active config layers.
• Use hooks only for dynamic checks that rules cannot express.
• Preserve managed policy intent with system config or requirements.toml where available.

5. Migrate general settings, environment, and UX preferences.

   • Map Claude env to shell environment, Codex config, MCP env, or env_vars forwarding. Never hardcode secrets.
   • Map model defaults to Codex model, model_reasoning_effort, model_verbosity, service_tier, and profiles when appropriate.
   • Map file opener/editor preferences to Codex file_opener.
   • Map transcript retention to Codex history settings if the user has privacy requirements.
   • Map status line/title preferences to Codex /statusline, /title, or config fields when available.
   • Flag Claude-specific settings with no Codex equivalent instead of pretending they migrated.

6. Migrate output styles, rules, and memory-like context.

   • Claude output styles change the system prompt. Codex does not use the same output-style format.
   • Convert output styles into one of:
     • AGENTS.md communication preferences for repo-wide behavior.
     • Codex personality / model_verbosity when the style is mostly tone or brevity.
     • A Codex skill when the style is actually a workflow.
     • A plugin skill if it must be distributed.
   • Keep coding-safety guidance that Claude output styles inherited from keep-coding-instructions: true; do not drop it during conversion.
   • For Claude memory/convention files, put durable project behavior in AGENTS.md and personal reusable behavior in global Codex guidance.

7. Migrate Claude Code CLI MCP servers.

   • Use claude mcp list and claude mcp get <name> when possible.
   • Include project .mcp.json and Claude Code user/project/local scopes.
   • Exclude servers imported only from Claude Desktop unless the user asks for Desktop migration.
   • Convert stdio servers to Codex:

[mcp_servers.server-name]
command = "node-or-binary"
args = ["arg1", "arg2"]
env = { TOKEN_ENV_VAR = "value-or-placeholder" }
# env_vars = ["TOKEN_ENV_VAR"]  # forward from shell instead of hardcoding
# cwd = "/absolute/or/project/path"

• Prefer codex mcp add <server-name> --env VAR=VALUE -- <command> for simple stdio servers.
• For HTTP MCP servers, configure the transport according to current Codex MCP docs and run codex mcp login <server-name> when OAuth is required.
• After migration, verify in Codex with /mcp in the TUI or codex mcp --help/available subcommands.

8. Migrate hooks with extra care.
   • Enable Codex hooks:

[features]
codex_hooks = true

• Codex looks for hooks next to active config layers as hooks.json or inline [hooks] tables. Common locations are ~/.codex/hooks.json, ~/.codex/config.toml, <repo>/.codex/hooks.json, and <repo>/.codex/config.toml.
• Map direct equivalents first:

• Flag non-equivalent or partial migrations:
  • Claude Notification, SubagentStop, SessionEnd, PreCompact, Setup, UserPromptExpansion, prompt hooks, agent hooks, HTTP hooks, and mcp_tool hooks may need redesign instead of a direct copy.
  • Codex PreToolUse is a guardrail, not a complete enforcement boundary. It can intercept Bash, apply_patch file edits, and MCP tool calls; it does not cover every possible tool path.
  • Claude hooks that return additionalContext, updatedInput, allow/ask decisions, or async results may fail open or need rewriting for Codex-supported output fields.
• Replace CLAUDE_PROJECT_DIR with a Codex-stable path. For repo hooks, prefer resolving from git root:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

• Test each migrated hook by triggering the matching event in Codex and confirming whether it blocks, warns, or adds context as expected.

9. Migrate plugins.
   • Inventory Claude plugins with claude plugin list --json when available, plugin marketplace settings, local --plugin-dir folders, and plugin roots that contain .claude-plugin/plugin.json.
   • Classify each Claude plugin component:

• Codex plugins use .codex-plugin/plugin.json. Keep skills/, .mcp.json, hooks/, assets/, and app files at the plugin root, not inside .codex-plugin/.
• If the user only needs local reusable workflows, create standalone Codex skills first. Package as a Codex plugin when they need installable distribution.
• Track marketplace migration separately from plugin conversion. A Claude marketplace entry does not automatically become a Codex plugin source.
• For every plugin, produce a component inventory:

Plugin: <name>
- skills: direct/partial/manual
- commands: converted to skills/AGENTS/manual
- agents: converted to subagents/skills/manual
- hooks: direct/partial/manual, with event notes
- MCP: user/project/plugin scope target
- settings/output styles/monitors/LSP/themes: direct/partial/no equivalent

10. Migrate sessions with handoff, not raw transcript copying.

• Back up or export before handoff if the session is important:

continues inspect <session-id> --preset full --write-md handoff.md
continues dump claude ./session-backup/claude --preset full

• Prefer continues when available:

npx continues
continues list --source claude --json
continues resume <session-id> --in codex --preset standard
continues inspect <session-id> --preset full --write-md handoff.md
continues resume <session-id> --in codex --debug-prompt

• Use bunx continues if the user prefers Bun, but verify the package works in their environment. The documented package command may be npx continues.
• Explain that continues reads Claude Code sessions from ~/.claude/projects/, Codex sessions from ~/.codex/sessions/, and creates a structured handoff prompt. It should not mutate original session files.
• Also document native Codex resume for future work: codex resume, codex resume --last, and codex resume <SESSION_ID>.
• Choose preset by risk:
  • minimal: quick context transfer
  • standard: default
  • verbose: complex task with relevant tool output
  • full: audit/debug migration where token cost is acceptable
• If continues is unavailable, export or summarize the Claude transcript into a handoff document with: objective, decisions, modified files, commands run, failures, pending tasks, and exact current workspace state.

11. Validate.

• Run codex --version and codex mcp//mcp checks.
• Start Codex in the migrated repo and ask it to summarize loaded instructions.
• Trigger migrated hooks intentionally.
• Call each MCP server with a harmless read-only request.
• Open plugin/skill lists in Codex (/plugins, /skills) when relevant.
• Use /status, /debug-config, /permissions, /diff, and /review to verify config, policy, and changes.
• Use continues --debug-prompt or equivalent before launching a cross-tool handoff when the session contains sensitive context.

12. Keep a rollback path.

• Keep .claude/, .mcp.json, and CLAUDE.md until Codex migration is verified.
• Isolate generated .codex/ changes in a separate commit or branch.
• To disable pieces quickly, disable Codex hooks by removing [features].codex_hooks = true, disable MCP servers in config, or start Codex from an untrusted project layer.
• Do not delete Claude sessions. They are the source of truth for handoff retries.

Unsupported and Partial Equivalents

Use this table when users ask for a "complete" migration:

Common Mistakes

Final Report

End each migration with:

Claude Code -> Codex migration result:
- AGENTS.md/instructions: migrated/unchanged/pending
- Hooks: migrated count, skipped count, compatibility notes
- CLI MCP servers: migrated count, Desktop servers excluded
- Plugins: converted to skills/plugins/manual follow-up
- Commands/subagents/output styles: migrated target and gaps
- Permissions/sandbox/rules: conservative mapping and remaining risks
- Managed/team config: migrated target or unsupported notes
- Sessions: handoff command or exported handoff file
- Verification run: commands and outcomes
- Manual actions left: secret setup, OAuth login, plugin install, hook rewrites

References

• Claude Code hooks: https://markdown.new/https://code.claude.com/docs/en/hooks
• Claude Code MCP: https://markdown.new/https://code.claude.com/docs/en/mcp
• Claude Code plugins: https://markdown.new/https://code.claude.com/docs/en/plugins
• Claude Code commands: https://markdown.new/https://code.claude.com/docs/en/commands
• Claude Code permissions: https://markdown.new/https://code.claude.com/docs/en/permissions
• Claude Code subagents: https://markdown.new/https://code.claude.com/docs/en/sub-agents
• Claude Code output styles: https://markdown.new/https://code.claude.com/docs/en/output-styles
• Codex config: https://markdown.new/https://developers.openai.com/codex/config-basic
• Codex advanced config: https://markdown.new/https://developers.openai.com/codex/config-advanced
• Codex rules: https://markdown.new/https://developers.openai.com/codex/rules
• Codex hooks: https://markdown.new/https://developers.openai.com/codex/hooks
• Codex MCP: https://markdown.new/https://developers.openai.com/codex/mcp
• Codex plugins: https://markdown.new/https://developers.openai.com/codex/plugins
• Codex skills: https://markdown.new/https://developers.openai.com/codex/skills
• Codex subagents: https://markdown.new/https://developers.openai.com/codex/subagents
• Codex CLI slash commands: https://markdown.new/https://developers.openai.com/codex/cli/slash-commands
• continues: https://github.com/yigitkonur/cli-continues