claude2codex

Universal migration tool from Claude Code to OpenAI Codex CLI.

Scans your Claude Code setup (~/.claude, plugins, MCP servers, skills, commands, agents) and migrates it to Codex CLI (~/.codex, ~/.agents/skills, prompts) with full safety: automatic snapshots, rollback, and transparent loss reporting.

Quick Start

npx claude2codex migrate

This will:

1. Scan your Claude Code setup
2. Show you what will change (plan preview)
3. Ask for confirmation
4. Create a snapshot of your existing ~/.codex/
5. Apply the migration
6. Verify the result
7. Write a loss report

Commands

Command	Description
claude2codex scan	Scan Claude Code setup, output inventory
claude2codex plan	Scan + convert, show what would change (dry-run)
claude2codex migrate	Scan + convert + apply with snapshot
claude2codex rollback	Restore from latest snapshot
claude2codex doctor	Verify current Codex setup health
claude2codex report	Re-print the latest migration report
claude2codex snapshots	List available snapshots
claude2codex dump-fixture	Export anonymized setup for regression testing

Global Options

--claude-home <path> Claude home directory (default: ~/.claude)
--codex-home <path> Codex home directory (default: ~/.codex)
--overwrite Replace existing files/keys
--no-projects Skip project-scope migration
--no-network Skip upstream plugin inspection
--only <types> Only convert specific types (mcp,skill,command,...)
--skip <types> Skip specific types
--yes, -y Skip confirmation prompts
--json Structured JSON output
--verbose, -v Verbose logging

What Gets Migrated

Claude Code	Codex CLI	Notes
CLAUDE.md	AGENTS.md	Content appended with markers
~/.claude/skills/	~/.agents/skills/	Near-1:1 copy
~/.claude/commands/	~/.codex/prompts/	Frontmatter stripped
MCP servers	config.toml [mcp_servers.*]	All transports (stdio/http/sse)
Plugins (with .codex/)	Clone + self-install	Upstream-aware
Plugins (without .codex/)	Unpacked to skills/prompts/mcp	Mechanical
Subagents	Skills + multi_agent=true	Lossy (tools lost)
Hooks	Dropped (except Stop→notify)	Reported as loss
Permissions	sandbox_mode + approval_policy	Coarse mapping

Safety

• Snapshot before every migration -- automatically created at ~/.codex/.claude2codex-backup-<timestamp>/
• Automatic rollback on failure -- if any step fails, the entire migration is reverted
• Non-destructive merge -- existing Codex config is preserved; new items are added alongside
• Idempotent -- re-running migrate is safe; markers prevent duplication
• Secrets never stored -- only env key names appear in IR and config; values use ${VAR} placeholders

Loss Reporting

Items that can't be translated are reported in ~/.claude2codex/reports/<timestamp>.md:

• Action Required: dropped hooks, collapsed permissions, pending secrets
• Informational: dropped frontmatter keys, plugin namespace flattening

Contributing

Export your setup as an anonymized fixture for regression testing:

claude2codex dump-fixture --output my-fixture

Then submit the fixture directory as a PR to help cover more edge cases.

License

MIT