oh-my-codex (OMX)
Website: https://yeachan-heo.github.io/oh-my-codex-website/
Docs: Getting Started · Agents · Skills · Integrations · Demo · OpenClaw guide
Community: Discord — shared Gajae community server for oh-my-codex, gajae-code, and related tooling.
Official project and package
The official/original OMX project is this repository, Yeachan-Heo/oh-my-codex, and the official npm package for this project is 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.
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
Ambassadors
Top Collaborators
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):
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:
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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
