# How to migrate from Claude Code to Codex in 2026: a step-by-step guide > Codex can import supported Claude Code setup. Check instructions, skills, MCP connections, hooks, and workflows against an inventory; manual work depends on your setup. Source: https://ailoot.ai/blog/en/migrate-claude-code-to-codex/ Canonical: https://ailoot.ai/blog/en/migrate-claude-code-to-codex/ Language: en Publisher: Ailoot (https://ailoot.ai/) Translation: guide-174 Revision: sha256-429b75731f4ffc3cc256efd3e4e130a2501bc9be4af69bb5c395dd6855154536
Key takeaways On June 2, 2026, OpenAI added the "Import other agent setup" feature to Codex. It scans ~/.claude, retrieves skills, the MCP config, instructions, and up to 30 days of session history, and converts CLAUDE.md into AGENTS.md. The amount transferred depends on your inventory and which features the importer supports; compare the scan result with your own list of required settings. What does not transfer: hooks with triggers that have no equivalent in Codex, MCP tokens, and slash commands in the `/name` format. In this guide, I explain what the Migration tool retrieves, what you need to finish manually, and when a full switch makes sense at all.
[Ailoot documentation: API, keys, and setup](https://ailoot.ai/docs/). ## Why is the Codex Migration tool needed at all?
Key takeaways Before June 2, 2026, switching from Claude Code to Codex was a day-long manual project: rename CLAUDE.md to AGENTS.md, rewrite paths for skills, reconnect MCP servers, and restore subagents from memory. The Migration tool does this in one scan: open the Codex App, click "Import other agent setup," and get an inventory of your `~/.claude` folder and a migration plan.
OpenAI added the feature to Codex in early June 2026. The [official changelog](https://developers.openai.com/codex/changelog) puts it briefly:

Added Migrate to Codex flows for importing supported settings from Claude Code and Claude Cowork, including during onboarding.

— OpenAI Codex Changelog, https://developers.openai.com/codex/changelog
In other words: when you first launch the Codex App, or from the settings of a client that's already running, a wizard starts that reads another agent's local configs. Claude Code and Claude Cowork are currently supported. Why OpenAI is doing this is clear. After Sites launched and the Codex App was updated in May–June 2026, Codex gained everything Claude Code previously had over OpenAI: a terminal, plugins, long sessions, and orchestration. Migration removes the last barrier for teams that have already integrated Claude Code into their stack: "supported settings can be imported, then checked against the original inventory." Why you might need it is less straightforward. I compared them head-to-head in the [Codex vs. Claude Code guide](https://ailoot.ai/blog/en/codex-vs-claude-code-choice/): Claude is still ahead on long architectural discussions and Plan Mode, while Codex is faster on autonomous tasks and parallel PRs. If you've decided to switch completely, read on. If you're considering a combination, the [collaboration patterns](https://ailoot.ai/blog/en/claude-code-codex-together/) may be more relevant. ## What does the Migration tool transfer automatically?
Key takeaways At a high level, the scanner retrieves five groups: instructions (CLAUDE.md → AGENTS.md), user skills, MCP server configuration, hooks with deterministic logic, and up to 30 days of session history. There is no measured transfer percentage or completion time established here. Record the number of required items in each group, then mark each as imported and verified, needing manual review, or unsupported. Estimate the remaining work from that inventory.
I'll go through the groups and explain exactly what happens to each part of `~/.claude`. **1. Instructions and context.** `CLAUDE.md` files—the global one in `~/.claude/` and project files in repositories—are converted to the `AGENTS.md` format. The global file ends up at `~/.codex/AGENTS.md`; project files remain in the repository root and child folders. The AGENTS.md format is essentially the same kind of Markdown file with rules; the differences are mostly cosmetic—section names and a couple of specific directives. I explained [what AGENTS.md is](https://ailoot.ai/blog/en/agents-md-guide-template/) and why Codex needs it. **2. Skills.** The `~/.claude/skills/` folder is scanned in its entirety; each skill is adapted to the Codex structure and placed in `$HOME/.agents/skills`. Project skills from `.claude/skills/` in a repository are moved to `.agents/skills`. The `SKILL.md` format with frontmatter is transferred almost as is. If a skill uses Claude-specific triggers, it is flagged for review. **3. MCP servers.** The `.mcp.json` config (both global and project-level) is imported into the Codex format. Server names, launch commands, and paths are preserved. What does not transfer: tokens and environment variables. For security reasons, Codex will ask you for API keys and passwords again so they are not exposed during migration. This is a one-time task: open the MCP section in the Codex App and enter the tokens you already have in your password manager. **4. Hooks.** This is the complicated group. Hooks with deterministic logic (blocking `rm -rf`, alerting on credential-shaped paths, recording evidence) transfer in full. Hooks with triggers that have no equivalent in Codex (for example, specific Claude Code lifecycle events) are marked for "manual review" and are not activated automatically. I explained in detail [how hooks work in Claude Code](https://ailoot.ai/blog/en/claude-code-hooks/), as a reference point—Codex has fewer types. **5. Session history.** Up to the last 30 days of Claude Code activity is imported as a reference. This does not mean "continue exactly where you left off," but your past conversations will be visible in Codex so you can quickly recall project context without explaining everything again. The Migration tool does not distinguish between active files and experimental artifacts—it transfers everything. After the migration, it's useful to manually clean up anything you haven't used in the last six months. ## What does NOT transfer, and why?
Key takeaways There are five groups that are either missing from Codex or work in a fundamentally different way. The Migration tool will flag them but will not convert them. They are MCP tokens and environment variables, slash commands in the `/name` format, Claude Code-specific lifecycle hooks, team workflows built on subagents, and large instructions tailored to the CLAUDE.md format.
I'll go through each group from the perspective of "what to do after migration." **MCP tokens and API keys.** This is the most predictable part. After scanning, Codex will show you a list of all MCP servers it found in Claude. It will ask for keys and tokens for each one. It's easiest to have your password manager handy and go through all the servers in one sitting. After that, MCP works identically in Codex and Claude Code. Check the command and connection parameters for the MCP server you've chosen against its documentation. **Slash commands `/name`.** In Claude Code, you're used to calling a skill with `/skill-name`. In Codex, the canonical invocation is different: `$skill-name`. Treating `/name` commands as proof that skills have loaded is a common migration mistake. After the migration, test a few key skills with `$skill-name` in Codex. If they work, the migration really succeeded. Don't trust the "skills migrated" checkbox in the wizard—verify by invoking them. **Hooks without a Codex equivalent.** If you had a hook for specific Claude Code events—for example, on `pre-tool-use` for a particular combination of tools—that trigger may not exist in Codex. The Migration tool will flag them and leave them inactive. You'll have to decide whether to rewrite them for a Codex equivalent, drop them, or keep them in Claude Code (if you're running it in parallel). A good rule: transfer only deterministic hooks; everything else is a reason not to duplicate the ladder in the new tool. **Team workflows built on subagents.** I explained [what subagents are in Claude Code](https://ailoot.ai/blog/en/claude-code-subagents/) and [how to use nested subagents](https://ailoot.ai/blog/en/claude-code-nested-subagents/). In Codex, subagents are organized through profiles and roles (see below). If you had a complex pipeline with several subagents in a chain in Claude, you'll have to rewrite it around the Codex profile concept. The Migration tool marks such setups as "requires architectural rework". **Large, Claude-specific CLAUDE.md files.** If a file has grown to 2,000–3,000 lines with sections for each project, Codex may accept it, but that's a bad pattern. AGENTS.md is designed to be compact and distributed: global rules in `~/.codex/AGENTS.md`, project-specific rules in the repository root, and narrow overrides in child folders. After migration, don't leave CLAUDE.md as a "giant instruction file"; split it across levels. I explained [how to configure CLAUDE.md correctly](https://ailoot.ai/blog/en/claude-memory-claude-md-auto-memory/); the same approach carries over to AGENTS.md. ## Step by step: 4 actions in the Codex App
Key takeaways The migration and verification time depends on the size of `~/.claude` and the amount of Claude-specific configuration. Download the latest Codex App, open Settings, choose "Import other agent setup," wait for the scan, and confirm the import. Then test skills by invoking `$skill-name`, enter MCP tokens, and check hooks that were not activated.
Here's the specific checklist. 1. ### Step 1: Update the Codex App to 26.608 or later The Migration tool appeared in version 26.608 (released June 9, 2026). On macOS, open the Codex App and check for updates. Do the same on Windows. If you run Codex CLI, make sure it's compatible with the current App. Without the latest version, "Import other agent setup" will not appear in Settings. 2. ### Step 2: Start the import from Settings In the Codex App, open Settings and find "Import other agent setup." If you've just installed the Codex App, the wizard will offer migration during onboarding. Once started, the wizard scans the filesystem: `~/.claude/` and repositories containing `CLAUDE.md` or `.claude/`. Scanning takes from 30 seconds to several minutes, depending on the number of files. 3. ### Step 3: Confirm the migration plan After scanning, Codex will show an inventory: how many skills were found, how many MCP servers, how many `CLAUDE.md` files were found, which hooks qualify for migration, and how many days of session history are available. You can uncheck any group you don't want to transfer. By default, everything Codex considers safe to import is selected. 4. ### Step 4: Wait for completion and enter tokens The import takes 1–5 minutes. When it finishes, Codex will open a follow-up window: "here's what I couldn't transfer automatically; check it manually." Usually, this is a list of MCP servers that need tokens. Open your password manager and enter the keys in the Codex form. After that, the main part of the migration is complete. Next, verify the result. Open a project you usually worked on in Claude Code and check: - `cat ~/.codex/AGENTS.md` — are your global rules there? - Run any skill: `$skill-name`. It should load. - Open `.mcp.json` in the project and check that the required servers are running. - Start a conversation that reflects how you typically work. Codex will show which imported hooks it cannot use; these are specific inventory items you need to handle manually; no fixed remainder is established. ## Hooks and subagents: Codex equivalents and what to rewrite
Key takeaways Codex hooks are less mature than Claude Code hooks in terms of trigger types, but they are sufficient for basic security tasks. Profiles and roles replace subagents. If you had a complex subagent pipeline, it cannot be transferred one-to-one; you need to rethink it using profiles. This may account for substantial manual work, depending on your workflow inventory.
**Hooks.** In Claude Code, you can attach a shell command to each lifecycle event (pre-tool-use, post-tool-use, on-error, on-context-load, and so on). Codex has a smaller set of events: it can check before execution, record evidence, and block dangerous commands. If you had a `pre-tool-use` hook that filtered for a specific combination, in Codex you'll have to wrap that in a general pre-execution check or drop it. I explained the [architecture of Claude Code hooks](https://ailoot.ai/blog/en/claude-code-hooks/) in detail; if you used them extensively, list each trigger and required effect, identify a supported equivalent, and verify it before enabling it. **Subagents.** In Claude Code, a subagent is a separate context with its own system prompt, launched via a `/command` or from the main conversation. Codex has a similar concept in profiles: you can define a profile with a specific set of skills, permissions, and approval policy. Profiles solve roughly the same problem—isolating context for a particular class of tasks—but through settings rather than an explicit agent invocation. What this means in practice: - If you had a "security-reviewer" subagent with its own prompt, create a `security-review` profile in Codex with the required permissions and higher reasoning effort. - If you had a "feature-developer" subagent, that's simply a working profile by default; nothing special is needed. - If you used [nested subagents](https://ailoot.ai/blog/en/claude-code-nested-subagents/), that won't work one-to-one in Codex; rethink it through a chain of profiles or explicit skills. The Migration tool will try to create profiles using your subagent names and flag which triggers did not transfer. The work required depends on the number of roles, triggers, permissions, and dependencies; test each required pipeline before considering it migrated. ## When to migrate completely and when to keep both tools
Key takeaways A full switch to Codex makes sense when your stack consists of autonomous PRs, long parallel tasks, and deep GitHub integration. A combination of both tools is stronger when your work mixes architectural and execution tasks. In my experience, entrepreneurs who vibe-code tend to benefit more from a combination than a full switch.
A simple decision filter: **A full switch to Codex** makes sense if: - You mainly do autonomous PRs and parallel tasks. - Your GitHub workflow is deeply integrated, and Codex Cloud Agent handles 80% of the work. - You don't spend much time on architectural discussions and Plan Mode. - You want to pay for one tool rather than two. **Keep Claude Code + Codex together** if: - You regularly use Plan Mode for long architectural decisions. - You need parallel work: Codex runs in the cloud on one task while Claude Code holds the context for another. - You do a lot of one-off hacks and micro-projects where Plan Mode is excessive. - You have a complex subagent pipeline that cannot be rewritten in one evening. I personally use both: Claude Code holds the long conversation, while Codex runs on "fix N bugs in parallel" or "review a PR." I explained more about how this works in the [guide to working with Claude Code and Codex together](https://ailoot.ai/blog/en/claude-code-codex-together/). The main thing I'd say about migration is this: the Migration tool removes the technical barrier to switching, but it doesn't answer whether you need to switch in the first place. First decide what kind of work you do. Then choose the tool.
### Sources - [Codex Changelog (developers.openai.com)](https://developers.openai.com/codex/changelog) — official release notes, including the entry about Migrate to Codex flows. - [Codex vs. Claude Code 2026 (Ailoot)](https://ailoot.ai/blog/en/codex-vs-claude-code-choice/) — a head-to-head comparison of the two tools before deciding whether to migrate. - [Claude Code and Codex Together (Ailoot)](https://ailoot.ai/blog/en/claude-code-codex-together/) — collaboration patterns if you're unsure about switching completely. - [Hooks in Claude Code (Ailoot)](https://ailoot.ai/blog/en/claude-code-hooks/) — how hooks work in Claude, to help you understand what to transfer.
If you need access to neural networks through Ailoot, take a look at [Ailoot](https://ailoot.ai/). ## Questions about How to migrate from Claude Code to Codex in 2026: a step-by-step guide ### How do I know whether the import actually worked? Compare the wizard’s inventory with your own list of instructions, skills, MCP servers, hooks, and workflows. Load important skills, check instruction paths, reconnect credentials where needed, and test each relevant workflow; an import checkbox alone is not proof. ### How much manual work should I expect after migration? It depends on your inventory and Claude-specific behavior. Record which items imported, need review, or remain unsupported, then estimate the work from that list rather than assuming a fixed percentage or half-hour completion time. ## Ailoot · The company and its project portfolio Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control. The company and its project portfolio: millions of customers; monthly sales in the billions. Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.