migrate-to-codex

What problem does it solve?

Migrate an existing Claude/agent configuration into Codex project/global conventions without losing important instruction, skill, agent, hook, or MCP setup—while clearly marking parts that require manual review.

Core Features & Use Cases

• Scans instruction files and configuration roots: Detects supported instruction sources (e.g., AGENTS.md/CLAUDE.md) and associated Claude Code artifacts.
• Converts skills, commands, and supported resources: Rewrites or symlinks instruction content, converts Claude skills/commands into Codex .agents/skills/SKILL.md artifacts, and copies required SKILL entry points.
• Migrates MCP/server and Codex config: Generates .codex/config.toml from Claude MCP/settings (including enabled/disabled server mapping).
• Migrates subagents to Codex custom agents: Converts .claude/agents into .codex/agents/*.toml with preserved intent and manual-review caveats.
• Plans, validates, and reports: Supports scan-only, plan, dry-run, doctor/readiness reporting, and target validation with collision/orphan reporting.

Quick Start

Run migrate-to-codex with your source root and Codex target root, selecting the components you want to migrate and using plan and dry-run first to review the staged changes.