Yeachan-Heo/oh-my-codex

oh‑my‑codex (OMX) – a workflow layer for OpenAI Codex

What it is – OMX is a thin CLI wrapper that sits on top of the official OpenAI Codex command‑line tool. It does not replace Codex’s code‑generation engine; instead it adds a structured, opinionated workflow, persistent project state, and a set of reusable “skills” (commands) that make day‑to‑day prompting more repeatable.

Why it exists – Many developers who use Codex report that they have to repeat the same sequence of steps: clarify the task, get a plan, approve it, then run the plan. OMX codifies that pattern as $deep‑interview → $ralplan → $ultragoal (with optional stricter variants) and stores the intermediate artefacts in a hidden .omx/ folder. This gives you:

• a single entry point (omx) that launches a Codex session with the right model settings (high‑effort reasoning, optional “madmax” bypass of sandbox checks),
• project‑scoped guidance via an AGENTS.md file that can be merged or kept separate,
• persistent logs, plans and checkpoints so you can resume or audit a long‑running refactor,
• tmux‑based UI on macOS/Linux that splits the terminal into a HUD and a Codex pane, making multi‑pane interaction smoother.

How you get it

# If you already have the Codex CLI (Homebrew, npm, etc.)
npm install -g oh‑my‑codex
# otherwise install Codex first
npm install -g @openai/codex
npm install -g oh‑my‑codex

After installation run the one‑time setup:

omx setup --scope project --merge-agents   # inside the repo you want OMX to manage
# or
omx setup --scope user                     # for a global user‑level setup

Then verify everything works:

omx doctor                     # checks dependencies and runtime files
omx exec -C . "Reply with exactly OMX‑EXEC‑OK"   # smoke‑test a real Codex call

Typical workflow

1. Start a session (preferably in a git worktree for isolation):

   omx --worktree=feat/task --madmax --xhigh
   

2. Clarify – $deep‑interview "…" – ask Codex to ask follow‑up questions and refine the problem statement.
3. Plan – $ralplan "…" – get a concrete architecture/implementation plan and approve it.
4. Execute – one of the execution spines:
   • $ultragoal / $ultrawork – durable, checkpointed execution with a ledger in .omx/ultragoal.
   • $autopilot – full supervised loop from interview to execution.
   • $ralph – single‑owner loop for simpler tasks.
   • $prometheus‑strict – adds an extra critique step for high‑risk changes.
5. Optional research – $best‑practice‑research, $autoresearch, $autoresearch‑goal to pull in external evidence before planning.

Key concepts & commands

Concept	Meaning	Typical command
Worktree	Isolated git checkout used as the runtime root.	omx --worktree=feature/auth …
MADMAX	Shortcut for --dangerously-bypass-approvals-and-sandbox; disables Codex’s safety guards (use only in trusted repos).
Model effort	--high / --xhigh set model_reasoning_effort to request more compute from Codex.
AGENTS.md	Durable guidance file (global or project‑scoped) that defines roles, safety rules, and routing.
.omx/	Directory where plans, logs, memory snapshots and ledger files live.
Skills	Built‑in command shortcuts ($deep‑interview, $ralplan, $ultragoal, etc.) that invoke specific Codex prompts.
Team mode	omx team launches a tmux‑managed multi‑pane session for parallel work.
Direct mode	omx --direct runs Codex without tmux UI, useful inside existing terminals.

Who it’s for

• Developers already comfortable with the OpenAI Codex CLI who want a repeatable, stateful workflow.
• Teams that need project‑level guidance (via AGENTS.md) and want to keep a log of plans and execution checkpoints.
• Users on macOS/Linux (the default, fully‑supported path). Windows support exists but is less stable.

Limitations / cautions

• Primarily tuned for macOS/Linux; Windows may break or behave inconsistently.
• The “madmax” flag disables safety checks – only use it on trusted codebases.
• OMX relies on a working, authenticated codex binary; it does not manage authentication itself.
• Updates are checked at launch; you can disable or defer them with OMX_AUTO_UPDATE.

Project health

• Published on npm (oh‑my‑codex), version badge indicates active releases.
• Maintained by the original author (Yeachan Heo) plus a small team of contributors.
• Documentation is extensive (getting‑started, agents, skills, integrations) and a Discord community is provided for support.

Bottom line – If you already use Codex and find yourself manually orchestrating prompts, OMX gives you a ready‑made, scriptable workflow, persistent state, and a richer terminal UI, turning ad‑hoc prompt engineering into a repeatable development process.