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.

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

Core Maintainers

Role	Name	GitHub
Creator & Lead	Yeachan Heo	@Yeachan-Heo
Maintainer	HaD0Yun	@HaD0Yun

Ambassadors

Name	GitHub
Sigrid Jin	@sigridjineth

Top Collaborators

Name	GitHub
HaD0Yun	@HaD0Yun
Junho Yeo	@junhoyeo
JiHongKim98	@JiHongKim98
Lor	—
HyunjunJeon	@HyunjunJeon

Recommended default flow

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. Start OMX strongly, clarify first when needed, approve the plan, then choose $team for coordinated parallel execution or $ralph for the persistent completion loop.

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, $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.

Quick start

Requirements

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

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.

A simple mental model

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.

Start here if you are new

1. Run omx setup
2. Launch with omx --madmax --high
3. Use $deep-interview "..." when the request or boundaries are still unclear
4. Use $ralplan "..." to approve the plan and review tradeoffs
5. Choose $team for coordinated parallel execution or $ralph for persistent completion loops

Recommended workflow

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.

Common in-session surfaces

Surface	Use it for
$deep-interview "..."	clarifying intent, boundaries, and non-goals
$ralplan "..."	approving the implementation plan and tradeoffs
$ralph "..."	persistent completion and verification loops
$team "..."	coordinated parallel execution when the work is big enough
/skills	browsing installed skills and supporting helpers

Advanced / operator surfaces

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

Team runtime

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>

Setup, doctor, and HUD

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
• 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.

Explore and sparkshell

• 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

Wiki

• 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

Platform notes for team mode

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.

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

Known issues

Intel Mac: high syspolicyd / trustd CPU during startup

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)

Documentation

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

Languages

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

Contributors

Role	Name	GitHub
Creator & Lead	Yeachan Heo	@Yeachan-Heo
Maintainer	HaD0Yun	@HaD0Yun

Star History

License

MIT