oh-my-codex: flujos de trabajo, skills y guardrails de runtime para Codex CLI

Mon, 25 May 2026 07:41:45 +0800

Yeachan-Heo/oh-my-codex, abreviado como OMX, es una capa de flujo de trabajo alrededor de OpenAI Codex CLI.

Proyecto: https://github.com/Yeachan-Heo/oh-my-codex

No intenta resolver el problema creando “otro coding agent”. Su objetivo es dar a quienes ya usan Codex CLI una forma de trabajo diaria más estable: iniciar sesiones con instrucciones del proyecto, aclarar antes de planificar cuando la tarea se vuelve compleja, mantener durable goals y estado durante la ejecución, y cerrar con review y QA para controlar el resultado.

En el momento de escribir esto, la página de GitHub muestra unas 29.4k stars, y el release más reciente es v0.18.1, publicado el 21 de mayo de 2026. El README también deja claro que el proyecto oficial es Yeachan-Heo/oh-my-codex y que el paquete npm oficial es oh-my-codex. Los proyectos de terceros con nombres como “OMX v2” no deben tratarse como continuaciones oficiales salvo que este repositorio lo indique.

Qué es exactamente

OMX no sustituye a Codex.

Mantiene Codex CLI como motor real de ejecución y añade principalmente tres cosas:

Un flujo de tareas más consistente.
Prompts, skills y specialist agents reutilizables.
Planes, logs, estado y registros de runtime bajo .omx/.

Dicho de otra forma, Codex hace el trabajo y OMX intenta que ese trabajo se parezca más a un proceso de ingeniería. Esa es también la gran diferencia frente a un paquete común de prompts: no se limita a meter reglas dentro de un system prompt. Divide la aclaración, planificación, ejecución, comprobación, coordinación de equipo y diagnóstico de runtime en superficies invocables.

Instalación recomendada

El README y la documentación Getting Started enfatizan que la ruta recomendada por defecto es macOS o Linux con Codex CLI. Windows nativo y Codex App no son hoy la experiencia principal, y pueden comportarse de forma inconsistente o tener soporte menos completo.

Si ya tienes Codex CLI instalado, puedes empezar así:

codex --version
npm install -g oh-my-codex
omx setup
omx doctor

Si todavía no tienes Codex CLI y quieres que npm lo gestione:

npm install -g @openai/codex
npm install -g oh-my-codex
omx setup
omx doctor

Hay un detalle importante: no combines @openai/codex y oh-my-codex en un único comando de instalación global en una máquina donde Homebrew ya posee el binario codex. El README menciona que npm puede chocar con EEXIST cuando intenta crear un binario que ya gestiona Homebrew. OMX solo necesita un comando codex funcional, autenticado y disponible en PATH; no exige que Codex haya sido instalado con npm.

Después de instalar, conviene ejecutar una prueba real:

1
2

codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

omx doctor puede demostrar que la forma de la instalación local parece correcta, pero no prueba que la cuenta de Codex, el proxy, la base URL y la autenticación del shell/profile actual puedan realizar una llamada real al modelo. Esta diferencia importa mucho al cambiar entre distintos HOME, contenedores, entornos remotos o proxies locales compatibles con OpenAI.

Flujo por defecto

El flujo principal de OMX es aproximadamente:

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$prometheus-strict "stress-test the plan before durable execution"
$ultragoal "turn the approved plan into durable Codex goals"

La ruta más común tiene tres pasos:

$deep-interview: pregunta por límites, objetivos y no-objetivos cuando la petición aún no está clara.
$ralplan: convierte la petición en un plan y lo confirma desde una mirada arquitectónica y crítica.
$ultragoal: convierte el plan aprobado en objetivos y checkpoints más duraderos.

Si una tarea necesita coordinación en paralelo, se puede usar $team dentro de una Ultragoal story. Si basta con un único responsable persistente, se puede usar $ralph. Los nombres pueden parecer pesados al principio, pero la idea es simple: no dejar que el agent empiece a modificar archivos apenas escucha una petición. Primero hay que escribir qué se hará, cómo se hará, cómo se verificará y cuándo debe detenerse.

Qué aportan skills y agents

La documentación de OMX agrupa las skills en varias familias.

Canonical Workflow incluye $deep-interview, $ralplan, $prometheus-strict, $ultragoal, $code-review y $ultraqa. Están orientadas a tareas de ingeniería completas: aclarar, planificar, ejecutar, revisar y pasar QA.

Execution Modes incluye $team, $ralph, $autopilot, $ultrawork y otros modos. Definen si la tarea avanza en una sola línea, con ejecución de equipo o mediante un bucle autónomo más fuerte.

El Agent Catalog se parece más a una biblioteca de roles. Incluye analyst, planner, architect, debugger, executor, verifier, security-reviewer, performance-reviewer, code-reviewer, test-engineer, designer, researcher y otros. No hace falta invocar estos roles manualmente todos los días, pero muestran que OMX no es “un gran prompt universal”. Descompone el proceso de ingeniería en roles y fases reutilizables.

Esto importa en proyectos largos. Muchos fallos en AI Coding no ocurren porque el modelo sea incapaz de escribir código. Ocurren porque entra demasiado rápido en ejecución y salta la confirmación de requisitos, los límites de arquitectura, la línea base de tests y la revisión final. OMX intenta fijar esos pasos mediante skills y roles.

Forma de plugin y estado de runtime

El README menciona que el repositorio también incluye un Codex plugin layout oficial en plugins/oh-my-codex, con marketplace metadata.

La documentación también insiste en que esta forma de plugin no sustituye a npm install -g oh-my-codex más omx setup. El plugin se parece más a un empaquetado de hooks, skill surface e integración con el ciclo de vida de Codex. En runtime sigue dependiendo del CLI omx instalado.

El release más reciente, v0.18.1, también se centra en esta línea: las instalaciones de plugin usan un pinned OMX launcher, los fallos de hooks son más seguros, las mutaciones de estado de Ultragoal se serializan, el empaquetado de release excluye caches .omx locales de crates, y npm, Cargo workspace, lockfiles y el plugin manifest declaran la misma versión.

Estos cambios muestran que OMX ya no es solo un repositorio de prompts. Empieza a tratar en serio la forma de instalación, la seguridad de hooks, la escritura de estado, el contenido del paquete de release y la consistencia entre runtimes. Para una herramienta de desarrollo, estos detalles no son vistosos, pero son importantes.

Para quién encaja

OMX encaja mejor con desarrolladores que ya usan Codex CLI de forma seria, especialmente en estos casos:

Pides a Codex tareas de varios archivos y varios pasos con frecuencia.
Quieres que el agent aclare requisitos antes de editar código.
Quieres separar planificación, ejecución, comprobación, review y QA.
Necesitas conservar estado, planes y logs bajo .omx/ en el proyecto.
Quieres probar tmux/team runtime o formas más fuertes de ejecutar tareas largas.
Tu equipo quiere convertir sus hábitos de ingeniería en skills y prompts reutilizables.

Si solo usas Codex de vez en cuando para cambiar una línea de configuración, generar un script pequeño o explicar un fragmento de código, OMX puede sentirse pesado. Es más una caja de herramientas para usuarios frecuentes de AI Coding que una primera capa obligatoria para principiantes.

Qué conviene vigilar

Primero, no trates OMX como una garantía de “ejecución autónoma hasta completar todo”. Puede reforzar el proceso, pero no decide por ti si un requisito es razonable, si una arquitectura debe cambiar o si un riesgo es aceptable.

Segundo, revisa los límites de plataforma. El README recomienda actualmente macOS/Linux + Codex CLI. La ruta de Windows nativo existe, pero no es la mejor experiencia por defecto. Si usas Windows, WSL2 suele ser una opción más estable.

Tercero, omx doctor no es una validación final. La prueba más fuerte es una llamada real al modelo, como codex login status más omx exec.

Cuarto, cuanto más fuerte es el flujo, más claros deben ser los límites de la tarea. $ultragoal, $team y $autopilot encajan con tareas que tienen criterios de aceptación concretos. Si la petición todavía es ambigua, conviene usar $deep-interview o una conversación normal para aclararla primero.

Resumen

El valor de oh-my-codex no está en convertir Codex en otra herramienta, sino en añadir a Codex CLI una capa de trabajo más orientada a ingeniería.

Mueve el AI Coding de “te digo algo y haces una pasada” hacia “aclarar, planificar, ejecutar, comprobar y registrar estado”. Para tareas ligeras puede ser demasiado. Para quienes usan Codex en proyectos reales con frecuencia, flujos estables, skills reutilizables, diagnósticos de runtime y durable goals pueden ser justo lo que reduce fricción.

Si Codex CLI ya forma parte de tu desarrollo diario, OMX merece una prueba. Incluso si no lo instalas directamente, su forma de dividir skills, agents, planificación y criterios de aceptación sirve para mejorar tu propio flujo de AI Coding.

Referencias

Yeachan-Heo/oh-my-codex: https://github.com/Yeachan-Heo/oh-my-codex
Getting Started: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/getting-started.html
Agent Catalog: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/agents.html
Skills Reference: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/skills.html
v0.18.1 release: https://github.com/Yeachan-Heo/oh-my-codex/releases/tag/v0.18.1

Oh-My-Codex on KnightLi Blog