Oh My Codex, or OMX, is a workflow layer around the OpenAI Codex CLI. Codex stays the execution engine; OMX adds reusable role keywords, skills, a stronger default session, and durable state under .omx/ for plans, logs, memory, and mode tracking. Project guidance lives in a scoped AGENTS.md that setup can either own or merge into between marker comments.
The canonical staged workflow is $deep-interview for Socratic requirements clearance, $ralplan for architecture and feasibility planning over that artifact, and $ultragoal for durable multi-goal execution with ledger checkpoints; $autopilot chains them. Each stage is also invocable on its own once its input contract is satisfied, and planning skills stop at planning artifacts, so code changes need an explicit execution lane. $team adds coordinated parallel execution and $ralph a single-owner completion loop.
Team runs are worktree-first: every worker gets its own git worktree and detached branch while the leader workspace stays clean, and the leader integrates worker commits by merge, cherry-pick, or cross-worker rebase, reporting conflicts in an integration report. Startup writes a preflight context file so a large run can resume after compaction with its original task, worker split, and verification checklist.
Operator surfaces sit beside the main path: omx mission runs a checklist of prompts sequentially through omx exec with durable summary and ledger artifacts, omx doctor checks install shape and prerequisites, omx hud --watch reports status, omx sparkshell runs bounded shell inspection, and omx wiki keeps repository knowledge as markdown. Native Codex lifecycle hooks are the canonical hook surface, with .codex/hooks.json kept for legacy installs and older Codex versions.
Requirements are Node.js 20 or newer, an installed and authenticated Codex CLI, and tmux on macOS or Linux for the durable team runtime. macOS and Linux with Codex CLI is the tuned path; native Windows and the Codex App are documented as inconsistent and less supported. --madmax is shorthand for the Codex flag that bypasses approvals and the sandbox, so the documentation pairs it with a named worktree launch.
Features
- Staged workflow: $deep-interview to $ralplan to $ultragoal, chained by $autopilot or invoked stage by stage
- Worktree-first teams: each worker runs in its own git worktree with incremental merge tracking and early conflict reporting
- Durable goals: /goal objectives and .omx/ultragoal ledger checkpoints survive across turns and compaction
- Mission runner: sequential prompt batches with plan, dry-run, status, resume, mark, and per-task rerun commands
- Scoped setup: project or user scope, an explicit AGENTS merge policy recorded per working root, and preserved non-OMX hook entries
- Codex plugin layout: a plugin and marketplace manifest with plugin-scoped lifecycle hooks, optional MCP servers, and apps disabled by default
- Session isolation: one writable session pointer per root, distinct OMX_ROOT values for concurrent conversations, and named worktrees for concurrent bypass-mode runs
- Runtime surfaces: HUD panes, omx doctor, omx exec smoke tests, sparkshell inspection, and a markdown-first wiki
