Migrate to Codex

Autonomy

Keep going until the selected migration is completely done: run the migrator, inspect the report, fix migrated Codex instructions/skills/agents/MCP config, and re-run checks without stopping to ask for confirmation of the next step. If the user has selected a target, do not ask before creating, editing, replacing, or deleting generated Codex artifacts in that target (AGENTS.md, .codex/, .agents/, or ~/.codex/). Preserve unrelated existing Codex config entries in .codex/config.toml or ~/.codex/config.toml, such as notify, projects, marketplaces, or unrelated MCP servers; do not ask about them unless they fail validation or directly conflict with the migration. Do not edit source Claude Code files (.claude/, ~/.claude/, .mcp.json, or .claude.json), unrelated project code, secrets, or another repository.

Migration Order

Run the migration in this order for each selected global or project source:

1. Start by using Codex's built-in TODO/task list tool. Do not create MIGRATION_TODOS.md or any TODO file unless the user explicitly asks. The TODO list input has a plan array whose items each have step and status; use statuses pending, in_progress, and completed. Make the TODOs specific to the selected artifacts. Before finishing, update the TODO list so every finished step is marked completed and no step remains in_progress. Use literal source → Codex target labels, for example:

   • Inspect .claude/commands → Codex skills/prompts
   • Inspect .claude/agents → .codex/agents
   • Inspect .mcp.json → .codex/config.toml MCP servers
   • Inspect .claude/settings.json hooks → .codex/hooks.json
   • Migrate safe selected artifacts → Codex files
   • Validate generated .codex/config.toml
   • Validate generated .codex/agents
   • Report migrated artifacts and manual-review items

2. Read references/differences.md (and refresh Codex docs if its Docs last checked date is old).

3. Scan and inspect before writing:

   • --scan-only lists active and inactive source surfaces.
   • --plan prints staged Codex artifact paths and report rows.
   • --doctor summarizes readiness, manual-review work, and validation risks.

4. Convert surfaces in the same order the CLI uses:

   • instructions: CLAUDE.md / AGENTS.md to AGENTS.md
   • plugins: report Claude plugin trees and marketplaces as manual migration work
   • hooks: rewrite supported Claude hooks into .codex/hooks.json and enable [features].codex_hooks = true
   • skills and commands: write Codex skills under .agents/skills/
   • config: write .codex/config.toml from Claude model/sandbox settings and MCP servers, including personality = "friendly" when config is generated
   • subagents: write Codex custom agents under .codex/agents/

5. Dry-run, then write the selected target. Use --replace only when orphan generated skills or agents should be deleted.

6. Inspect the terminal output and .codex/migrate-to-codex-report.txt after real runs.

7. Review generated artifacts in this order: AGENTS.md, .agents/skills/, .codex/config.toml, .codex/hooks.json, .codex/agents/, then report-only plugin items.

8. Run --validate-target against each target after edits.

9. Re-run checks and --dry-run after edits.

10. Return the final migration report as one markdown table per scope that has rows. The tables cover only the non-native follow-up migration work you performed, such as skills created from slash commands, subagents, MCP servers, hooks, unsupported/local plugin notes, and manual-review caveats. Include programmatic native import rows for config, instructions, skills, or supported plugins only if you personally migrated them in this follow-up run.

…