yeachan-heo/ oh-my-codex
View on GitHubOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.
OmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.
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.
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:
$plan, $ultragoal, $team, $code-review, and $ultraqa — each independently, no fixed chain.omx/| Role | Name | GitHub | | --- | --- | --- | | Creator & Lead | Yeachan Heo | @Yeachan-Heo | | Maintainer | Doyun Ha | @HaD0Yun | | Maintainer | Valeriy Pavlovich | @iqdoctor |
| Name | GitHub | | --- | --- | | Sigrid Jin | @sigridjineth |
| Name | GitHub | | --- | --- | | Doyun Ha | @HaD0Yun | | Junho Yeo | @junhoyeo | | JiHongKim98 | @JiHongKim98 | | Lor | @gobylor | | HyunjunJeon | @HyunjunJeon |
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:
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.omx setup --scope user for user-level Codex setup when you are not preparing the current directory as an OMX project.AGENTS.md often contains global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead.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:
# 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.
Use OMX if you already like Codex and want a better day-to-day runtime around it:
$deep-interview -> $ralplan -> $ultragoal$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$ultragoal and .omx/ultragoal artifacts as the default completion path after planningAGENTS.md.omx/ for plans, logs, memory, and mode trackingIf you want plain Codex with no extra workflow layer, you probably do not need OMX.
codex --version, and authenticated (Homebrew or npm are both fine; do not reinstall @openai/codex with npm if Homebrew already owns codex)tmux on macOS/Linux if you want the recommended durable team runtimepsmux on native Windows only if you intentionally want the less-supported Windows team pathAfter 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.
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:
omx
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx
OMX_ROOT="$HOME/.omx/instances/third-conversation" omx
PowerShell:
$env:OMX_ROOT = "$HOME/.omx/instances/second-conversation"
omx
Command Prompt:
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 conflict. Separate checkouts have separate default roots, while --worktree and --madmax keep their existing isolation behavior.
--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.
Repo-aware tools receive the same canonical context in launch, team-worker, and autoresearch runtimes: OMX_REPO_ROOT, OMX_WORKTREE_ROOT, OMX_GIT_COMMON_DIR, OMX_WORKTREE_SCOPE, OMX_CODEGRAPH_MODE, and OMX_CODEGRAPH_PROJECT_PATH. OMX_CODEGRAPH_MODE=auto prefers a worktree-local .codegraph/codegraph.db, then a leader/repo .codegraph/codegraph.db, otherwise resolves to off. Explicit shared, local, and off are honored. OMX does not install CodeGraph, auto-index worktrees, or copy/symlink .codegraph; shared leader indexes are useful for baseline navigation but are not branch-accurate for worktree-only changes.
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.
$plan "approve the checkout bug-fix plan and review tradeoffs"
$ultragoal "execute the approved checkout fix with checkpoint evidence"
Use $team when an active Ultragoal story needs coordinated parallel work.
/goal and skill selectionStart a normal strong session with omx --madmax --xhigh (or add --worktree=<task> in a git repo). Inside that session, execute directly or use $ultragoal for durable multi-goal runs, $team for coordinated parallel work, or $plan when the task needs explicit planning first. 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-quality problem, not a hard parser/runtime blocker. Treat it as a concrete runtime blocker only when a command actually errors.
Anti-pattern:
omx --madmax --xhigh
# Then immediately load 20 skills "just in case" before stating the task.
# This bloats session context and makes the model spend attention on irrelevant workflows.
OMX does not replace Codex.
It adds a better working layer around it:
.omx/ stores plans, logs, memory, and runtime stateMost users should think of OMX as better task routing + better workflow + better runtime, not as a command surface to operate manually all day.
codex --version and install or update OMX with npm install -g oh-my-codex; otherwise install @openai/codex separately first if you want npm to manage Codexomx setup --scope project --merge-agents from the target git project or omx setup --scope user for user-level Codex setup, or use omx update when you also want npm to check for and install the latest build before refreshing setupomx doctorcodex login status and omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"omx --worktree=feat/task --madmax --xhigh; if you run concurrent --madmax sessions, use distinct named worktrees such as --worktree=feature/auth$deep-interview "..." when the request or boundaries are still unclear$ralplan "..." to approve the plan and review tradeoffs$ultragoal or $team when the task needs durable or parallel execution; add /goal when durable objective/checkpoint structure should be explicit$autopilot is the first-class canonical orchestrator for the staged workflow $deep-interview -> $ralplan -> $ultragoal. The chain is its defining default, while each stage remains independently invocable when earlier input contracts are already satisfied.
$deep-interview — iterative Socratic ambiguity clearance, resumable state, and execution-ready requirements artifacts.$ralplan — architecture, feasibility, and consensus planning over the deep-interview artifact.$ultragoal — durable multi-goal execution with .omx/ultragoal ledger checkpoints.$team — coordinated parallel execution when a story benefits from multiple lanes.$deep-interview is an independent requirements stage, not an alias for $plan --interview, and never implements directly. Planning skills stop at planning artifacts; code changes require an explicit execution lane ($ultragoal or $team).
Inside an Ultragoal story, use $team only when that story benefits from coordinated parallel execution.
| Surface | Use it for |
| --- | --- |
| $plan "..." | optional planning and clarification (--interview mode) |
| $ultragoal "..." | durable multi-goal completion after the approved plan |
| $team "..." | coordinated parallel execution when the work is big enough |
| /skills | browsing installed skills and supporting helpers |
| /goal ... | durable objective/checkpoint structure for tasks that must reconcile progress across turns |
| omx mission <file> | sequential prompt/checklist batch runs through omx exec, with .omx/missions/<slug>/summary.json and ledger.jsonl operator artifacts |
These are useful, but they are not the main onboarding path.
Use omx mission when you have a short checklist of OmX/Codex prompts that should run one after another instead of opening a separate shell command for each prompt. Start with omx mission plan ./mission.md or omx mission ./mission.md --dry-run to validate parsing and inspect the durable summary, then run omx mission run ./mission.md -- --model gpt-5 when the prompts are ready. Interrupted runs can be inspected with omx mission status ./mission.md, continued with omx mission resume ./mission.md, operator-blocked with omx mission mark ./mission.md --task task-002 --status blocked, and repaired task-by-task with omx mission rerun ./mission.md --task task-002. See docs/mission.md for input format, status output, and artifact details.
Use the team runtime when you specifically need durable tmux/worktree coordination, not as the default way to begin using OMX. In Codex App or plain outside-tmux sessions, treat omx team as a tmux-runtime shell surface rather than a directly available in-app workflow; launch OMX CLI from shell first if you actually want team execution.
When Team runs inside an Ultragoal story, Ultragoal remains leader-owned state: workers report checkpoint-ready evidence upward instead of mutating .omx/ultragoal directly. Team startup tolerates stale or malformed Ultragoal artifacts for unrelated work, but explicitly Ultragoal-linked Team launches stay fail-closed. Team startup also writes .omx/state/team/<team-name>/preflight-context.json so large Team runs can be resumed after compaction with the original task, worker split, Ultragoal context, and verification checklist.
For very small atomic work, Team may cap implicit fanout to one worker and print an over-orchestration warning; pass an explicit worker count only when the extra coordination cost is intentional.
omx team 3:executor "fix the failing tests with verification"
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>
These are operator/support surfaces:
${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/ (local installs may use local as the version identifier); that packaged plugin includes plugin-scoped companion metadata for official Codex lifecycle hooks, optional MCP compatibility servers, and apps (MCP/apps disabled by default), so it is still paired with the installed omx CLI for runtime execution.codex/config.toml, and (for legacy installs or older Codex without plugin_hooks) OMX-managed native Codex hooks in .codex/hooks.json
.codex/hooks.json and only rewrites OMX-managed wrappersAGENTS.md as persistent durable guidance even though bundled skills/hooks come from the plugin cache; omx doctor treats a missing persistent scope AGENTS.md in plugin mode as a failed check because the session-scoped AGENTS file would otherwise contain only runtime overlay guidanceomx setup --merge-agents preserves existing project AGENTS.md guidance while inserting or refreshing generated OMX sections between <!-- OMX:AGENTS:START --> / <!-- OMX:AGENTS:END -->; --no-merge-agents records an explicit contextual non-merge choice, and --clear-merge-agents-policy always removes the recorded choice and cannot combine with a set selector. The policy is stored per working root (even for user scope), replayed by immediate and deferred updates only when its saved scope is valid and matches, and is never a force/default policy.omx uninstall removes OMX-managed wrappers from .codex/hooks.json but keeps the file when user hooks remainomx update checks npm immediately, installs the newest global OMX build, then reruns the same interactive setup refresh pathOMX_AUTO_UPDATE=0 to disable them or OMX_AUTO_UPDATE=defer to schedule deferred updates without a promptgpt-5.6-sol config seeding now recommends model_context_window = 250000 and model_auto_compact_token_limit = 200000, but only when those keys are missing.omx-config.json model/env routing is documented in the model/env routing reference; only edit keys supported by your installed OMX versionomx doctor verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model callomx hud --watch is a monitoring/status surface, not the primary user workflow"guardex": { "enabled": true } to the project-local .omx/hud-config.json to show gx:<step>/<total> <phase>; running review/autofix phases animate in the HUD. OMX does not read Guardex state when this flag is absent or false.For non-team sessions, native Codex hooks are now the canonical lifecycle surface:
plugins/oh-my-codex/hooks/hooks.json = official plugin-scoped hook registrations for plugin installs.codex/hooks.json = legacy/fallback native Codex hook registrations preserved for legacy installs and older Codex versions.omx/hooks/*.mjs = OMX plugin hooksomx tmux-hook / notify-hook / derived watcher = tmux + runtime fallback pathsSee Codex native hook mapping for the current native / fallback matrix.
A green omx doctor means the install and local runtime wiring look sane. If real execution still fails, check the environment Codex actually uses:
codex login status and omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" from the same shell/profile that will launch OMX.~/.codex (or CODEX_HOME) is the one with the expected auth and config. Do not assume your normal user ~/.codex is visible there.~/.codex/config.toml includes the expected openai_base_url; otherwise a proxy-issued key can be sent to the default endpoint and fail with 401 Unauthorized, Missing bearer or basic authentication in header, or Incorrect API key provided.omx doctor --team or resume reports a stale team such as resume_blocker or a missing tmux session, clean the dead runtime state before retrying:omx team shutdown <team-name> --force --confirm-issues
omx cancel
omx doctor --team
Only use the forced team shutdown for a team you have confirmed is dead or intentionally abandoned.
If Shift+Enter still submits instead of inserting a newline inside an OMX-managed tmux session, see Troubleshooting execution readiness. Current OMX already enables tmux extended-key forwarding around its own Codex launch paths, so a persistent failure is usually a tmux terminal-capability/discoverability problem rather than a net-new OMX feature gap.
omx sparkshell <command> is for shell-native inspection and bounded verificationomx explore command has been removed)OMX_SPARKSHELL_BIN selects a native sidecar path, OMX_SPARKSHELL_MODEL selects the primary summary model, OMX_SPARKSHELL_FALLBACK_MODEL selects the retry model, OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE selects summary instructions, and OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS controls the local API summary timeoutExamples:
omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400
omx wiki is the CLI-first JSON surface for wiki operations; omx_wiki MCP is explicit compatibility onlyomx_wiki/Examples:
omx wiki list --json
omx wiki query --input '{"query":"session-start lifecycle"}' --json
omx wiki lint --json
omx wiki refresh --json
omx team works best on macOS/Linux with tmux.
Native Windows remains a secondary path, and WSL2 is generally the better choice if you want a Windows-hosted setup.
On native Windows, OMX accepts psmux as the tmux-compatible binary for the existing tmux-backed paths it already uses.
| Platform | Install |
| --- | --- |
| macOS | brew install tmux |
| Ubuntu/Debian | sudo apt install tmux |
| Fedora | sudo dnf install tmux |
| Arch | sudo pacman -S tmux |
| Windows | winget install psmux |
| Windows (WSL2) | sudo apt install tmux |
syspolicyd / trustd CPU during startupOn some Intel Macs, OMX startup — especially with --madmax --high — can spike syspolicyd / trustd CPU usage while macOS Gatekeeper validates many concurrent process launches.
If this happens, try:
xattr -dr com.apple.quarantine $(which omx)--madmax --high)| Role | Name | GitHub | | --- | --- | --- | | Creator & Lead | Yeachan Heo | @Yeachan-Heo | | Maintainer | Doyun Ha | @HaD0Yun | | Maintainer | Valeriy Pavlovich | @iqdoctor |
MIT
OmX includes a geobench product spec for measuring LLM hit rate, MRR, share of voice, and citations.
geobench/oh-my-codex.yamldocs/geobench.md
No comments yet. Set the tone — say what you would want to know.