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.

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 skills with $deep-interview, $ralplan, $team, and $ralph
• keep project guidance, plans, logs, and state in .omx/

If you want the default OMX experience, start here:

npm install -g @openai/codex oh-my-codex
omx setup
omx --madmax --high

Then work normally inside Codex:

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"

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 choose $team for coordinated parallel execution or $ralph for the persistent completion loop.

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, $team, and $ralph
• 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.

• Node.js 20+
• Codex CLI installed: npm install -g @openai/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

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:

omx --madmax --high

This starts the interactive leader session directly by default. If you explicitly want the leader session in tmux, use:

omx --tmux --madmax --high

Then try the canonical workflow:

$deep-interview "clarify the authentication change"
$ralplan "approve the safest implementation path"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"

Use $team when the approved plan needs coordinated parallel work, or $ralph when one persistent owner should keep pushing to completion.

OMX does not replace Codex.

It adds a better working layer around it:

• Codex does the actual agent work
• OMX role keywords make useful roles reusable
• OMX skills make common workflows reusable
• .omx/ stores plans, logs, memory, and runtime state

Most users should think of OMX as better task routing + better workflow + better runtime, not as a command surface to operate manually all day.

1. Run omx setup
2. Run omx doctor
3. Run a real execution smoke test: codex login status and omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
4. Launch with omx --madmax --high
5. Use $deep-interview "..." when the request or boundaries are still unclear
6. Use $ralplan "..." to approve the plan and review tradeoffs
7. Choose $team for coordinated parallel execution or $ralph for persistent completion loops

1. $deep-interview — clarify scope when the request or boundaries are still vague.
2. $ralplan — turn that clarified scope into an approved architecture and implementation plan.
3. $team or $ralph — use $team for coordinated parallel execution, or $ralph when you want a persistent completion loop with one owner.

These are useful, but they are not the main onboarding path.

Use the team runtime when you specifically need durable tmux/worktree coordination, not as the default way to begin using OMX.

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:

• omx setup installs prompts, skills, AGENTS scaffolding, .codex/config.toml, and OMX-managed native Codex hooks in .codex/hooks.json
  • setup refresh preserves non-OMX hook entries in .codex/hooks.json and only rewrites OMX-managed wrappers
  • omx uninstall removes OMX-managed wrappers from .codex/hooks.json but keeps the file when user hooks remain
• omx doctor verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model call
• omx hud --watch is a monitoring/status surface, not the primary user workflow

For non-team sessions, native Codex hooks are now the canonical lifecycle surface:

• .codex/hooks.json = native Codex hook registrations
• .omx/hooks/*.mjs = OMX plugin hooks
• omx tmux-hook / notify-hook / derived watcher = tmux + runtime fallback paths

See 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:

• Run 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.
• In custom HOME, profile, container, or service shells, confirm the active ~/.codex (or CODEX_HOME) is the one with the expected auth and config. Do not assume your normal user ~/.codex is visible there.
• If you depend on a local OpenAI-compatible proxy, confirm the active ~/.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.
• If 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 explore --prompt "..." is for read-only repository lookup
• omx sparkshell <command> is for shell-native inspection and bounded verification
• when .omx/wiki/ exists, omx explore can inject wiki-first context before falling back to broader repository search

Examples:

omx explore --prompt "find where team state is written"
omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

• omx wiki is the CLI parity surface for the OMX wiki MCP server
• wiki data lives locally under .omx/wiki/
• the wiki is markdown-first and search-first, not vector-first

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.

On 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)
• adding your terminal app to the Developer Tools allowlist in macOS Security settings
• using lower concurrency (for example, avoid --madmax --high)

• Getting Started
• Demo guide
• Wiki feature
• Agent catalog
• Skills reference
• Codex native hook mapping
• Integrations
• Troubleshooting execution readiness
• OpenClaw / notification gateway guide
• Contributing
• Changelog

• English
• 한국어
• 日本語
• 简体中文
• 繁體中文
• Tiếng Việt
• Español
• Português
• Русский
• Türkçe
• Deutsch
• Français
• Italiano
• Ελληνικά
• Polski
• Українська

MIT