Migrar de Codex CLI a Claude Code: comandos, config, agents y hooks

29 de julio del 20269 minClaude Code, Codex CLI, OpenAI, Anthropic, AI, Developer Tools, CLI, Migration

Codex CLI (OpenAI) y Claude Code (Anthropic) resuelven el mismo problema: tener un agente de coding dentro de la terminal que lee tu repo, edita archivos, ejecuta comandos y te devuelve control cuando algo necesita tu ojo. La diferencia está en los detalles — y los detalles son los que te rompen el flujo cuando migrás sin pensarlo.

Esta guía es para devs que ya usan Codex CLI y quieren pasar a Claude Code (o evaluarlo en paralelo) sin perder el trabajo que ya hicieron: el AGENTS.md que armaste, el config.toml con tu sandbox y approval policy, los scripts externos que ejecutás como wrappers. Mapeamos comandos uno a uno, traducimos el config, mostramos cómo convertir un AGENTS.md largo en un agent reutilizable y cerramos con un ejemplo real de hook lifecycle.

Cuándo NO migrar. Si dependés de Assistants API, GPT Store, fine-tunes de OpenAI o cualquier feature específica del ecosistema OpenAI, Claude Code no te la cubre. Para esos casos, Codex CLI sigue siendo la elección correcta. Esta guía asume que tu uso es CLI-level (agente en el repo) y no API-level (producto embebido).

Install + setup (5-10 min)

Codex CLI:

install-codex.sh
# macOS / Linux
npm install -g @openai/codex
# o
brew install codex

# Iniciar sesión (auth OAuth en el browser)
codex login

Claude Code:

install-claude.sh
# macOS / Linux / WSL
npm install -g @anthropic-ai/claude-code

# Iniciar sesión
claude
# seguí las instrucciones del browser OAuth

Path de los configs después del install:

• Codex: ~/.codex/config.toml + AGENTS.md (proyecto)
• Claude Code: ~/.claude/settings.json + ~/.claude.json + CLAUDE.md o .claude/CLAUDE.md (proyecto) + .claude/settings.json (proyecto)

Mapeo de comandos del día a día

Las tres diferencias operativas que más vas a notar:

1. Codex CLI no tiene /compact ni /clear. Si el contexto crece, Codex depende del resumen automático del modelo; Claude Code te da comandos explícitos para resetear o compactar manualmente.
2. Codex CLI no tiene comando nativo de commit. El patrón habitual es codex exec "agregá los cambios staged a un commit con mensaje conventional". Claude Code tiene claude commit que arma el mensaje mirando el diff, igual que cz commit o git cz.
3. /init existe en ambos pero el archivo destino cambia: Codex genera AGENTS.md, Claude Code genera CLAUDE.md con la estructura de proyecto que detectó del repo.

Config persistente: de TOML a JSON

Codex CLI:

~/.codex/config.toml
model = "gpt-5"
model_provider = "openai"
approval_policy = "on-failure"
sandbox = "workspace-write"

[providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
wire_api = "responses"

Claude Code:

~/.claude/settings.json
{
"model": "claude-sonnet-5",
"permissions": {
  "defaultMode": "acceptEdits",
  "allow": ["Bash", "Edit", "Read"],
  "deny": ["Bash(rm -rf:*)"]
},
"env": {
  "ANTHROPIC_API_KEY": "sk-ant-..."
}
}

Mapeo campo a campo:

Lo que cambia de modelo mental: Codex separa sandbox (qué puede tocar en disco) de approval_policy (cuándo pedir confirmación). Claude Code unifica los dos en permissions con defaultMode y listas allow/deny por tool. defaultMode puede ser acceptEdits (edita sin pedir, pero los comandos Bash requieren permiso) o bypassPermissions (todo pasa) o plan (solo propone, no ejecuta).

Custom commands y agents

Codex CLI no tiene slash commands definidos por el usuario. Lo más cercano es tu AGENTS.md, que el agente lee como system prompt persistente por proyecto. Si querías un comando custom ("revisá solo performance"), lo armabas como script de shell que llamaba codex exec con un prompt pre-armado.

Claude Code tiene dos primitivas separadas:

1. Slash commands (simples, sin tools propias): archivo .md en ~/.claude/commands/foo.md invocable como /foo. Ideal para prompts que querés reutilizar con un nombre corto.
2. Sub-agents (con su propio system prompt + tools restringidas): archivo .md en ~/.claude/agents/foo.md con frontmatter de name, description y tools. El agente principal lo invoca con la Task tool cuando encaja.

Migración típica: tu AGENTS.md largo.

Si tu AGENTS.md tiene 200 líneas con secciones mezcladas ("reglas del repo", "persona del reviewer", "convenciones de naming"), separalo en Claude Code:

CLAUDE.md (raíz del proyecto)
# Reglas del repo

- Lenguaje: TypeScript estricto
- Tests: Vitest, no Jest
- Style: Prettier + ESLint con config del repo
- Commits: conventional commits, sin co-author

.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Revisa PRs señalando solo issues de seguridad y performance
tools: Read, Grep, Glob, Bash
---

Sos un code reviewer estricto. Tu trabajo es leer el diff y reportar:

1. Vulnerabilidades de seguridad (inyección, XSS, secretos hardcoded).
2. Problemas de performance (O(n²) evitables, queries N+1, memory leaks).
3. Nada más. No comentes estilo ni naming.

Formato del reporte: lista numerada con archivo:línea y fix concreto.

.claude/agents/refactor-planner.md
---
name: refactor-planner
description: Propone planes de refactor para código legacy sin tocar nada
tools: Read, Grep, Glob
---

Cuando te invoquen, leé el archivo o directorio indicado y devolvé un
plan de refactor en pasos numerados. Cada paso: (a) qué cambia,
(b) qué archivos toca, (c) cómo verificar que no rompió nada.

No modifiques archivos. Solo el plan.

El agente principal ahora invoca code-reviewer cuando le pedís "revisá este PR" y refactor-planner cuando le pedís "armame un plan para refactorizar X". Es un mapping natural de lo que antes era un script externo con un prompt pegado.

Hooks y automation

Codex CLI: no tiene hooks. La única automatización es AGENTS.md (instrucciones estáticas) + scripts externos que invocás manualmente.

Claude Code tiene hooks con eventos lifecycle declarados en settings.json. Cada hook es un comando de shell que recibe el contexto del evento por stdin como JSON.

~/.claude/settings.json (extracto)
{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "~/.claude/hooks/block-dangerous.sh"
        }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "~/.claude/hooks/format-on-write.sh"
        }
      ]
    }
  ]
}
}

Ejemplo real: hook que formatea TypeScript con Prettier después de cada edit.

~/.claude/hooks/format-on-write.sh
#!/usr/bin/env bash
# Recibimos el contexto del tool por stdin como JSON
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')

# Solo actuar sobre archivos TS/TSX
case "$file_path" in
*.ts|*.tsx)
  npx prettier --write "$file_path" 2>/dev/null
  ;;
esac

exit 0

Eventos disponibles:

• PreToolUse: corre antes de cada tool call. Podés bloquear (exit 2 = rechaza).
• PostToolUse: corre después. Útil para formateo, logging, métricas.
• UserPromptSubmit: corre cuando el usuario envía un mensaje.
• SessionStart / SessionEnd: arranque y cierre de sesión.
• Stop / SubagentStop: cuando el agente principal o un sub-agent termina.
• PreCompact: antes de compactar el contexto.
• Notification: cuando Claude Code manda una notificación al SO.

El equivalente "hazlo a mano en Codex" es un wrapper de shell que corre codex exec con un prompt que incluye "después de cada edit, corré prettier". Funciona pero pierde precisión — el hook de Claude Code corre en un punto específico del lifecycle, no dependiendo de que el modelo recuerde la instrucción.

Troubleshooting común

• "Permission denied" al ejecutar un comando Bash. Claude Code tiene un allowlist por tool. Solución: agregá el patrón al array permissions.allow en settings.json, o usá defaultMode: "bypassPermissions" si querés saltar la confirmación.
• "Model not found". El nombre del modelo cambia entre releases. Verificá con claude doctor y usá el alias corto (claude-sonnet-5, claude-opus-4-8) en vez del ID largo.
• MCP server no carga. Claude Code lee .mcp.json del proyecto. Si no levanta, corré claude con --debug para ver el error de spawn del server.
• Costos inesperados con thinking models. Si activás extended thinking en Opus 4.8, los thinking tokens se facturan como input. Para mantener el costo bajo, usá Sonnet 5 con thinking solo en tareas largas.
• Codex y Claude Code corriendo en paralelo duplican contexto. Si tenés los dos instalados y los dos leen tu repo, no se rompen entre sí, pero estás pagando inferencia doble. Elegí uno por defecto y usá el otro solo para tareas específicas.
• El AGENTS.md que tenés no se lee. Claude Code no lee AGENTS.md por default — lee CLAUDE.md. Renombrá o creá un symlink: ln -s AGENTS.md CLAUDE.md.

Cierre

Codex CLI sigue siendo un buen agente de coding, y migrar no es obligatorio. La decisión real es cuál te da mejor relación tiempo-resultado para tu workflow. Si tu flujo depende más de slash commands custom, agents reutilizables y hooks lifecycle, Claude Code gana. Si dependés de features específicas del ecosistema OpenAI (Assistants API, GPT Store, fine-tunes), quedate con Codex CLI.

La mayoría de los devs que migran terminan usando los dos en paralelo — Codex para code review o generación one-shot en proyectos donde ya está afinado, Claude Code como agente principal del día a día. Esa es una configuración válida y soportada por ambos.

Docs oficiales: Codex CLI y Claude Code.