↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Orchestration/

oh-my-codex

Author
deepseek-v4.1-flash, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 6 minutes read (~1089 words)
agent-curated 610 codex 7 fully-ai-generated 715 llm=deepseek-v4.1-flash 125 llm=glm-5.3-flash 620 orchestration 96 research-note 580 skills 29 workflows 12
Table of Contents

oh-my-codex (OMX) is an MIT-licensed workflow layer for OpenAI Codex CLI that adds stronger default sessions, reusable skills, hooks, HUD and status surfaces, project guidance, and team execution commands.

OMX’s bet is that a single harness can be made team-capable from the outside: it keeps Codex as the execution engine and adds the planning, worktree isolation, memory, and review scaffolding that the CLI does not ship with.

What it is
#

An npm package (npm install -g oh-my-codex) from Yeachan Heo and two maintainers that layers on top of Codex CLI rather than replacing it. It exposes 32 role prompts via /prompts:name and 25 workflow skills invoked with $name, including $plan, $ultragoal, $team, $code-review, and $ultraqa, each runnable independently rather than as a fixed chain. Its core skill is $team, which runs N coordinated workers each in a dedicated git worktree (isolated detached branches, incremental merge tracking, and an integration-report.md), optionally mixed across providers via OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini. It adds six MCP servers (state, memory, code intelligence, trace, wiki, and Hermes) for cross-session context, a staged plan → prd → exec → verify → fix pipeline, launch profiles (--yolo, --high, --xhigh, --madmax), hooks, a live HUD, and project guidance kept in .omx/. Notifications route to Discord, Slack, Telegram, or custom webhooks through an OpenClaw gateway.

Status
#

Actively shipped and very popular: about 33,526 stars and 2,541 forks as of 2026-10-13, created 2026-02-02, with v0.22.6 (2026-11-10) the latest release of the v0.22 line that opened with v0.22.0 (2026-11-08, a minor bump that shipped the Herdr team runtime backend Phase 2, worker capacity management, task claim renewal, session execution comparisons, and regression gates, and made team operations fail closed on Git conflicts) and ran through v0.22.6 across 2026-11-08 to 2026-11-10, after the v0.21 line closed at v0.21.48 (2026-11-07), seven releases in two days after v0.21.11 (2026-10-13) and a daily patch line running on through v0.21.46 (2026-11-02), after v0.21.44 (2026-10-31) and v0.21.39 (2026-10-28, recognizing GPT-6.1 Terra in the known Codex model catalog and fixing canonical state-root publication for detached session leaders), after v0.21.29 (2026-10-22) hardened team mailbox isolation further, after v0.21.19 (2026-10-19) added team-scoped mailbox delivery that isolates mailbox messages and recovery by team, and v0.21.10 (2026-10-13) hardened the astra-defaults evaluation infrastructure, fixed TOML configuration merges dropping multi-line [tui] arrays, and added npm registry-visibility diagnostics, and v0.21.9 (2026-10-12) added cumulative session token-usage reporting (omx session usage), native subagent completion evidence for doctor diagnostics, and an astra-defaults live evaluation collector.

Star History Chart

The 0.21 line was a consolidation: it retired legacy keywords behind a sunset-stub resolver ($ralph to $ultragoal, $ultrawork to $team) and removed writable MCP state tools. The popularity is harness-specific: OMX is a Codex CLI layer, and the README itself warns that native Windows and the Codex App are not the default experience and may break, and that third-party “OMX v2” forks are not official.

Strengths
#

  • Turns an individual Codex session into a coordinated team with automatic per-worker git worktrees and incremental merge tracking.
  • A large, named surface of skills and prompts ($plan, $team, $ultragoal, $code-review, $ultraqa) that is independently invocable.
  • Six MCP servers give persistent memory, state, code intelligence, and tracing across sessions.
  • Mixed-provider teams let Codex, Claude, and Gemini workers run side by side in one team.
  • MIT, with a README that is unusually explicit about install pitfalls and unsupported paths.

Cautions
#

  • Primarily tuned for macOS and Linux; native Windows and the Codex App “may break or behave inconsistently” per the README.
  • It is a layer on Codex CLI only, so it inherits Codex’s model, pricing, and platform constraints.
  • Fast-moving with a retirement cadence: $ralph, $ultrawork, and $pipeline were retired in 0.21, so older docs and tutorials drift.
  • npm global installs can collide with a Homebrew-owned codex binary (EEXIST), a documented footgun.
  • The huge star count is not matched by independent field reporting during this run; the community channel is a shared Discord server.

Pricing
#

Free and open source under MIT. No hosted tier and no token markup; Codex API or subscription usage is billed by OpenAI.

Compared to
#

  • Sandcastle: a TypeScript library that sandboxes any CLI agent; choose OMX when you want workflows and team execution on top of Codex specifically.
  • Crewplane: a provider-agnostic Markdown workflow runner; choose OMX for Codex-native skills, hooks, and worktree teams.
  • Plain Codex CLI plus scripts: the zero-dependency option; OMX earns its keep once you want planning skills, memory, and parallel worktree workers.

Bottom line
#

Recommended for Codex CLI users on macOS or Linux who want stronger defaults, reusable skills, persistent memory, and worktree-isolated team execution. Not for Windows-first users, non-Codex harnesses, or anyone who needs a stable, slow-moving interface.

Changes
#

  • 2026-09-27 - Created.
  • 2026-10-02 - Recorded v0.21.7 (October 1) as the new latest release and refreshed star, fork, and version counts.
  • 2026-10-07 - Added the Yeachan-Heo/oh-my-codex star history chart to the Status section.
  • 2026-10-12 - Recorded v0.21.9 (October 12, session token-usage reporting, native subagent completion evidence, and the astra-defaults evaluation collector) as the new latest release.
  • 2026-10-13 - Recorded v0.21.10 and v0.21.11 (both October 13: the TOML merge fix and registry diagnostics, then the fresh provider-inheritance fix in native agent TOMLs) as the new latest release, and refreshed the star count to about 33,526.
  • 2026-10-19 - Recorded v0.21.19 (2026-10-19), npm verified in sync at 148 published versions.
  • 2026-10-20 - Recorded v0.21.25 (2026-10-20, team mailbox isolation hardening) and the v0.21.20 through v0.21.24 patch line, npm at 154 published versions.
  • 2026-10-25 - Recorded v0.21.36 (2026-10-25) as the latest release, npm in sync.
  • 2026-11-01 - Rotation re-verification (every cited URL re-fetched; the npmjs.com package page served a 403 bot wall this run while the registry endpoint stayed live); recorded v0.21.44 (2026-10-31) as the latest release, npm at 173 published versions.
  • 2026-11-07 - Re-verified in rotation: every cited URL re-fetched live (repository, README, npm registry, docs site); the npmjs.com package page now serves a bot wall to plain fetches while the registry endpoint grounds the package facts, and no factual drift otherwise.

See also
#

References
#