oh-my-codex

# oh-my-codex (OMX)

Start Codex stronger, then let OMX add better prompts, workflows, and runtime help when the work grows.

Liked OmX but find it a bit overkill? Try gajae-code.
Keep Codex OAuth with a faster, cheaper, simpler, and more powerful SDK-based path for OpenClaw, Hermes, Grokbot, and other integrations.

**Website:** https://yeachan-heo.github.io/oh-my-codex-website/ **Docs:** [Getting Started](./docs/getting-started.html) · [Agents](./docs/agents.html) · [Skills](./docs/skills.html) · [Integrations](./docs/integrations.html) · [Demo](./DEMO.md) · [OpenClaw guide](./docs/openclaw-integration.md) **Community:** [Discord](https://discord.gg/wSyUQYfhAw) — shared Gajae community server for oh-my-codex, [gajae-code](https://github.com/Yeachan-Heo/gajae-code), and related tooling. ## Official project and package The official/original OMX project is this repository, [`Yeachan-Heo/oh-my-codex`](https://github.com/Yeachan-Heo/oh-my-codex), and the official npm package for this project is [`oh-my-codex`](https://www.npmjs.com/package/oh-my-codex). Install this project with `npm install -g oh-my-codex` (or alongside Codex CLI as shown below). Third-party projects or forks that use names such as “OMX v2” are not official continuations, replacements, or release lines for this repository unless this README or the docs explicitly say so. When in doubt, trust this repository and the `oh-my-codex` package as the official install target. OMX is a workflow layer for [OpenAI Codex CLI](https://github.com/openai/codex). 🚨 CAUTION — RECOMMENDED DEFAULT ONLY: macOS or Linux with Codex CLI.

OMX is primarily designed and actively tuned for that path.
Native Windows and Codex App are not the default experience, may break or behave inconsistently, and currently receive less support. It keeps Codex as the execution engine and makes it easier to: - start a stronger Codex session by default - run one consistent workflow from clarification to completion - invoke the canonical workflow with `$plan`, `$ultragoal`, `$team`, `$code-review`, and `$ultraqa` — each independently, no fixed chain - keep project guidance, plans, logs, and state in `.omx/` ## Core Maintainers | Role | Name | GitHub | | --- | --- | --- | | Creator & Lead | Yeachan Heo | [@Yeachan-Heo](https://github.com/Yeachan-Heo) | | Maintainer | Doyun Ha | [@HaD0Yun](https://github.com/HaD0Yun) | | Maintainer | Valeriy Pavlovich | [@iqdoctor](https://github.com/iqdoctor) | ## Ambassadors | Name | GitHub | | --- | --- | | Sigrid Jin | [@sigridjineth](https://github.com/sigridjineth) | ## Top Collaborators | Name | GitHub | | --- | --- | | Doyun Ha | [@HaD0Yun](https://github.com/HaD0Yun) | | Junho Yeo | [@junhoyeo](https://github.com/junhoyeo) | | JiHongKim98 | [@JiHongKim98](https://github.com/JiHongKim98) | | Lor | [@gobylor](https://github.com/gobylor) | | HyunjunJeon | [@HyunjunJeon](https://github.com/HyunjunJeon) | ## Recommended default flow If you want the default OMX experience, start here: Choose one install path. If Codex CLI is already installed (Homebrew, npm, or another supported method): ```bash codex --version npm install -g oh-my-codex # from the git project you want Codex to edit; choose a task-specific name omx --worktree=feat/task --madmax --xhigh ``` If you do not have Codex CLI yet and want npm to manage it: ```bash npm install -g @openai/codex npm install -g oh-my-codex ``` Do not run a combined `npm install -g @openai/codex oh-my-codex` over an existing Homebrew-owned `codex` binary such as `/opt/homebrew/bin/codex`; npm may fail with `EEXIST` when `@openai/codex` tries to create the same binary. OMX only needs a working, authenticated `codex` command on `PATH`; it does not require Codex to be installed through npm. On a real `oh-my-codex` version bump, the global npm install now prints an explicit reminder instead of launching setup automatically. When you're ready, run the scoped setup command below or use `omx update` to check npm and then run the same setup refresh path. OMX also checks for npm updates at launch on a throttled cadence and prompts before scheduling the update after the current session exits. Set `OMX_AUTO_UPDATE=0` to disable the launch-time check, or set `OMX_AUTO_UPDATE=defer` to schedule the same deferred update without prompting. Choose the setup scope deliberately: - Use `omx setup --scope project --merge-agents` from the git project you want OMX to operate on when that repository should own the durable `AGENTS.md` guidance. - Use `omx setup --scope user` for user-level Codex setup when you are not preparing the current directory as an OMX project. - Avoid running project-scoped setup from a broad home directory or operating hub unless that directory is intentionally the project under review. A home-level `AGENTS.md` often contains global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead. ### Persisting an explicit AGENTS merge policy `omx setup --merge-agents`, `omx setup --no-merge-agents`, and `omx setup --clear-merge-agents-policy` are the only policy selectors; use their bare forms (not `=value` spellings). Repeating an identical selector is harmless, but mixing set and clear choices fails before setup changes anything. An explicit set overrides a saved policy. A successful explicit set records `mergeAgents: true` or `false` in the current working root's `./.omx/setup-scope.json`, even when setup scope is `user`; it never becomes a global user preference or leaks to another root. Later `omx update` replays a valid matching policy for both immediate and deferred refreshes. `true` takes the existing merge branch. `false` only suppresses that branch: it does not promise preservation, replacement, or any new safety mode, so the existing prompt, skip, managed-refresh, plugin-default, and force behavior still applies. A matching-scope review retains the policy while unrelated settings change. Reset or a scope change removes the inherited policy unless the same setup run explicitly sets `true` or `false`; clear always removes the policy and cannot be combined with a set selector. Malformed, unknown, nonboolean, or wrong-scope saved data is ignored safely. `--force` is independent and transient: it is neither recorded nor replayed, and does not override an explicit merge policy. Setup atomically commits explicit set or clear intent only after all setup work succeeds, including when active-session or plugin-symlink safeguards skip the current `AGENTS.md` write, so the next refresh can honor the requested policy. This does not make merge the default or revive the rejected #2892 merge-by-default approach. Older OMX versions safely ignore the field, but may erase it when rewriting their known setup preferences. **Codex plugin install note:** this repo also ships an official Codex plugin layout at `plugins/oh-my-codex` with marketplace metadata in `.agents/plugins/marketplace.json`. That plugin bundles the mirrored skill surface plus plugin-scoped companion metadata for official Codex lifecycle hooks, optional MCP compatibility servers, and apps. It is still **not** a replacement for the global `oh-my-codex` CLI plus scoped setup: plugin-scoped hooks launch the installed `omx` CLI, legacy setup mode installs native agents and prompts, and plugin setup mode relies on plugin discovery for bundled skills while archiving/removing legacy OMX-managed prompts/native-agent TOMLs so stale role files cannot shadow plugin behavior. Plugin mode still needs a persistent scope `AGENTS.md` (`~/.codex/AGENTS.md` for user setup or `./AGENTS.md` for project setup) as the durable orchestration guidance layer; session-scoped AGENTS files only compose that durable guidance with runtime overlays and are not a replacement. Then work normally inside Codex: ```text # Durable objective/checkpoints for a long task: /goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior. $deep-interview "clarify the authentication change" $ralplan "approve the auth plan and review tradeoffs" $ultragoal "turn the approved plan into durable Codex goals" ``` That is the main path. Before you treat the runtime as ready, run the quick-start smoke test below: `omx doctor` verifies the install shape, while `omx exec` proves the active Codex runtime can actually authenticate and complete a model call from the current environment. Start OMX strongly, clarify first when needed, approve the plan, then use `$ultragoal` as the default durable completion wrapper. Use `$team` inside that execution path only when a specific Ultragoal story needs coordinated parallel work; use `$ralph` when you intentionally want a single-owner completion loop instead of a durable multi-goal run. ## What OMX is for Use OMX if you already like Codex and want a better day-to-day runtime around it: - a standard workflow built around `$deep-interview` -> `$ralplan` -> `$ultragoal` - research boundaries: use `$best-practice-research` for ordinary pre-planning official/upstream evidence, `$autoresearch` for bounded validator-gated research artifacts, `$autoresearch-goal` for goal-mode research missions, and feed any research findings into `$ralplan` for architecture synthesis - durable multi-goal handoffs with `$ultragoal` and `.omx/ultragoal` artifacts as the default completion path after planning - specialist roles and supporting skills when the task needs them - project guidance through scoped `AGENTS.md` - durable state under `.omx/` for plans, logs, memory, and mode tracking If you want plain Codex with no extra workflow layer, you probably do not need OMX. ## Quick start ### Requirements - Node.js 20+ - Codex CLI installed, verified with `codex --version`, and authenticated (Homebrew or npm are both fine; do not reinstall `@openai/codex` with npm if Homebrew already owns `codex`) - Codex auth configured and visible in the same shell/profile that will run OMX - `tmux` on macOS/Linux if you want the recommended durable team runtime - `psmux` on native Windows only if you intentionally want the less-supported Windows team path ### A good first session After install, check both boundaries: ```bash omx doctor codex login status omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" ``` `omx doctor` catches missing OMX files, hooks, and runtime prerequisites. The real smoke test catches auth, profile, and provider/base-URL problems that only appear when Codex performs an actual request. Launch OMX the recommended way from a git project: ```bash omx --worktree=feat/task --madmax --xhigh ``` On macOS/Linux interactive terminals with `tmux` available, this starts the leader in OMX-managed detached tmux by default so the HUD/runtime panes can be created and recovered. `--worktree` also moves the launch into a separate git checkout, which is the safer default when using `--madmax`. Replace `feat/task` with a branch-like name for the task. ### Concurrent standard conversations A standard launch owns one writable session pointer under its selected `OMX_ROOT`. A second ordinary `omx` launch from the same checkout therefore fails closed instead of sharing or silently changing that root. Give each additional conversation an explicit, distinct root: ```bash omx OMX_ROOT="$HOME/.omx/instances/second-conversation" omx OMX_ROOT="$HOME/.omx/instances/third-conversation" omx ``` PowerShell: ```powershell $env:OMX_ROOT = "$HOME/.omx/instances/second-conversation" omx ``` Command Prompt: ```bat set "OMX_ROOT=%USERPROFILE%\.omx\instances\second-conversation" omx ``` User-specified roots are literal: launching twice with the same explicit `OMX_ROOT` remains a fatal owner conf