oh-my-codex

OmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.

32,631 stars TypeScript Markdown Skills API Spec
AI Prompts & Specs

Repository: Yeachan-Heo/oh-my-codex


Stars: 23761

README.md

oh-my-codex (OMX)

<p align="center">
<img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
<br>
<em>Start Codex stronger, then let OMX add better prompts, workflows, and runtime help when the work grows.</em>
</p>

![npm version](https://www.npmjs.com/package/oh-my-codex)
![License: MIT](https://opensource.org/licenses/MIT)
![Node.js](https://nodejs.org)
![Discord](https://discord.gg/PUwSMR9XNk)

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.

<table>
<tr>
<td><strong>🚨 CAUTION — RECOMMENDED DEFAULT ONLY: macOS or Linux with Codex CLI.</strong><br><br><strong>OMX is primarily designed and actively tuned for that path.</strong><br><strong>Native Windows and Codex App are not the default experience, may break or behave inconsistently, and currently receive less support.</strong></td>
</tr>
</table>

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 |

If you want the default OMX experience, start here:

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

Then work normally inside Codex:

text
$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:

bash
omx --madmax --high

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

bash
omx --tmux --madmax --high

Then try the canonical workflow:

text
$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

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.

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

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

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

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

![Star History Chart](https://www.star-history.com/#Yeachan-Heo/oh-my-codex&type=date&legend=top-left)

License

MIT