oh-my-codex

v0.12.3

Published

21 hours ago

Multi-agent orchestration layer for OpenAI Codex CLI

0High
0Medium
0Low

bellman_04

codex openai cli agents orchestration multi-agent

oh-my-codex (OMX)

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/

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 later want the durable team runtime
psmux on native Windows if you later want Windows team mode

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

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

Recommended workflow

$deep-interview — clarify scope when the request or boundaries are still vague.
$ralplan — turn that clarified scope into an approved architecture and implementation plan.
$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
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

Examples:

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

Platform notes for team mode

omx team needs a tmux-compatible backend:

| 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

Languages

Contributors