claude-code-to-codex

What this skill does

# Claude Code to Codex

Migrate the user's Claude Code CLI setup into Codex CLI without silently dropping automation. Treat hooks, CLI MCP servers, plugins, and session history as first-class migration targets, not afterthoughts.

## Ground Rules

- Preserve behavior first, then improve naming or structure.
- Separate Claude Code CLI configuration from Claude Desktop configuration. Do not read or migrate Claude Desktop MCP servers unless the user explicitly requests it.
- Do not copy secrets into chat, commits, or generated files. Inventory environment variable names only; ask the user to re-enter secret values in the target tool when needed.
- Prefer project-scoped Codex config for team-shared behavior and user-scoped Codex config for personal behavior.
- Verify current CLI syntax with `claude --help`, `claude mcp --help`, `claude plugin --help`, `codex --help`, `codex mcp --help`, and current official docs when exact flags matter.
- Keep original Claude files intact until Codex behavior has been verified. Prefer additive `.codex/` files over destructive rewrites.

## Inventory

Inspect these Claude Code CLI sources if they exist:

| Area | Claude Code source | Codex target |
|---|---|---|
| Instructions | `CLAUDE.md`, nested `CLAUDE.md` files | `AGENTS.md`, `AGENTS.override.md`, `project_doc_fallback_filenames` |
| Custom commands | `.claude/commands/*.md`, plugin `commands/` | Codex skills, `AGENTS.md` command recipes, or prompts |
| Subagents | `.claude/agents/*.md`, plugin `agents/`, `agent` setting | Codex custom agents/subagents or skills |
| User settings | `~/.claude/settings.json`, `~/.claude.json` | `~/.codex/config.toml`, `~/.codex/hooks.json` |
| Project settings | `.claude/settings.json` | `.codex/config.toml`, `.codex/hooks.json` |
| Local settings | `.claude/settings.local.json` | project-local `.codex/config.toml` if intentionally shared, otherwise user config |
| Permissions | `permissions.allow/ask/deny`, permission mode, `--allowedTools`, `--disallowedTools` | `approval_policy`, `sandbox_mode`, `[permissions]`, `rules/*.rules`, hooks |
| Output style | `outputStyle`, `.claude/output-styles/`, plugin `output-styles/` | `personality`, `model_verbosity`, `AGENTS.md`, skills, or no direct equivalent |
| Project MCP | `.mcp.json` | `.codex/config.toml` `[mcp_servers.<name>]` tables, or plugin `.mcp.json` |
| Claude CLI MCP | `claude mcp list/get`, `~/.claude.json`, `.mcp.json` | `codex mcp add`, `~/.codex/config.toml` |
| Hooks | `hooks` objects in Claude settings or plugin `hooks/hooks.json` | Codex hooks in `.codex/hooks.json`, `~/.codex/hooks.json`, inline `[hooks]`, or plugin hooks |
| Plugins | `.claude-plugin/plugin.json`, marketplaces, installed plugin list | Codex plugin with `.codex-plugin/plugin.json`, `skills/`, `.mcp.json`, `hooks/hooks.json` |
| Team policy | managed settings, marketplace settings, allowed/denied MCP servers | Codex system config, `requirements.toml`, managed plugins/config |
| Sessions | `~/.claude/projects/` JSONL transcripts | `~/.codex/sessions/` via handoff, not raw copy |

Report a short inventory before editing:

```text
Claude Code migration inventory:
- Instructions: found/not found
- Hooks: count by event and source
- Claude Code CLI MCP servers: count by scope; Desktop imports excluded
- Plugins: installed/local/marketplace candidates
- Commands/subagents/output styles: count and recommended target
- Permissions/team policy: explicit rules and high-risk gaps
- Sessions: recent Claude sessions found; recommended handoff method
- Secrets: env var names only, values not read
```

## Migration Workflow

1. Create or update `AGENTS.md` from `CLAUDE.md`.
   - Preserve concrete repo rules, build/test commands, permissions, and style guidance.
   - Remove Claude-only tool names or translate them to Codex equivalents.
   - If both files must coexist, keep shared human-readable policy aligned and put agent-specific details in clearly labeled sections.
   - Use Codex project discovery deliberately: global `~/.codex/AGENTS.md` for personal defaults, repo `AGENTS.md` for shared rules, and `AGENTS.override.md` only for intentional temporary overrides.

2. Migrate custom slash commands and command recipes.
   - Inventory `.claude/commands/` and plugin `commands/`.
   - Convert repeatable procedural commands into Codex skills when they have conditional steps, references, or scripts.
   - Convert short command snippets into `AGENTS.md` recipes if they are project-specific and not worth a standalone skill.
   - Preserve arguments explicitly. Claude command files often rely on text after the command name; Codex skills should say how to pass user-supplied arguments.
   - Flag interactive Claude built-ins with no direct Codex equivalent. Map workflow intent instead:

| Claude command/workflow | Codex target |
|---|---|
| `/init` | `/init` or manually create `AGENTS.md` |
| `/mcp` | `/mcp`, `codex mcp`, `config.toml` |
| `/agents` | `/agent`, Codex subagents/custom agents |
| `/permissions` | `/permissions`, `approval_policy`, sandbox config, rules |
| `/hooks` | Codex hooks files and `/debug-config` |
| `/background`, `/tasks` | Codex `/ps`, `/stop`, subagents, app/remote workflows |
| custom `/deploy` style commands | Codex skill, plugin skill, or repo script documented in `AGENTS.md` |

3. Migrate subagents and agent defaults.
   - Inventory `.claude/agents/`, plugin `agents/`, and the Claude `agent` setting that runs the main thread as a named subagent.
   - Convert agents that describe a reusable workflow into Codex skills.
   - Convert agents that need independent context, parallel execution, or a different model/instruction profile into Codex custom agents/subagents.
   - Preserve tool restrictions as sandbox/approval/rules guidance when Codex custom-agent tool scoping cannot express the same policy.
   - Remember that Codex only spawns subagents when explicitly asked. Add `AGENTS.md` guidance if the old Claude workflow expected automatic delegation.
   - Document whether the agent is `direct`, `partial`, or `manual redesign`:

| Claude agent feature | Codex handling |
|---|---|
| Prompt/instructions | direct to Codex custom agent or skill |
| Model choice | direct if supported in Codex config, otherwise note |
| Tool restrictions | partial; use sandbox, approvals, rules, instructions |
| Hook/MCP/permissionMode frontmatter | partial/manual; verify Codex support before copying |
| Main-thread `agent` setting | manual; use profile/instructions or start with explicit prompt |

4. Migrate permissions, approvals, sandbox, and rules.
   - Treat this as security-sensitive. Do not loosen behavior silently.
   - Map intent rather than syntax:

| Claude behavior | Codex target |
|---|---|
| `permissions.deny` for reads/edits | `[permissions.<name>.filesystem]` deny entries, protected paths, `AGENTS.md` warnings |
| `permissions.allow` for safe Bash prefixes | Codex `rules/*.rules` `prefix_rule(... decision = "allow")` |
| `permissions.ask` | `prefix_rule(... decision = "prompt")` or `approval_policy = "on-request"` |
| `bypassPermissions` | avoid by default; only map to `sandbox_mode = "danger-full-access"` with explicit user approval |
| `acceptEdits` | `workspace-write` plus appropriate approval policy |
| `dontAsk` / auto mode | `approval_policy = "never"` only after confirming sandbox boundaries |
| `--add-dir` | `--add-dir`, writable roots, or scoped project config |
| blocked tool categories | sandbox mode, rules, hooks, MCP server enablement, and instructions |

   - Prefer Codex `approval_policy = "untrusted"` or `"on-request"` and `sandbox_mode = "workspace-write"` as conservative defaults.
   - Use Codex rules for shell escalation prefixes. Rules are exact-prefix based, can be `allow`, `prompt`, or `forbidden`, and load from `rules/` under active config layers.
   - Use hooks only for dynamic checks that rules cannot express.
   - Preserve managed policy intent with system config or `requirements.toml` whe