oh-my-codex: Adding Workflows, Skills, and Runtime Guardrails to Codex CLI

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

Yeachan-Heo/oh-my-codex, or OMX, is a workflow layer around OpenAI Codex CLI.

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

It is not trying to build yet another coding agent. Its goal is to give people who already use Codex CLI a steadier daily workflow: start sessions with project guidance, clarify before planning when tasks get complex, keep durable goals and state during execution, and use review plus QA to hold the result together at the end.

At the time of writing, the GitHub page shows about 29.4k stars, and the latest release is v0.18.1, published on May 21, 2026. The README also makes it clear that the official project is Yeachan-Heo/oh-my-codex, and the official npm package is oh-my-codex. Third-party projects using names such as “OMX v2” should not be treated as official continuations unless this repository says so.

What it is

OMX does not replace Codex.

It keeps Codex CLI as the actual execution engine and mainly adds three things:

A more consistent task workflow.
Reusable prompts, skills, and specialist agents.
Plans, logs, state, and runtime records under .omx/.

In other words, Codex does the work, while OMX makes that work look more like an engineering process. That is also the main difference between OMX and a normal prompt pack: it is not just a pile of rules inside a system prompt. It breaks clarification, planning, execution, checking, team coordination, and runtime diagnostics into callable surfaces.

Recommended installation

The README and Getting Started docs both emphasize that the recommended default path is macOS or Linux with Codex CLI. Native Windows and Codex App are not the primary experience today and may behave inconsistently or receive less complete support.

If Codex CLI is already installed, start with:

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

If you do not have Codex CLI yet and want npm to manage it:

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

One detail matters: do not combine @openai/codex and oh-my-codex into one global install command on a machine where Homebrew already owns the codex binary. The README notes that npm may hit an EEXIST conflict with a Homebrew-owned binary. OMX only needs a working, authenticated codex command on PATH; Codex does not have to be installed through npm.

After installation, run a real execution smoke test:

1
2

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

omx doctor can show that the local install shape looks sane, but it cannot prove that the Codex account, proxy, base URL, and authentication path in the current shell/profile can actually make a model call. This distinction matters when you switch between different HOME directories, containers, remote environments, or local OpenAI-compatible proxies.

Default workflow

The main OMX workflow is roughly:

$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"

The most common path is three steps:

$deep-interview: ask for boundaries, goals, and non-goals when the request is still unclear.
$ralplan: turn the request into a plan, then confirm it through architectural and critical review.
$ultragoal: turn the approved plan into more durable goals and checkpoints.

If a task needs parallel coordination, use $team inside an Ultragoal story. If it only needs one persistent owner, use $ralph. The naming can feel heavy at first, but the idea is simple: do not let an agent start changing files as soon as it hears a request. First write down what to do, how to do it, how to verify it, and when to stop.

What skills and agents provide

OMX groups skills into several families.

Canonical Workflow includes $deep-interview, $ralplan, $prometheus-strict, $ultragoal, $code-review, and $ultraqa. These are aimed at complete engineering tasks: clarify, plan, execute, review, and QA.

Execution Modes include $team, $ralph, $autopilot, $ultrawork, and others. They decide whether a task moves through a single line, a team runtime, or a stronger autonomous loop.

The Agent Catalog is more like a role library. It includes analyst, planner, architect, debugger, executor, verifier, security-reviewer, performance-reviewer, code-reviewer, test-engineer, designer, researcher, and more. You do not need to invoke these roles manually every day, but they show that OMX is not a “one big prompt” system. It decomposes engineering work into reusable roles and phases.

That matters for long-running projects. Many AI coding failures do not happen because the model cannot write code at all. They happen because it moves into execution too quickly and skips requirement confirmation, architecture boundaries, test baselines, and final review. OMX tries to make those steps harder to skip.

Plugin shape and runtime state

The README says the repository also includes an official Codex plugin layout at plugins/oh-my-codex, with marketplace metadata.

The docs are also clear that this plugin shape is not a replacement for npm install -g oh-my-codex plus omx setup. The plugin mainly packages hooks, the skill surface, and Codex lifecycle integration. At runtime, it still depends on the installed omx CLI.

The latest v0.18.1 release also focuses on this area: plugin installs now use a pinned OMX launcher, hook failures are safer, Ultragoal state mutations are serialized, release packaging excludes crate-local .omx runtime caches, and npm, Cargo workspace, lockfiles, and the plugin manifest all share the same version.

These changes show that OMX is no longer just a prompt repository. It is also dealing seriously with install shape, hook safety, state writes, release package contents, and runtime consistency. For developer tooling, these are not flashy details, but they matter a lot.

Who it fits

OMX is best for developers who already use Codex CLI seriously, especially in situations like these:

You often ask Codex to handle multi-file, multi-step tasks.
You want the agent to clarify requirements before editing code.
You want planning, execution, checking, review, and QA to be separate stages.
You want .omx/ state, plans, and logs in the project.
You want to try tmux/team runtime or stronger long-task execution.
Your team wants to turn its engineering habits into reusable skills and prompts.

If you only ask Codex to change one line of config, generate a small script, or explain a code snippet, OMX may feel heavy. It is more like a tool belt for frequent AI coding users than a required first layer for beginners.

Things to watch

First, do not treat OMX as a guarantee of unattended completion. It can strengthen the workflow, but it cannot decide for you whether a requirement is reasonable, whether an architecture should change, or whether a risk is acceptable.

Second, pay attention to platform boundaries. The README currently recommends macOS/Linux plus Codex CLI. Native Windows exists, but it is not the default best experience. If you use Windows, WSL2 is usually the steadier path.

Third, omx doctor is not final validation. The stronger proof is a real model call such as codex login status plus omx exec.

Fourth, stronger workflow requires clearer task boundaries. $ultragoal, $team, and $autopilot are best for tasks with concrete acceptance criteria. If the request is still vague, use $deep-interview or a normal conversation first.

Summary

The value of oh-my-codex is not that it turns Codex into a different tool. It adds a more engineering-oriented working layer to Codex CLI.

It moves AI coding from “I say one thing, you make one pass” toward “clarify, plan, execute, check, and record state.” For lightweight tasks this may be too much. For people who use Codex on real projects often, stable workflows, reusable skills, runtime diagnostics, and durable goals can be exactly what saves effort.

If Codex CLI is already part of your daily development setup, OMX is worth trying. Even if you do not install it directly, its breakdown of skills, agents, planning, and acceptance flow is useful material for improving your own AI coding workflow.

References

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