nodeops-app/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:

| Area | Claude Code source | Codex target | |---|---|---| | Instructions | CLAUDE.md, nested CLAUDE.md files | AGENTS.md, AGENTS.override.md, project_doc_fallback_filenames | | Custom commands | .claude/commands/*.md, plugin commands/ | Codex skills, AGENTS.md command recipes, or prompts | | Subagents | .claude/agents/*.md, plugin agents/, agent setting | Codex custom agents/subagents or skills | | User settings | ~/.claude/settings.json, ~/.claude.json | ~/.codex/config.toml, ~/.codex/hooks.json | | Project settings | .claude/settings.json | .codex/config.toml, .codex/hooks.json | | Local settings | .claude/settings.local.json | project-local .codex/config.toml if intentionally shared, otherwise user config | | Permissions | permissions.allow/ask/deny, permission mode, --allowedTools, --disallowedTools | approval_policy, sandbox_mode, [permissions], rules/*.rules, hooks | | Output style | outputStyle, .claude/output-styles/, plugin output-styles/ | personality, model_verbosity, AGENTS.md, skills, or no direct equivalent | | Project MCP | .mcp.json | .codex/config.toml [mcp_servers.<name>] tables, or plugin .mcp.json | | Claude CLI MCP | claude mcp list/get, ~/.claude.json, .mcp.json | codex mcp add, ~/.codex/config.toml | | Hooks | hooks objects in Claude settings or plugin hooks/hooks.json | Codex hooks in .codex/hooks.json, ~/.codex/hooks.json, inline [hooks], or plugin hooks | | Plugins | .claude-plugin/plugin.json, marketplaces, installed plugin list | Codex plugin with .codex-plugin/plugin.json, skills/, .mcp.json, hooks/hooks.json | | Team policy | managed settings, marketplace settings, allowed/denied MCP servers | Codex system config, requirements.toml, managed plugins/config | | Sessions | ~/.claude/projects/ JSONL transcripts | ~/.codex/sessions/ via handoff, not raw copy |

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:

| Claude command/workflow | Codex target | |---|---| | /init | /init or manually create AGENTS.md | | /mcp | /mcp, codex mcp, config.toml | | /agents | /agent, Codex subagents/custom agents | | /permissions | /permissions, approval_policy, sandbox config, rules | | /hooks | Codex hooks files and /debug-config | | /background, /tasks | Codex /ps, /stop, subagents, app/remote workflows | | custom /deploy style commands | Codex skill, plugin skill, or repo script documented in AGENTS.md |

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:

| Claude agent feature | Codex handling | |---|---| | Prompt/instructions | direct to Codex custom agent or skill | | Model choice | direct if supported in Codex config, otherwise note | | Tool restrictions | partial; use sandbox, approvals, rules, instructions | | Hook/MCP/permissionMode frontmatter | partial/manual; verify Codex support before copying | | Main-thread agent setting | manual; use profile/instructions or start with explicit prompt |

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

| Claude behavior | Codex target | |---|---| | permissions.deny for reads/edits | [permissions.<name>.filesystem] deny entries, protected paths, AGENTS.md warnings | | permissions.allow for safe Bash prefixes | Codex rules/*.rules prefix_rule(... decision = "allow") | | permissions.ask | prefix_rule(... decision = "prompt") or approval_policy = "on-request" | | bypassPermissions | avoid by default; only map to sandbox_mode = "danger-full-access" with explicit user approval | | acceptEdits | workspace-write plus appropriate approval policy | | dontAsk / auto mode | approval_policy = "never" only after confirming sandbox boundaries | | --add-dir | --add-dir, writable roots, or scoped project config | | blocked tool categories | sandbox mode, rules, hooks, MCP server enablement, and instructions |

• 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:

| Claude hook | Codex handling | |---|---| | PreToolUse on Bash | PreToolUse matcher Bash | | PreToolUse on Edit/Write | PreToolUse matcher Edit|Write or apply_patch | | PreToolUse on MCP tools | matcher mcp__server__tool or mcp__server__.* | | PostToolUse | PostToolUse where supported | | PermissionRequest | PermissionRequest where approval policy triggers it | | UserPromptSubmit | UserPromptSubmit; matcher is ignored in Codex | | SessionStart | SessionStart with matcher startup|resume|clear | | Stop | Stop; matcher is ignored in Codex |

• 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:

| Claude plugin component | Codex target | |---|---| | skills/<name>/SKILL.md | Codex skills/<name>/SKILL.md | | commands/*.md | Convert to Codex skills or AGENTS.md commands guidance | | agents/*.md | Convert to Codex subagents if available, otherwise skills or AGENTS.md | | hooks/hooks.json | Codex plugin hooks/hooks.json, after hook compatibility review | | .mcp.json | Codex plugin .mcp.json or user/project [mcp_servers] | | bin/ scripts | Keep as plugin assets/scripts if Codex plugin packaging supports the needed runtime | | settings.json, themes, output styles, monitors, LSP | Usually not direct; flag for manual redesign |

• 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:

| Claude Code feature | Codex status | Action | |---|---|---| | Claude Desktop MCP connectors | out of scope by default | Ignore unless explicitly requested | | CLAUDE.md | direct concept, different filename/discovery | Convert to AGENTS.md | | .claude/commands/*.md | no exact same command store | Convert to Codex skills or recipes | | Claude output styles | no same file format | Convert to personality/verbosity/AGENTS/skill | | Claude themes | no direct migration unless Codex theme supports same fields | Recreate manually | | Claude LSP plugin config | partial/no direct | Prefer MCP or local tooling; flag manual | | Claude monitors/background hooks | partial | Convert to hooks, scripts, /ps, or external supervisor | | Claude Notification, SessionEnd, PreCompact hooks | partial/no direct | Redesign or skip with notes | | Claude agent hooks/prompt hooks/HTTP hooks | partial/no direct | Rewrite as Codex command hooks, MCP, or skills | | Claude managed settings | partial | Map to Codex system config/requirements where possible | | Raw session files | not portable contract | Use continues or handoff docs |

Common Mistakes

| Mistake | Fix | |---|---| | Migrating Claude Desktop MCP servers by accident | Only use Claude Code CLI sources unless Desktop migration is requested | | Copying hook JSON verbatim | Check event, matcher, input, output, path variables, and fail-open behavior | | Hardcoding MCP secrets in TOML | Use env forwarding or placeholders; ask user to set env vars locally | | Treating plugins as only skills | Inventory hooks, MCP servers, agents, commands, bin scripts, and settings separately | | Raw-copying session files | Use a handoff tool or generated handoff prompt; session stores are implementation details | | Assuming hooks fully enforce policy | Treat hooks as guardrails; keep critical controls in sandbox, approvals, MCP scopes, and instructions too | | Ignoring permission modes | Map policy intent to Codex approvals, sandbox, rules, and permissions before using Codex | | Dropping output styles | Preserve role/tone/process instructions in AGENTS.md, personality, verbosity, or skills | | Migrating team policy as user config | Use Codex system config or requirements.toml for managed constraints |

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