oh-my-codex (OMX)

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

Website: https://yeachan-heo.github.io/oh-my-codex-website/

Docs: Getting Started · Agents · Skills · Integrations · Demo · OpenClaw guide

Community: Discord — shared OMX/community server for oh-my-codex 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.

🚨 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 default workflow with $deep-interview, $ralplan, and $ultragoal - keep project guidance, plans, logs, and state in .omx/

Core Maintainers

Role	Name	GitHub
Creator & Lead	Yeachan Heo	@Yeachan-Heo
Maintainer	Doyun Ha	@HaD0Yun
Maintainer	Valeriy Pavlovich	@iqdoctor

Ambassadors

Name	GitHub
Sigrid Jin	@sigridjineth

Top Collaborators

Name	GitHub
Doyun Ha	@HaD0Yun
Junho Yeo	@junhoyeo
JiHongKim98	@JiHongKim98
Lor	@gobylor
HyunjunJeon	@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):

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.

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:

# 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"
$prometheus-strict "stress-test the plan before durable execution"
$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, optionally use $prometheus-strict for interview-driven plan hardening on high-risk work, 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, with $prometheus-strict available when plans need stricter interview/critique/synthesis before execution and optional .omx/plans/prometheus-strict/ artifacts - 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:

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:

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.

Madmax and worktree launch safety

--madmax is OMX shorthand for Codex --dangerously-bypass-approvals-and-sandbox. It removes the normal approval and sandbox guardrails, so only use it in trusted repositories and environments. --high and --xhigh are shorthand for -c model_reasoning_effort="high|xhigh"; a normal strong session is omx --madmax --xhigh (or omx --worktree=feat/task --madmax --xhigh from a git project).

When you use --madmax from a git repository, prefer a worktree launch instead of running directly in the current checkout. For repeatable or concurrent work, use a named worktree:

omx --worktree=feature/auth --madmax --xhigh

If you are outside a git repository, omit --worktree; worktree launches require Git.

For concurrent --madmax sessions, do not run them all in the same directory. Give each session its own named worktree:

omx --worktree=feature/auth --madmax --xhigh
omx --worktree=fix/flaky-tests --madmax --xhigh

--worktree / -w with no name creates or reuses a detached launch worktree at ../<repo>.omx-worktrees/launch-detached. --worktree=<name>, --worktree <name>, or -w <name> creates or reuses a named launch worktree under ../<repo>.omx-worktrees/ and checks out that branch name. OMX consumes the worktree flag before starting Codex; it is not forwarded to Codex itself. Treat the unnamed detached form as a one-off convenience: if the source checkout advances after that worktree is created, a later unnamed launch can fail with worktree_target_mismatch because launch-detached still points at the old HEAD. Use a named worktree for repeated work, or remove the old detached worktree before retrying. If the target launch worktree is already dirty, OMX warns and launches as-is, so clean, commit, or stash that worktree before relying on it for isolation.

For omx team, workers already use dedicated worktrees automatically by default; --worktree on omx team is only a legacy-compatible override.

If you want a one-off launch with no OMX tmux/HUD management, use --direct:

omx --direct --yolo

For a persistent shell/profile preference, set an environment policy:

OMX_LAUNCH_POLICY=direct omx --yolo

Return to the auto/default behavior with:

unset OMX_LAUNCH_POLICY

CLI policy flags win over the environment, and the last CLI policy flag before -- wins:

OMX_LAUNCH_POLICY=direct omx --tmux --yolo

Use OMX_LAUNCH_POLICY=direct|tmux|detached-tmux|auto. This iteration only adds CLI and environment controls; it intentionally does not add a config-file setting. If you run --direct from inside an existing tmux pane, OMX will not create HUD splits, enable mouse mode, or wrap extended-key handling, but the process still runs inside that already-open terminal pane.

Then try the canonical workflow:

# Copy/pasteable durable-goal example:
/goal Ship the checkout bug fix with a durable objective, checkpoints for reproduction, implementation, regression tests, and final verification.

$ralplan "approve the checkout bug-fix plan and review tradeoffs"
$ultrawork "execute the approved checkout fix with checkpoint evidence"

Use $team when an active Ultragoal story needs coordinated parallel work, or $ralph when one persistent owner should keep pushing to completion without a multi-goal ledger.

/goal and skill selection

Start a normal strong session with omx --madmax --xhigh (or add --worktree=<task> in a git repo). Inside that session, pick the execution spine that matches the work: $autopilot for the full supervised planning-to-execution loop, $ultrawork when you want durable checkpointed execution, or $ralph when one persistent owner should keep pushing to completion. Use /goal when the task itself needs a durable objective/checkpoint structure that Codex should keep reconciling across turns.

Add only 2-5 relevant skills by default. More skills are allowed when the task scope justifies them, but loading a large catalog is usually a context-budget and attention-qual