Claude Code To Codex

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