oh-my-codex (OMX)
TL;DR
oh-my-codex, or OMX, is an MIT-licensed npm package by Yeachan Heo and co-maintainers that wraps OpenAI Codex CLI with a staged workflow of skills, a tmux and git-worktree team runtime, hooks, a status HUD and durable state under .omx/. Codex remains the execution engine. It suits Codex users on macOS or Linux who want parallel workers.
Key facts
| Type | Orchestrator |
|---|---|
| Languages / SDKs | TypeScript, Rust |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 33,433 (as of 2026-09-30) |
| GitHub forks | 2,544 |
| Last push | 2026-09-30 |
| Latest release | v0.21.6 |
| Repository | Yeachan-Heo/oh-my-codex |
| Website | oh-my-codex.dev |
| Documentation | github.com |
| Last verified | 2026-09-30 |
Key features
- A default workflow of
$deep-interview,$ralplanand$ultragoal, with$autopilotas the orchestrator that chains them; each stage can also be invoked on its own. (source) omx teamstarts a durable tmux runtime with several workers (for exampleomx team 3:executor "..."), with status, resume and shutdown subcommands; workers get dedicated git worktrees by default. (source)omx --worktree=<name>launches Codex in a named git worktree, and separateOMX_ROOTvalues allow several concurrent conversations from one checkout. (source)- Durable state under
.omx/for plans, logs, memory, mission ledgers and Ultragoal checkpoints, plus scopedAGENTS.mdguidance installed byomx setup. (source) - A Codex plugin layout at
plugins/oh-my-codexwith marketplace metadata, registering official Codex lifecycle hooks that call the installedomxCLI. (source) - Optional first-party MCP servers (state, memory, code-intel, trace and others) shipped disabled by default in the plugin manifest. (source)
- A documented Team coordination protocol covering acknowledgements, claim-safe task lifecycle, blocked-lane reporting and leader-owned Ultragoal state. (source)
omx hud --watchshows a live row per team agent with state, task, role and tmux pane, andomx doctorchecks the install. (source)
Architecture and orchestration pattern
Pattern: Supervisor
OMX is an npm CLI, written mainly in TypeScript with Rust runtime crates, that launches and augments Codex CLI rather than replacing it. omx setup installs prompts, skills, scoped AGENTS.md guidance, .codex/config.toml and Codex hooks, or relies on the Codex plugin layout for skills and hooks. The README states that Codex does the actual agent work.
Multi-agent coordination is the $team runtime. A leader session dispatches tasks to workers that run in tmux panes, each in its own git worktree by default. Dispatch, mailbox, monitor and integration states have documented owners in the team runtime state contract, and a worker counts as integrated only after leader-head containment checks pass. Inside an Ultragoal story the leader owns the Ultragoal state and workers report evidence upward.
State is file-based: plans, logs, notepad and project memory, mission summaries and Ultragoal ledgers live under .omx/, and team startup writes a preflight context file so runs can resume after compaction. The project's own architecture note says the CLI and JSON surface is the canonical control plane, with MCP as an optional compatibility layer.
Human in the loop
The default flow has explicit human stages: $deep-interview clarifies requirements before any code, and $ralplan produces a plan for the user to approve and review for trade-offs, with planning skills stopping at planning artifacts. Team runs can be inspected with omx team status and omx hud --watch, and stopped with omx team shutdown or omx cancel. The recommended launch flag --madmax maps to Codex's dangerously-bypass-approvals-and-sandbox option, which removes approval and sandbox guardrails; the README limits it to trusted repositories.
Harnesses it can drive
- Codex (evidence)
- Hermes (evidence)
Protocols
| Protocol | Support | Note |
|---|---|---|
| MCP | Yes evidence | Server side: OMX ships small optional first-party MCP servers launched with omx mcp-serve <name> (state, memory, code-intel, trace, a Hermes bridge and others), registered but disabled by default in the plugin manifest; its architecture note calls MCP an optional compatibility layer, with CLI and JSON as the canonical interface. |
| A2A | Unknown | No A2A / Agent2Agent mention in the README; repo code search returned only a release-readiness note and a capabilities lock file, not read as protocol support. |
| AG-UI | Unknown | No AG-UI mention in the README; repo code search for ag-ui returned nothing; not checked against a listing in the AG-UI README. |
Best for
- Codex CLI users on macOS or Linux who want a fixed clarify, plan and execute workflow with durable checkpoints. (shortlist)
- Running several Codex workers in parallel tmux panes, each in its own git worktree, under one leader. (shortlist)
- Coordinators such as Hermes that need to dispatch work to Codex, poll status and fetch result artifacts through an MCP bridge.
- Long tasks that must resume after context compaction, using state files kept in the repository. (shortlist)
Not for
- Users who want plain Codex with no extra workflow layer; the README says they probably do not need OMX.
- Native Windows or the Codex App as the primary environment; the README says they are not the default path and receive less support.
- Setups that need Codex's approval and sandbox protections while using the recommended --madmax launch.
Quickstart
npm install -g oh-my-codex# Codex CLI must already be installed and authenticated
codex --version
npm install -g oh-my-codex
# From the git project Codex should edit
omx setup --scope project --merge-agents
omx doctor
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
# Launch in a named worktree (--madmax bypasses approvals and sandbox)
omx --worktree=feat/task --madmax --xhigh
# Inside Codex
# $deep-interview "clarify the authentication change"
# $ralplan "approve the auth plan and review tradeoffs"
# $ultragoal "turn the approved plan into durable Codex goals"
# Parallel workers (needs tmux)
omx team 3:executor "fix the failing tests with verification"
omx team status <team-name>
Common pitfalls
- Requires Node.js 20+, an authenticated Codex CLI, and tmux on macOS or Linux for the team runtime.
- Do not run
npm install -g @openai/codex oh-my-codextogether over a Homebrew-ownedcodex; npm can fail with EEXIST. - A green
omx doctordoes not prove Codex can authenticate; runcodex login statusand theomx execsmoke test from the same shell. - A second plain
omxlaunch from the same checkout fails closed; give each conversation its ownOMX_ROOTor a named worktree. --madmaxremoves approval and sandbox guardrails.- Avoid project-scoped setup from a broad home directory, where a global AGENTS.md may hold unrelated rules.
- Intel Macs may show high syspolicyd or trustd CPU at startup with
--madmax --high. - Third-party projects named like OMX v2 are not official continuations, per the README.
Pros
- Team runtime state has a written contract naming the authoritative owner of each state, and integration requires leader-head containment checks rather than mailbox or tmux activity. (source)
- Worktree launches and per-worker worktrees are documented, including the concurrency limits and the fail-closed behaviour for a second launch. (source)
- CLI and JSON are documented as the canonical control plane, so scripts and recovery do not depend on MCP transport working. (source)
- Setup includes a doctor command and an explicit real-execution smoke test, with a troubleshooting section for false-green readiness. (source)
- MIT licensed with tagged releases every few days to weeks and a published release protocol. (source)
Cons
- Codex CLI only: OMX is a workflow layer for Codex and does not drive other coding agents. (source)
- Native Windows and the Codex App are not the default experience and receive less support; team mode works best on macOS or Linux with tmux. (source)
- The recommended launch uses --madmax, shorthand for Codex's bypass of approvals and sandbox. (source)
- The README itself points users who find OMX overkill to a separate, simpler project, gajae-code. (source)
- Known issue on some Intel Macs: high syspolicyd and trustd CPU during startup, especially with --madmax --high. (source)
Alternatives
FAQ
Does oh-my-codex support MCP?
Yes, on the server side. It ships small first-party MCP servers, launched with omx mcp-serve, including a bridge for Hermes-style coordinators. They are registered but disabled by default, and the project calls MCP an optional layer over its CLI and JSON interface.
Does it work without Codex?
No. It is a workflow layer for OpenAI Codex CLI, which must be installed and authenticated. Codex remains the execution engine.
How does it run several agents at once?
Through the $team runtime: a leader dispatches tasks to workers in tmux panes, each worker in its own git worktree by default, with status, resume and shutdown commands. Run omx team 3:executor followed by a task.
Is it free?
Yes. The repository is MIT licensed and no paid product is documented. Codex and model usage are billed by OpenAI or your provider.
How does it relate to oh-my-openagent?
They are separate projects. The oh-my-openagent README says its Ultragoal and UltraQA ideas come from oh-my-codex and were reimplemented for OmO.