Claude Code → Codex · workspace agnóstico

No migres el cerebro. Separa el cerebro del modelo.

Kit de auditoría, adaptadores y núcleo portátil para llevar tu configuración de Claude Code a Codex, o para que contexto, decisiones, tareas y skills funcionen con cualquier modelo.

Agente Claude → Codex: migra o quédate agnóstico
Qué es

Un comando para auditar, adaptar y probar la migración

La newsletter habla de tres niveles: importar en la app (un clic), ejecutar un comando y cuidar la capa personal duradera. Este repo es el nivel 2 y el nivel 3, con scripts que empiezan en modo audit y solo después cambian algo.

🔍 Auditoría de solo lectura

Inventaría skills, comandos, subagentes, hooks, plugins y MCP de Claude y de Codex y clasifica cada ítem: reutilizable, adaptador, nativo o no resuelto. Nada se copia en masa.

🧩 Adaptadores pequeños

CLAUDE.md se convierte en un AGENTS.md portátil más un residuo específico de Claude. Las skills tienen una fuente canónica y copias generadas por runtime con control de drift.

✅ Prueba de continuidad

Una sesión nueva en cada runtime responde: objetivo, regla y fuente, última decisión, próxima acción, conflictos. Que el archivo exista no es prueba. Que el agente lo haya leído y usado, sí.

Cómo funciona

Auditar → organizar → adaptar → probar → handoff

El núcleo (contexto, decisiones, tareas, skills, handoffs) queda en Markdown común dentro del proyecto. En los bordes, un adaptador por herramienta. Claude, Codex, Gemini o un modelo local pasan a ser solo ejecutores.

doctor.sh→ audit.sh→ adapt-instructions.sh→ init-core.sh→ sync-skills.sh→ readback-test.sh→ handoffs/latest.md

📁 Núcleo portátil

AGENTS.md, context/overview.md, context/current-state.md, context/sources.md, context/decisions/, tasks/current.md, handoffs/latest.md, .agents/skills/, scripts/.

🏷️ Dueño por tipo de información

Instrucciones estables, estado actual, decisiones, tareas y handoffs tienen dueño y regla de actualización. Hecho, preferencia, hipótesis y decisión son cosas distintas.

🔁 Ciclo diario

Sesión → handoff en Markdown → la nueva sesión lee el handoff (prime). El resumen estructurado viaja a cualquier proveedor.

Requisitos previos

Qué necesita estar instalado

Los scripts leen las carpetas de configuración de los dos runtimes. Si falta uno, el paso correspondiente queda marcado como no ejecutado.

Claude Code

Fuente de la migración. Skills en ~/.claude/skills.

# versión
claude --version

Codex CLI

Destino. Skills en ~/.agents/skills. El CLI no tiene import nativo.

# versión y diagnóstico
codex --version
codex doctor

polyskill

Convierte una skill en una fuente portátil y genera las copias por runtime.

# instalar
npm i -g polyskill
Guía de uso · paso a paso

Del diagnóstico a la prueba en siete pasos

Cada paso es reversible. Instalar una skill es una vista previa hasta que pases --apply, y reemplazarla hace un backup antes. Los secretos nunca entran al repo.

0

Clonar y diagnosticar el entorno

Responde "¿mi entorno está listo?": git, python3, node, Claude Code, Codex CLI, sandbox, MCP, polyskill. Cada ítem sale como ok, aviso o falta, con el comando para resolverlo.

git clone https://github.com/inematds/agente-claude-codex
cd agente-claude-codex
scripts/doctor.sh  # [ok] / [aviso] / [FALTA]
1

Auditar lo que existe

Genera un informe en Markdown con versiones, la brecha de skills y la matriz reutilizable / adaptador / nativo. Solo lectura.

scripts/audit.sh  # relatorios/auditoria-AAAA-MM-DD.md
2

Separar las instrucciones portátiles del residuo de Claude

Lee el CLAUDE.md del proyecto y propone un AGENTS.md portátil y un CLAUDE.md que importa el AGENTS.md. Los guarda como .proposto.md para que los revises.

scripts/adapt-instructions.sh ~/proyectos/mi-proyecto
# revisar AGENTS.proposto.md y CLAUDE.proposto.md, luego renombrar
3

Instalar el núcleo portátil en el proyecto

Copia la plantilla (context/, tasks/, handoffs/, AGENTS.md) sin sobrescribir nada que ya exista.

scripts/init-core.sh ~/proyectos/mi-proyecto
# luego completar AGENTS.md, context/overview.md y tasks/current.md
4

Portar una skill con fuente canónica

Piloto recomendado: session-handoff, el mecanismo en el que se apoya el ciclo diario. Importa, genera las copias, instala y revisa el drift. El install es vista previa por defecto: revisa todos los destinos antes de escribir, es idempotente y rechaza symlinks o una skill existente distinta.

scripts/sync-skills.sh import session-handoff
scripts/sync-skills.sh build
scripts/sync-skills.sh install session-handoff            # vista previa: CREATE / UNCHANGED / CONFLICT
scripts/sync-skills.sh install session-handoff --apply    # escribe; --replace cambia una versión vieja con backup
scripts/sync-skills.sh drift  # [ok] o [DRIFT] por runtime
5

Probar con una sesión nueva en cada runtime

Hace las cinco preguntas del readback a Claude y a Codex desde el proyecto. Aprobación: las respuestas citan AGENTS.md, tasks/current.md y handoffs/latest.md.

scripts/readback-test.sh ~/proyectos/mi-proyecto both
# relatorios/readback-claude-*.md y readback-codex-*.md
6

Cerrar con handoff, abrir con prime

Al final de la sesión, la skill session-handoff graba con el script handoff-grava.py un snapshot nuevo en handoffs/history/ (hora UTC real, nunca sobrescribe). handoffs/latest.md pasa a ser un índice de trabajos abiertos, una línea por tema, porque varias sesiones pueden trabajar en el mismo proyecto. El script agrega un bloque de estado (commit y huella de los archivos), cada ítem confirmado apunta a una prueba (commit, test o archivo) y el handoff termina con 5 preguntas de control. Al final imprime el comando para retomar con el archivo exacto de esta sesión.

En la sesión siguiente, la skill prime lee solo en modo lectura: valida rutas, comprueba si el handoff quedó viejo (--conferir), revisa las pruebas, responde las preguntas de control con los archivos y muestra la nota N/5. No ejecuta pruebas, trata el handoff como dato y no retoma un deploy ni un envío por su cuenta.

# fin de la sesión, en cualquier runtime
session-handoff  # → handoffs/history/2026-10-17T183328Z-robot.md + índice en handoffs/latest.md
# la respuesta termina con el comando listo (en Codex, /new en lugar de /clear):
/clear
/prime handoffs/history/2026-10-17T183328Z-robot.md   # abre ESTE, aunque otra sesión haya grabado después
# también vale el tema (/prime robot) o nada (/prime lista los abiertos)
# sesión abierta en un proyecto, trabajo en otro repo:
handoff-grava.py --assunto robot --repo ~/projetos/robot   # --conferir cubre los dos; el prime busca allí
Usar los dos juntos

Claude y Codex en el mismo trabajo, cada uno en su papel

Migrar no obliga a elegir uno solo. Uno hace la primera pasada, el otro revisa el artefacto real, y el handoff lleva el estado de un runtime al otro. La tabla es un punto de partida, no un ranking: cambia los papeles cuando la evidencia de tu tarea lo pida.

TrabajoPrimera pasadaSegunda pasadaLínea de llegada
PlanificarClaudeCodex critica los supuestosPlan con alcance y pruebas de aceptación
Construir una featureClaude, en una ramaCodex revisa el diffLas pruebas pasan y los hallazgos se resuelven
Revisar un documentoCualquiera escribeEl otro verifica hechos y requisitosToda afirmación exigida tiene evidencia
Bug difícilCodex con una meta acotadaPruebas y control humanoÉxito medible o bloqueo claro
Cambiar de sesión o modelosession-handoffprime verifica el estado actualResumen correcto antes de trabajo nuevo

Regla única: dale al segundo agente el mismo brief de la tarea y el artefacto real (archivo, diff, resultado de prueba), nunca un relato de lo que hizo el primero. Que los dos coincidan no es prueba: pueden compartir el mismo supuesto equivocado.

1. Planificar y criticar

Uno escribe el plan (alcance, supuestos, pruebas de aceptación, riesgos); el otro lo revisa en solo lectura con el mismo brief. Cada hallazgo queda aceptado, rechazado con evidencia o abierto. Dos rondas como máximo.

2. Construir y revisar el diff

El constructor trabaja en una rama nueva, preserva los cambios existentes y ejecuta las pruebas. El revisor recibe el brief, el diff y los resultados y busca bugs y regresiones antes que estética. Sin merge, deploy ni publicación sin ti.

3. Meta con condición de parada

Objetivo observable (qué suite, qué entrada, qué salida), alcance acotado, detente cuando pase. Si el mismo bloqueo sobrevive a dos intentos, informa y pide la decisión. Un tope real de tiempo o costo se configura en el entorno, no en el prompt.

4. Handoff y prime entre runtimes

Quien sale graba el snapshot en handoffs/history/ y actualiza handoffs/latest.md; quien llega ejecuta prime, verifica el estado sin cambiar nada y espera la instrucción actual. Una sola suscripción también sirve: una segunda sesión revisa con los mismos archivos.

# los prompts listos (en portugués), con campos para completar
cat prompts/05-usar-os-dois.md
# revisión de solo lectura por el otro runtime (por la suscripción, nunca por API paga)
codex exec --sandbox read-only "Revisa plans/tarea-v1.md contra tasks/current.md ..."
claude -p "Revisa el diff de git diff main...HEAD contra el brief ..."

Adaptado del kit "Use Both: Claude + Codex Workflow Kit" de Prompt Advisers / Mark Kashef, licencia MIT. Guía del kit · repositorio.

Un contexto, varias plataformas

Tu IA cambia. Tu contexto sigue.

El contexto de tu negocio vive en un GitHub privado que es tuyo. Claude, ChatGPT, Codex y Gemini solo reciben acceso, las mismas instrucciones y una prueba. ¿Cambiaste de IA? Nada que rehacer. El video muestra la idea completa con dibujos; la plantilla lista está en template/.

Claude y Codex con el mismo contexto · 7min36 · en portugués, con subtítulos en portugués · abrir el reproductor con capítulos

La idea en 8 dibujos

La capa de contexto portátil: IAs arriba, un puente en el medio, el contexto que tú controlas abajo
1. La capa. Arriba, donde trabaja la IA. En el medio, el puente (git, conector, API). Abajo, el contexto que es tuyo.
Archivos y documentos de un lado, datos vivos del otro
2. De qué está hecho. Los documentos (negocio, voz, clientes, skills, decisiones) van a un hogar de documentos; los registros que cambian todo el tiempo van a una base de datos.
Claude y Codex trabajando en la misma carpeta local
3. Nivel 1: tu computadora. Claude y Codex ya trabajan en la misma carpeta. El límite es mantener la laptop encendida.
Nivel 2: GitHub o Notion para archivos, una base en la nube para datos vivos
4. Nivel 2: una casa en la nube. GitHub (solo o equipo técnico) o Notion (equipos), y una base como Supabase para los datos vivos.
Crear un repositorio privado en GitHub
5. Un repositorio privado. Un repositorio es solo una carpeta en línea. Un nombre fácil, y siempre privado.
Instrucciones del proyecto: el repositorio es la fuente de la verdad
6. Las instrucciones del proyecto. El mismo bloque en todas las plataformas: el repo es la fuente de la verdad, leer antes, commit después, sin secretos.
Codex crea un archivo, Claude lee y edita el mismo archivo
7. Ida y vuelta. Una IA crea, la otra lee y edita. Los dos commits aparecen en el mismo historial.
La maleta del núcleo portátil: lo que viaja y lo que no
8. La maleta. Contexto, skills, decisiones y datos viajan. El historial del chat, la memoria de la app y la elección de modelo se quedan.

La plantilla lista: conectar cada plataforma

# instala el núcleo portátil + la carpeta plataformas/ en tu proyecto (no sobrescribe nada)
scripts/init-core.sh ~/proyectos/miempresa-contexto
bash ~/proyectos/miempresa-contexto/scripts/check.sh   # 8 archivos [ok]
PlataformaAccesoInstruccionesPrueba
Claude Code / Codex CLIgit clone del repolee AGENTS.md solo (Claude vía CLAUDE.md → @AGENTS.md)"lee el contexto y di el objetivo"
Gemini CLIgit cloneGEMINI.md → @AGENTS.mdlo mismo
Claude.ai (Proyecto)Personalizar → Conectores → GitHub (integración + MCP)pegar plataformas/instrucoes-projeto.mdeditar una línea de prueba
ChatGPT (Proyecto)Conectores → GitHubpegar el mismo bloquecrear context/teste.md
Codex en la nubeentorno con el repoAGENTS.md ya está en el repopedir una edición y ver el commit

Probado en esta máquina (13/10/2026): en un proyecto creado por init-core.sh, Codex recibió el bloque de instrucciones y creó context/voz.md (commit + push); luego Claude, con el mismo bloque, leyó el archivo creado por Codex, agregó una línea e hizo commit + push. Los dos commits quedaron en el mismo historial. Los conectores de Claude.ai y ChatGPT siguen el mismo bloque, pero dependen de tu cuenta: haz la prueba de ida y vuelta al conectar cada uno. (Los archivos de la plantilla están en portugués; tradúcelos si lo prefieres.)

Repo privado

El contexto del negocio nunca es público. Contraseñas y claves van en la bóveda de cada plataforma, nunca en el repo.

La memoria se vuelve skill

Lo que la IA aprenda se vuelve regla en AGENTS.md, skill en .agents/skills/ o hecho en context/. La memoria de la app no viaja.

Drive y Notion

Hoy Google Drive lee pero no edita bien markdown. Equipos sin Git: Notion como hogar de documentos.

Herramientas

Cada herramienta: cuándo usarla, cómo llamarla, qué genera.

Referencia rápida de las skills y comandos que conectan Claude y Codex. Todo corre con la suscripción de cada asistente, sin clave de API.

HerramientaCuándo usarlaClaude CodeCodexQué genera
session-handoffAl final de la sesión, antes de cambiar de asistente o de modelo/session-handoff$session-handoffResumen en el chat y, si el proyecto tiene handoffs/, AGENTS.md o CLAUDE.md (crea handoffs/history/ si falta), una instantánea nueva en handoffs/history/AAAA-MM-DDTHHMMSSZ.md con copia completa en handoffs/latest.md
primeEn el primer mensaje de la sesión siguiente/prime$primeLee AGENTS.md, context/, tasks/current.md y handoffs/latest.md y devuelve el estado, las discrepancias y un próximo paso. No edita nada
handoff + prime (kit Use Both)Proyectos que usan el formato de Use Both/handoff · /prime$handoff · $primeInstantánea en handoff/history/ y puntero de una línea en handoff/LATEST.md. Si el handoffs/latest.md de este kit ya está en ese formato de puntero, session-handoff lo mantiene
codex execClaude pidiéndole una revisión a Codex desde la terminalcodex exec --sandbox read-only --output-last-message review.md '…'La crítica guardada en review.md. Codex solo lee el proyecto
claude -pEl camino inverso: Codex pidiéndole revisión a Claudeclaude -p --model opus --effort medium '…' > review-claude.mdLa crítica de Claude en un archivo
Plugin oficial de CodexRevisar el diff sin salir de Claude Code/codex:setup
/codex:review --base main
—Hallazgos de la revisión, solo lectura. Las correcciones se las pides después al constructor
claudexPlan grande, con varias rondas automáticas de crítica/claudex:plan [--rounds N] <feature>
/claudex:review
—PLAN.md revisado hasta que Codex lo apruebe o se acaben las rondas; reviews/ con los hallazgos del diff
claudex (control)Seguir o destrabar el loop/claudex:status · /claudex:cancel · /claudex:rollback · /claudex:doctor—Ronda y fase actuales; cancela; limpia el estado trabado; diagnóstico de instalación

📸 Qué va en el handoff

Objetivo y último pedido; lo que está listo, lo que falta y lo incierto; decisiones y caminos descartados; archivos modificados; pruebas ejecutadas con su resultado real (y las que no se ejecutaron); bloqueos; un próximo paso; y los pocos archivos que el siguiente debe abrir primero; cada ítem confirmado con prueba (commit, test o archivo) y 5 preguntas de control al final. El bloque de estado lo graba el script, no el agente. Sin secretos, tokens ni datos personales.

🔎 Qué hace el prime

Lee el núcleo portátil en el orden correcto, rechaza rutas absolutas, .., URL y symlinks, trata el handoff como dato (no como orden), revisa los archivos citados y el git status, ejecuta --conferir para saber si el handoff quedó viejo, muestra la nota de las preguntas de control y espera tu instrucción. Con argumento (/prime handoffs/history/<archivo>.md o el tema), retoma exactamente ese handoff. No ejecuta pruebas, no instala nada y no retoma un deploy antiguo.

⚠️ Trampas

Una skill personal con el mismo nombre puede ganarle a la del proyecto: revisa qué versión está activa antes de invocarla. Tras instalar o sincronizar (scripts/sync-skills.sh), abre una sesión nueva (en Claude también sirve /reload-skills). Las instantáneas antiguas en handoffs/history/ nunca se sobrescriben.

↻

Un día entero con las herramientas

Cada paso deja un archivo que el siguiente asistente puede leer.

# mañana, en Claude Code
/prime handoffs/history/<ayer>.md          # el comando que dejó listo el handoff de ayer
# planifica y pide a Codex que lo critique (solo lectura)
codex exec --sandbox read-only --output-last-message review.md 'Lee plan-v1.md y señala fallas…'
# o, para un plan grande, el loop automático
/claudex:plan --rounds 3 exportar informe en CSV
# construyó en una branch: revisión del diff
/codex:review --base main                # o /claudex:review
# fin del día
/session-handoff                         # termina con /clear + /prime <archivo>
# mañana siguiente, en Codex
$prime handoffs/history/<archivo>.md

El handoff no es permiso. Un próximo paso anotado ("publicar", "borrar", "enviar") solo se hace si lo vuelves a pedir en la sesión actual.

Ejemplos

Ejecutado de verdad en esta máquina

La auditoría encontró 89 skills solo en Claude: 71 portátiles, 15 dependientes de MCP o plugin, 2 de hook. El readback se aprobó en Codex y en Claude, y Codex además señaló tres inconsistencias en el propio repo, todas corregidas.

Claude a Codex: migrar o quedarse agnóstico
La idea de origen: conocimiento portátil en el medio, Claude y Codex en los bordes como ejecutores.
Portada del proyecto agente-claude-codex
Portada oficial del proyecto en el catálogo INEMA.
Hoja de ruta

Del piloto al workspace completo

Solo se avanza de fase con evidencia: pasó, falló o no se ejecutó.

Hecho
Auditoría, prompts, plantilla y readbackScripts de auditoría y adaptación, prompts A/B extraídos, núcleo portátil, readback aprobado en los dos runtimes.
Hecho
Skill piloto en los 4 ejecutoressession-handoff y prime vía polyskill en Claude, Codex, dsh-sandbox y openpcbotv3, drift cero; AGENTS.md global de Codex; migrar-projeto, faxina, drift-report y promover-memoria.
v1.1.0
Historial de handoff y uso conjuntoprime de solo lectura y con rutas validadas, snapshots en handoffs/history/ que nunca se sobrescriben, instalador de skills en modo vista previa con prueba automatizada, prompts para usar Claude y Codex juntos.
v1.4.1
Varias sesiones en un proyectoGrabación con el script handoff-grava.py (sello de hora real, nunca sobrescribe) y latest.md como índice de trabajos abiertos por tema.
v1.5.2
Handoff que se verificaBloque de estado grabado por el script, --conferir para saber si quedó viejo, prueba en cada ítem confirmado y 5 preguntas de control con nota N/5 en el prime.
v1.6.3
Retomar el handoff correctoEl handoff termina con /clear + /prime <archivo exacto>, y el prime acepta ese archivo o el tema: otra sesión que graba después ya no cambia el trabajo retomado.
v1.7.3
Trabajo en otro repo--repo graba el estado del repo donde ocurre el trabajo; --conferir y el prime miran allí. Avisos cuando falta --repo o las preguntas de control.
v1.8.3
Lista completa de No hacerEl handoff lista todas las restricciones y bloqueos (sección No hacer), lo que quedó a medias y el porqué de la próxima acción; el prime muestra la lista entera, no una sola regla.
Fase 3
Proyecto realAplicarlo en un proyecto INEMA con su propio CLAUDE.md y probar una copia aislada.
Fase 4
MCP y hooksRegistrar en Codex solo los MCP que un proyecto necesita; los hooks pasan a ser texto en AGENTS.md cuando no hay un evento equivalente.