# Migrating from Claude Code to Codex: How to Move CLAUDE.md, MCP, Skills, Slash Commands, and Settings

> Complete engineering guide on migrating from Claude Code to OpenAI Codex CLI: porting CLAUDE.md to AGENTS.md, configuring MCP, sandboxing, hooks, and retaining Claude models.

Codex features a single-command importer that automates the migration of most Claude Code settings. The core engineering challenge lies in the operational nuances: certain configuration blocks require manual reassembly, and one component cannot be migrated natively — the Anthropic Claude models themselves.

Migrating the entire configuration suite from Claude Code to Codex takes approximately 20 minutes. Below is an executive breakdown of the migration landscape.

---

## 1. What Can Be Migrated and What Cannot — Quick Verdict

### 1.1. Quick Assessment: Surface Compatibility Matrix

| Question | Solution / Answer |
| :--- | :--- |
| Can most of the configuration be migrated? | **Yes.** 9 out of 12 surfaces migrate or rebuild without friction. |
| What is the fastest path? | Run `codex` → `/import` (Codex 0.140+), then manually refine 3 items. |
| What is migrated automatically? | Memory files, MCP servers, skills, slash commands, custom endpoints. |
| What requires manual refinement? | Permission model, hook event format, subagent wrapper definitions. |
| What is the only real dead end? | Anthropic Claude models. Vanilla Codex only supports OpenAI models natively. |
| What is the workaround for the dead end? | Configure an API gateway as a `model_provider` to continue running Claude in Codex. |

> 📌 **Environment Versions:** This guide was tested on Codex CLI 0.142.5 (July 1, 2026) and Claude Code 2.1.178. If you run an older Codex build, upgrade first: the `/import` command requires version 0.140.0+.

### 1.2. Automated vs Manual Migration Components

**Surfaces that migrate seamlessly:**
- Repository guidelines and personal preferences (content of `CLAUDE.md`).
- **MCP servers** — command binaries and runtime arguments translate directly.
- **Skills** — both tools adhere to the shared Agent Skills specification.
- Slash commands and reusable prompt templates.
- Custom API base URLs and authentication tokens.

**Surfaces that require manual translation or workarounds:**
- Operation-specific permission allowlists (`permissions.allow`) — Codex uses coarse sandbox tiers.
- The `ConfigChange` hook event (Codex features `PreCompact`/`PostCompact`, but no config change listener).
- **Output styles** — the output styling concept does not exist in Codex.
- **Anthropic models** — default Codex builds route exclusively to OpenAI models; Claude requires a proxy gateway.

---

## 2. Full Map: All 12 Claude Code Configurations and Their Codex Equivalents

### 2.1. Comprehensive Configuration Surface Matrix

Both tools solve identical coding automation tasks using distinct serialization paradigms: Claude Code relies on JSON (`settings.json`, `.mcp.json`) and Markdown (`CLAUDE.md`, `.claude/agents/*.md`), while Codex unifies configuration in a single TOML file (`~/.codex/config.toml`) alongside `AGENTS.md`.

| # | Claude Code Surface | Codex CLI Equivalent | Migration Verdict |
| :---: | :--- | :--- | :--- |
| 1 | `CLAUDE.md` (memory) | `AGENTS.md` (or fallback filename) | Migrated directly |
| 2 | `.mcp.json` (JSON) | `[mcp_servers.*]` in `config.toml` | Migrated with reformatting |
| 3 | `.claude/skills/` | Codex skills (`[[skills.config]]`) | Migrated directly |
| 4 | `.claude/commands/` | Slash commands / prompts | Migrated, requires restructuring |
| 5 | `.claude/agents/` (Markdown) | `.codex/agents/*.toml` files | Rebuilt as TOML |
| 6 | `settings.json` (JSON) | `config.toml` + profiles (TOML) | Rebuilt as TOML |
| 7 | `permissions.allow/ask/deny` | `approval_policy` + `sandbox_mode` | Reconceptualized |
| 8 | Hooks (`PreToolUse`, `Stop`, …) | `[[hooks.*]]` in `config.toml` | Rebuilt as TOML |
| 9 | `ConfigChange` hook | No equivalent | No direct equivalent |
| 10 | `ANTHROPIC_BASE_URL` endpoint | `[model_providers.*]` | Migrated directly |
| 11 | `outputStyle` | No equivalent | No direct equivalent |
| 12 | Anthropic Claude models | OpenAI models only by default | Dead end (bypassed via gateway) |

### 2.2. Core Architectural Differences: JSON vs TOML

Rows 9 and 11 are cosmetic: `outputStyle` has negligible operational impact, and `ConfigChange` is only relevant for advanced session-dynamic tooling.

The true operational hurdle is Row 12 (Anthropic models). However, defining a custom proxy in the `[model_providers]` table allows developers to continue leveraging Claude Opus and Sonnet within the Codex execution sandbox.

---

## 3. When to Migrate and When to Stay on Claude Code

### 3.1. Workflows and Criteria for Migrating to Codex

Migrating to Codex is advantageous when workflows prioritize autonomous task execution and strict filesystem isolation:
- **Headless CI/CD Automation:** Executing agent pipelines non-interactively with predictable `read-only` or `workspace-write` sandboxes.
- **Team Standardization:** Committing a unified `config.toml` with preset risk profiles instead of managing scattered `.claude/settings.local.json` overrides.
- **Latest OpenAI Models:** Utilizing `gpt-5.5` and `gpt-5.4` as primary code synthesis engines.

### 3.2. When You Should Remain on Claude Code

Retain Claude Code if your development loop exhibits the following characteristics:
- **Reliance on Specific Hooks:** Your automation depends on `ConfigChange` triggers or `outputStyle` formatting flags.
- **Interactive Conversational Flows:** Your primary usage involves extensive conversational back-and-forth; Claude Code's conversational memory handles dialogue loops better than Codex's batch task-and-review cycle.
- **Granular Allowlist Rules:** If you rely on complex glob patterns covering every terminal command, transitioning to Codex's coarser sandbox levels will require re-evaluating your operational security model.

> 💡 **Stop Rule:** If your primary goal is merely benchmarking Codex models on an existing codebase, do not overhaul your entire configuration. Point Codex to the repository, execute `/import`, and evaluate the results. Deep manual reconfiguration is only required when adopting Codex as your primary driver.

---

## 4. System Requirements Before Starting

### 4.1. CLI Version Checks, Project State, and Permissions

Before modifying configuration files, verify four prerequisites:
1. **Codex CLI version 0.140.0 or higher:** Check your installed binary via `codex --version`.
2. **Untouched Claude Code Project:** Keep the `.claude/` directory and `CLAUDE.md` intact until migration is fully verified.
3. **Valid API Key:** Ensure an active OpenAI API key or a third-party gateway key (e.g. ofox.ai) for Anthropic model routing.
4. **Filesystem Permissions:** Ensure write access to `~/.codex/config.toml` for persistent user configuration.

### 4.2. Migration Path: Step-by-Step Transition Pipeline

The migration follows a structured six-stage transition pipeline:

```mermaid
flowchart LR
    A["Audit CLAUDE.md + settings.json"] --> B["Run codex /import"]
    B --> C["Review conflict report"]
    C --> D["Manually refine permissions + hooks"]
    D --> E["Add model_provider for Claude"]
    E --> F["Test with read-only profile"]
```

---

## 5. Step-by-Step Configuration Migration

### 5.1. Step 1: Run the Automated Importer (/import)

Open your project root and invoke the interactive Codex importer:

```bash
cd my-project
codex
# Inside the Codex interactive session:
/import
```

The `/import` command selectively ports settings, project instructions, and recent conversation contexts. This generates an initial `~/.codex/config.toml`, drafts an `AGENTS.md` file, and displays an itemized report of skipped or conflicting fields.

### 5.2. Step 2: Instructions — Migrate from CLAUDE.md to AGENTS.md

Codex looks for `AGENTS.md` by default. To maintain backwards compatibility or avoid renaming existing files, specify fallback lookup filenames:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]
project_doc_max_bytes = 32768
```

Your system instructions, coding conventions, build commands, and testing guidelines will load into Codex's context window without modification.

### 5.3. Step 3: MCP Servers — Convert from JSON to TOML

Both ecosystems implement the Model Context Protocol. The underlying server binaries remain identical; only the declarative syntax shifts from JSON to TOML.

Original entry in `.mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

Equivalent entry in `~/.codex/config.toml`:

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
```

To provide environment variables, configure them inline: `env = { GITHUB_TOKEN = "..." }`. Both local STDIO processes and remote streaming HTTP/SSE transports are supported.

### 5.4. Step 4: Subagents — Configure in .codex/agents/

Claude Code organizes subagents as Markdown documents in `.claude/agents/`. Codex uses dedicated TOML files stored under `~/.codex/agents/` (user-level) or `.codex/agents/` (project-level):

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews diffs for correctness and style"
developer_instructions = """
Review the diff for correctness and style. Cite file and line for each issue found.
"""
```

Subagents in Codex are enabled by default and are invoked upon explicit request by the user or coordinating agent.

### 5.5. Step 5: Permission Model — Configure Sandbox and Approval

Security architectures differ fundamentally: instead of an operation-specific glob allowlist (`permissions.allow`), Codex relies on filesystem isolation (`sandbox_mode`) and confirmation policies (`approval_policy`).

| Claude Code Pattern | Purpose | Codex Equivalent (`~/.codex/config.toml`) |
| :--- | :--- | :--- |
| `allow: ["Bash(npm run test *)"]` | Unprompted safe execution | `sandbox_mode = "workspace-write"`<br>`approval_policy = "on-request"` |
| `ask: ["Bash(python *)"]` | Require confirmation before execution | `approval_policy = "on-request"` |
| `deny: ["Read(./.env)"]` | Block sensitive out-of-bounds paths | `sandbox_mode = "workspace-write"` |
| `Plan mode` | Non-destructive analytical mode | `sandbox_mode = "read-only"` |
| `--dangerously-skip-permissions` | Full autonomy | `approval_policy = "never"`<br>`sandbox_mode = "danger-full-access"` |

Recommended balanced baseline configuration:

```toml
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

### 5.6. Step 6: Hooks — Port Lifecycle Event Handlers

Codex natively supports lifecycle hooks across key operational events: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact`, and `PostCompact`.

```toml
# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.sh"
```

> ⚠️ **Important Note:** The `ConfigChange` hook is unsupported in Codex. Dynamic automations that react to runtime configuration edits must be shifted to pre-session launch scripts.

---

## 6. Migration Dead End: Claude Models in Codex and How to Keep Them

### 6.1. Custom model_provider Gateway Architecture for Anthropic

Codex is designed around OpenAI models (`gpt-5.5`, `gpt-5.4`) and does not natively expose Anthropic endpoints. To utilize Claude Opus or Sonnet within the Codex harness, declare a custom OpenAI-compatible proxy gateway.

Register the provider in `~/.codex/config.toml`:

```toml
# ~/.codex/config.toml
[model_providers.ofox]
name = "ofox.ai gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"
requires_openai_auth = false
```

### 6.2. Configuring wire_api=responses and Activating Claude Profile

When declaring custom providers, two directives are essential:
1. `wire_api = "responses"`: Support for the legacy `chat` protocol was removed from Codex in February 2026.
2. `requires_openai_auth = false`: Prevents the CLI from expecting standard `sk-` OpenAI token formats.

Create a profile in `~/.codex/claude.config.toml`:

```toml
# ~/.codex/claude.config.toml
model = "anthropic/claude-opus-4.8"
model_provider = "ofox"
```

Execute Codex with the designated profile:

```bash
codex --profile claude
```

---

## 7. Common Migration Mistakes and Solutions

### 7.1. Troubleshooting Matrix and Root Cause Analysis

| Symptom | Root Cause | Engineering Solution |
| :--- | :--- | :--- |
| Codex ignores `CLAUDE.md` | Defaults to looking for `AGENTS.md` | Rename the file or add `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` |
| Custom provider yields `401 Unauthorized` | Client expects OpenAI tokens with `sk-` prefix | Add `requires_openai_auth = false` in `[model_providers.*]` |
| Startup crash: `chat wire API deprecated` | Legacy `chat` protocol removed | Specify `wire_api = "responses"` |
| Subagents fail to act | Missing TOML definition or missing explicit call | Create `.codex/agents/NAME.toml`; Codex only triggers agents when explicitly called |
| Hooks fail to execute | Invalid event label or broken regex matcher | Verify event syntax and check `matcher` regex in `[[hooks.*]]` |
| Commands previously allowed are blocked | Codex sandbox is coarser than granular rules | Widen `sandbox_mode` or set `approval_policy = "on-request"` |

### 7.2. Project Trust Settings and Configuration Precedence

If `.codex/config.toml` at the project level is ignored, check project trust status. For security reasons, Codex only evaluates project-level configurations within trusted directories, and intentionally forbids local project files from overriding global authentication or model providers.

---

## 8. Team Migration

### 8.1. Centralized config.toml vs Individual .local.json Overrides

In Claude Code, teams routinely balanced two layers: shared `.claude/settings.json` and git-ignored local `.claude/settings.local.json`. Codex simplifies this into a cleaner hierarchy:

| Collaboration Aspect | Claude Code | OpenAI Codex CLI |
| :--- | :--- | :--- |
| Shared Team Configuration | `.claude/settings.json` (committed) | `.codex/config.toml` (committed to repo) |
| Developer Overrides | `.claude/settings.local.json` | Personal profile files in `~/.codex/` |
| Base Project Instructions | `CLAUDE.md` | `AGENTS.md` |
| Risk Tiers | `permission allowlist` | CLI flags: `--profile strict` vs `--profile fast` |

### 8.2. Shared API Gateway and Unified Team Billing

Leveraging a centralized `model_provider` streamlines team finances and key distribution:
- The team repository commits baseline gateway definitions in `.codex/config.toml`.
- Developers supply their credentials via corporate secret managers (`OFOX_API_KEY`).
- The entire engineering team accesses a unified billing endpoint, whether individuals run `openai/gpt-5.5` or `anthropic/claude-opus-4.8`.

---

## 9. Advanced Level: Profiles for CI, Local Work, and Review

### 9.1. Configuring Tiered Security Profiles

Profiles are independent configuration files stored in `~/.codex/` and invoked on demand via `--profile`. This cleanly eliminates the need to rewrite global settings between distinct workflows.

Example configuration for automated CI review:

```toml
# ~/.codex/ci.config.toml
model = "gpt-5.5"
approval_policy = "never"
sandbox_mode = "read-only"
```

### 9.2. Practical Scenarios: Isolated CI Review and Local Development

Executing `codex --profile ci` guarantees read-only repository inspection without risking unintended modifications or network leaks.

Daily active development uses `local.config.toml` with `sandbox_mode = "workspace-write"`, while complex architectural reasoning is delegated to `codex --profile claude`, running Claude Opus without changing baseline developer credentials.

---

## 10. Frequently Asked Questions (FAQ)

### 10.1. Model Compatibility and Configuration Files

> ❓ **Can I use Anthropic Claude models directly in Codex CLI?**  
> Native Codex builds connect exclusively to OpenAI models. However, you can access any Claude model (such as `anthropic/claude-opus-4.8`) by establishing an OpenAI-compatible proxy gateway in `[model_providers]` and referencing it in your profile.

> ❓ **Does Codex CLI read the legacy CLAUDE.md instruction file?**  
> Codex defaults to reading `AGENTS.md`. To retain your existing file without duplication, define `project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"]` in your `~/.codex/config.toml`.

> ❓ **How do I rapidly import an existing Claude Code configuration?**  
> Launch `codex` in the repository root and enter `/import`. The automated importer migrates instructions, MCP definitions, and contextual prompts, while surfacing an itemized checklist of settings requiring manual adjustment.

> ❓ **Are AGENTS.md and CLAUDE.md interchangeable?**  
> Functionally, yes. `AGENTS.md` represents an open cross-tool specification adopted across modern coding agents, whereas `CLAUDE.md` is Anthropic's proprietary format. The underlying instruction syntax is parsed identically.

### 10.2. Technical Specifications of Hooks, MCP, and Subagents

> ❓ **Does Codex CLI support lifecycle hooks like Claude Code?**  
> Yes, hooks are enabled out of the box. Supported lifecycle hooks include `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `PreCompact`, and `PostCompact`. The only Claude Code hook without an equivalent is `ConfigChange`.

> ❓ **Can Claude Code and Codex share the same MCP servers?**  
> Yes. The underlying MCP protocol and binaries are identical. Only the declaration syntax changes from JSON format in `.mcp.json` to structured TOML tables in `config.toml`.

> ❓ **Do I need to rewrite subagent definitions when migrating?**  
> No, prompt instructions are preserved intact. You only need to adjust the enclosing wrapper: copy instructions from Markdown files in `.claude/agents/*.md` into the `developer_instructions` multi-line string within `.codex/agents/*.toml`.