Claude-to-Codex Migration Bridge

Move a Claude Code project into Codex without giving up Claude

Claude-to-Codex Migration Bridge creates a side-by-side Codex representation of one selected project. It scans project-local Claude instructions, agents, skills, commands, supported hooks, settings, MCP configuration, and Claude-specific harness signals, then generates safe Codex counterparts while leaving CLAUDE.md, .claude/, and .mcp.json untouched.

Persist the model routing

A workflow can move while its Claude model roles remain unresolved. In our repeated unresolved-import tests, those unresolved roles caused substantial recurring usage. Results vary by workflow, account, and model settings.

For supported migrated agents, the bridge resolves the mapping during migration and writes the model and reasoning level into the generated Codex agent file:

• Fable → gpt-5.6-sol with ultra
• Opus → gpt-5.6 with medium
• Sonnet → gpt-5.6-luna with max
• Haiku → gpt-5.6-luna with inherited reasoning

Model and reasoning availability still depends on the buyer's Codex account and the selected model.

What it transfers

• CLAUDE.md instructions → managed AGENTS.md sections
• Claude agents → project-local Codex .toml agents with persistent routing
• Claude skills → explicit-only Codex skills
• Claude commands → explicit-only Codex skills
• Compatible local command hooks → project Codex hook definitions
• Safe stdio and streamable HTTP MCP settings → project Codex configuration
• Claude-only harness, plugin, permission, setting, or runtime gaps → a review report instead of an unsafe guess

One folder, both clients

Claude continues to read CLAUDE.md, .claude/, and .mcp.json. Codex reads the generated AGENTS.md, .agents/, and .codex/ files. The bridge does not switch clients by renaming or deleting either side.

After a Claude-side change, run status to detect added, deleted, or changed sources, then review a new plan and apply it. If a generated Codex file was edited manually, the bridge reports a conflict instead of overwriting it.

Safe by design

• Read-only plan before apply
• Canonical selected-project confinement for every read and write
• External symlink, junction, and path-escape rejection
• Sensitive path-component and secret-literal blocking
• No execution of imported hooks, MCP servers, setup commands, or project code
• Hash checks for generated targets and original backups
• Zero-change repeat apply when the project is unchanged
• Explicit rollback from verified file preimages
• Unsupported MCP environment aliases block the affected plan instead of producing a misleading configuration

Explicit invocation only

Invoke $claude-codex-bridge explicitly. Its full instructions are not loaded implicitly into ordinary Codex work. A slash-command alias depends on the host or marketplace UI and is not guaranteed by the package.

Verified release evidence

• Tested on Python 3.10 and 3.13
• 26 automated cases per interpreter: 25 passed; 1 Windows symlink-creation case was privilege-gated and skipped
• The Windows junction confinement case passed
• Representative fixture: 4 Claude agents, 12 planned Codex outputs, 0 blocking findings
• Second apply: 0 changes and an identical manifest hash
• Status after apply: clean
• Rollback: every original file restored byte-for-byte
• 1,281 generated sentinel files outside the selected test project remained unchanged

The reproducible evidence fixture verifies file generation, hashes, idempotency, rollback, and selected-project confinement. It does not claim universal usage savings, identical Claude/Codex runtime behavior, or model entitlement.

How to use it

1. Download and install the Skill in Codex.
2. Open the Claude project folder you want to bridge.
3. Invoke $claude-codex-bridge explicitly.
4. Review the read-only migration plan and compatibility findings.
5. Authorize apply, run status, and open a new Codex task.
6. Invoke the Skill again after Claude-side changes, or request rollback when needed.

Important limits

Hook event semantics, MCP authentication, project trust, model entitlements, top-level Claude model settings, and Claude/Anthropic SDK harness code may require manual work. Sessions, memories, OAuth state, credentials, approval state, and private runtime data are intentionally excluded. Unknown models and unsupported fields are reported rather than silently guessed or granted.

Generated files and local hash checks do not by themselves prove identical behavior between Claude and Codex.