# oh-my-codex (OMX): features, protocols, quickstart

## 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

| Field | Value |
| --- | --- |
| 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](https://github.com/Yeachan-Heo/oh-my-codex) |
| Website | [oh-my-codex.dev](https://oh-my-codex.dev) |
| Documentation | [github.com](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md) |
| Last verified | 2026-09-30 |

## Key features

- A default workflow of `$deep-interview`, `$ralplan` and `$ultragoal`, with `$autopilot` as the orchestrator that chains them; each stage can also be invoked on its own. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- `omx team` starts a durable tmux runtime with several workers (for example `omx team 3:executor "..."`), with status, resume and shutdown subcommands; workers get dedicated git worktrees by default. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- `omx --worktree=<name>` launches Codex in a named git worktree, and separate `OMX_ROOT` values allow several concurrent conversations from one checkout. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- Durable state under `.omx/` for plans, logs, memory, mission ledgers and Ultragoal checkpoints, plus scoped `AGENTS.md` guidance installed by `omx setup`. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- A Codex plugin layout at `plugins/oh-my-codex` with marketplace metadata, registering official Codex lifecycle hooks that call the installed `omx` CLI. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- Optional first-party MCP servers (state, memory, code-intel, trace and others) shipped disabled by default in the plugin manifest. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/plugins/oh-my-codex/.mcp.json))
- A documented Team coordination protocol covering acknowledgements, claim-safe task lifecycle, blocked-lane reporting and leader-owned Ultragoal state. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/team-coordination-protocol.md))
- `omx hud --watch` shows a live row per team agent with state, task, role and tmux pane, and `omx doctor` checks the install. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))

## 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](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- Hermes ([evidence](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/hermes-mcp-bridge.md))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/hermes-mcp-bridge.md) | 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 (checked 2026-09-30) | — | 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 (checked 2026-09-30) | — | 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](https://multiagentguide.top/best/coding-agents.md))
- Running several Codex workers in parallel tmux panes, each in its own git worktree, under one leader. ([shortlist](https://multiagentguide.top/best/parallel-coding-agents.md))
- 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](https://multiagentguide.top/best/coding-agents.md))

## 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

```sh
npm install -g oh-my-codex
```

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i oh-my-codex` (no -g) ok, `npx --no-install omx --version` ok, oh-my-codex 0.21.6. The official command uses `-g`; the same package was installed locally. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```bash
# 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-codex` together over a Homebrew-owned `codex`; npm can fail with EEXIST.
- A green `omx doctor` does not prove Codex can authenticate; run `codex login status` and the `omx exec` smoke test from the same shell.
- A second plain `omx` launch from the same checkout fails closed; give each conversation its own `OMX_ROOT` or a named worktree.
- `--madmax` removes 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.

Official quickstart: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md#quick-start

## 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](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/contracts/team-runtime-state-contract.md))
- Worktree launches and per-worker worktrees are documented, including the concurrency limits and the fail-closed behaviour for a second launch. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- CLI and JSON are documented as the canonical control plane, so scripts and recovery do not depend on MCP transport working. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/architecture/cli-first-mcp-taxonomy.md))
- Setup includes a doctor command and an explicit real-execution smoke test, with a troubleshooting section for false-green readiness. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- MIT licensed with tagged releases every few days to weeks and a published release protocol. ([source](https://github.com/Yeachan-Heo/oh-my-codex/releases))

## Cons

- Codex CLI only: OMX is a workflow layer for Codex and does not drive other coding agents. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- 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](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- The recommended launch uses --madmax, shorthand for Codex's bypass of approvals and sandbox. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- The README itself points users who find OMX overkill to a separate, simpler project, gajae-code. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))
- Known issue on some Intel Macs: high syspolicyd and trustd CPU during startup, especially with --madmax --high. ([source](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md))

## Alternatives

- [Oh My OpenAgent (OmO)](https://multiagentguide.top/tools/oh-my-openagent.md)
- [Codex CLI](https://multiagentguide.top/tools/codex.md)
- [Superpowers](https://multiagentguide.top/tools/superpowers.md)
- [ECC](https://multiagentguide.top/tools/ecc.md)
- [Ruflo](https://multiagentguide.top/tools/ruflo.md)

## 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.

## Sources

- [oh-my-codex README](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md)
- [oh-my-codex plugin MCP manifest](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/plugins/oh-my-codex/.mcp.json)
- [Team coordination protocol](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/team-coordination-protocol.md)
- [Team runtime state contract](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/contracts/team-runtime-state-contract.md)
- [CLI-first MCP taxonomy](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/architecture/cli-first-mcp-taxonomy.md)
- [oh-my-codex releases](https://github.com/Yeachan-Heo/oh-my-codex/releases)
- [Hermes MCP bridge](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/hermes-mcp-bridge.md)
- [oh-my-codex README, quick start](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/README.md#quick-start)
- [oh-my-codex website](https://oh-my-codex.dev)
- [Yeachan-Heo/oh-my-codex GitHub repository](https://github.com/Yeachan-Heo/oh-my-codex)
- [oh-my-openagent README (Author's Note)](https://github.com/code-yeongyu/oh-my-openagent/blob/dev/README.md)

## Unknown fields

protocols.a2a: no mention in the README; code search hits (a release-readiness note and a capabilities lock file) were not read as protocol support. protocols.agui: no mention found. OpenClaw: docs describe an OpenClaw notification gateway integration, which is not a plugin or install target, so OpenClaw is not listed under harnesses.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/oh-my-codex