oh-my-codex (OMX): a workflow layer for OpenAI Codex CLI

What problem oh-my-codex solves, and for whom

Codex CLI is an execution engine. It takes instructions and edits files. What it does not ship with, according to the README, is a consistent procedure for the parts around the edit: clarifying a request before work starts, keeping a plan and its logs somewhere durable, and reusing the same review or QA pass across sessions. OMX positions itself as that layer. The README states plainly that it "keeps Codex as the execution engine" and adds prompts, workflows and runtime help on top.

The intended user is someone who already has a working, authenticated codex command on PATH. The README says OMX "only needs a working, authenticated `codex` command on `PATH`" and does not require Codex to be installed through npm. That is a narrower audience than a general coding-assistant tool: if you have not installed Codex CLI, OMX has nothing to orchestrate.

The second half of the audience is teams that want the same workflow invoked by name. OMX exposes `$plan`, `$ultragoal`, `$team`, `$code-review` and `$ultraqa` as separate entry points. The README is careful to note each runs "independently, no fixed chain", which matters if you only want the review pass and not the planning ceremony around it.

How the OMX workflow layer sits on top of Codex CLI

Two mechanisms are visible in the repository. The first is a CLI: package.json declares a single bin, `omx`, pointing at `dist/cli/omx.js`. Everything the user types goes through that entry point, including setup, update and doctor.

The second is state on disk. The README says OMX keeps "project guidance, plans, logs, and state in `.omx/`". That directory is the contract between sessions: guidance for the agent, the plan it is following, and whatever the workflow recorded. Setup writes a scope file there too, `./.omx/setup-scope.json`, which records an explicit merge policy as `mergeAgents: true` or `false`.

Underneath the TypeScript there is a Rust workspace. Cargo.toml lists six members: `crates/omx-api`, `crates/omx-explore`, `crates/omx-mux`, `crates/omx-runtime-core`, `crates/omx-runtime` and `crates/omx-sparkshell`. The build scripts in package.json confirm these are not vestigial: `build:runtime` runs `cargo build -p omx-runtime`, and `build:explore` runs `cargo build -p omx-explore-harness`. So an install from source is a two-toolchain job, TypeScript plus a Rust 1.73 toolchain. The published npm package hides that, but anyone building from the repository should expect it.

A third mechanism is hooks. The repository has a top-level `hooks/` area referenced by test paths such as `dist/hooks/__tests__/explore-routing.test.js`, and the project description advertises hooks, agent teams and HUDs. The README excerpt does not document the hook API, so treat hook authoring as something to read the docs site for rather than something the README explains.

Installing oh-my-codex and running a first session

The README gives two install paths. If Codex CLI is already present, check it and install OMX globally:

codex --version
npm install -g oh-my-codex

If Codex is not installed yet and you want npm to manage it, the README gives this pair instead:

npm install -g @openai/codex
npm install -g oh-my-codex

Do not combine them into one command over an existing Homebrew-owned binary. The README warns that `npm install -g @openai/codex oh-my-codex` can fail with `EEXIST` when `@openai/codex` tries to create a binary that Homebrew already owns, such as `/opt/homebrew/bin/codex`.

After installing, choose a setup scope deliberately. From the git project you want OMX to operate on:

omx setup --scope project --merge-agents

The README recommends `--scope user` instead when you are not preparing the current directory as an OMX project, and warns against running project-scoped setup from a home directory or operating hub, because a home-level `AGENTS.md` usually holds global safety and routing rules. Then launch a session:

omx --worktree=feat/task --madmax --xhigh

The README shows this exact invocation as the recommended default flow, run from the git project you want Codex to edit, with a task-specific worktree name. What you should see is a Codex session started through OMX rather than through codex directly, with the workflow commands available inside it. If something looks wrong, `omx doctor` is the diagnostic entry point declared in package.json.

The merge policy flags, and why they are stricter than they look

OMX's AGENTS.md handling has more rules than a typical setup wizard, and the README documents them precisely enough that they are worth reading before you run setup twice.

There are three policy selectors: `omx setup --merge-agents`, `omx setup --no-merge-agents` and `omx setup --clear-merge-agents-policy`. The README states these are the only selectors and that you must use their bare forms, not `=value` spellings. Repeating the same selector is harmless. Mixing a set choice with a clear choice fails before setup changes anything.

An explicit set is recorded in the current working root's `./.omx/setup-scope.json`, and the README notes this happens even when the setup scope is `user`. It never becomes a global user preference. Later `omx update` replays a valid matching policy for both immediate and deferred refreshes.

The semantics of `false` are narrower than the name suggests, and the README says so: `false` "only suppresses that branch: it does not promise preservation, replacement, or any new safety mode". The existing prompt, skip, managed-refresh, plugin-default and force behavior still applies. If you read `--no-merge-agents` as a guarantee that your AGENTS.md will be left untouched, you have read it wrong.

`--force` is separate and transient. It is neither recorded nor replayed, and it does not override an explicit merge policy. Malformed, unknown, nonboolean or wrong-scope saved data is ignored safely, which is the right failure direction but also means a typo in that file silently does nothing.

Platform limits and the Windows and Codex App gap

The README carries a caution block that is unusually direct: OMX is "primarily designed and actively tuned" for macOS or Linux with Codex CLI, and native Windows and the Codex App "are not the default experience, may break or behave inconsistently, and currently receive less support".

That is the clearest limitation in the project's own words. If your team is on Windows, OMX is the wrong tool today, regardless of how well the workflow commands fit your process. The same applies if your workflow runs through the Codex App rather than the CLI.

There is a second, quieter limitation in the packaging. The project spans a TypeScript CLI and a Rust workspace, and the npm scripts include `build:explore:release`, `build:sparkshell` and `build:api`. Contributors building from source need both toolchains and should expect the native crates to be part of the install path, not an optional extra. The README does not document rollback for a setup that has already written AGENTS.md changes, so a bad setup run is something you undo by hand or from version control, not through an OMX command.

Finally, the README spends a paragraph on naming: third-party projects using names like "OMX v2" are not official continuations unless the README or docs say so. That is a signal that the name has been reused elsewhere, and it means you should verify you are installing `oh-my-codex` from the official repository rather than a lookalike package.

Where OMX differs from gajae-code and plain Codex CLI

The README points to a sibling project, gajae-code, with the line "Liked OmX but find it a bit overkill?" and describes it as an SDK-based path that keeps Codex OAuth while aiming to be "faster, cheaper, simpler". The two share a Discord community.

The difference in approach is scope. OMX is a workflow layer: named commands, hooks, agent teams, a HUD, and durable state in `.omx/`. gajae-code is described as an integration path with a smaller surface. If your complaint about OMX is that it adds ceremony you did not ask for, gajae-code is the author's own answer to that complaint, which is a more useful signal than a third-party comparison.

The other alternative is doing nothing. Plain Codex CLI plus your own AGENTS.md and your own prompts is a legitimate setup, and it has no extra install, no npm update check at launch, and no `.omx/` directory to reason about. OMX earns its place only if you actually use the workflow commands or need the plan and log state to persist across sessions. Installing it and then driving Codex exactly as before gets you the update prompts and nothing else.

Updates, licence and the cost of staying current

OMX checks npm for updates at launch on a throttled cadence, and the README says it prompts before scheduling an update after the current session exits. Two environment variables control this. `OMX_AUTO_UPDATE=0` disables the launch-time check. `OMX_AUTO_UPDATE=defer` schedules the same deferred update without prompting. `omx update` checks npm and runs the setup refresh path.

On a version bump, the README notes that the global npm install now prints an explicit reminder instead of launching setup automatically. That is a deliberate change: upgrading the package no longer silently rewrites your setup. The cost is that staying current is two steps, the npm upgrade and then the setup refresh, and a deferred update only lands after the session exits.

The licence situation is worth stating carefully. The README's badge links to opensource.org/licenses/MIT, and Cargo.toml declares `license = "MIT"` for the Rust workspace. The repository also contains a top-level LICENSE file. The repository metadata supplied for this project lists the licence as unknown, which conflicts with those two in-repo signals. Before you depend on OMX in a commercial setting, open LICENSE at the repository root and confirm it yourself. Nothing here is legal advice, and the workspace-level MIT declaration in Cargo.toml covers the crates, not necessarily the TypeScript in `src/`.

Maintenance cadence is visible from the release history: v0.21.0 on 2026-08-22, v0.20.5 on 2026-08-10, v0.20.4 on 2026-07-31. The last push to the default branch was 2026-08-22. The repository is not archived.

Editorial conclusion

Adopt OMX if you already run Codex CLI on macOS or Linux and want repeatable workflows plus project state in .omx/. Skip it if you work natively on Windows, rely on the Codex App, or do not want a second npm package between you and your agent. Before committing, run omx doctor, confirm which scope your setup wrote to, and read .omx/setup-scope.json to see whether a merge policy was recorded.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes