oh-my-codex (OMX)

// Overview

OMX keeps the OpenAI Codex CLI as the execution engine and wraps a workflow around it. Instead of replacing the agent, it makes a session start stronger by default, gives you one consistent path from clarification to completion, and keeps project guidance, plans, logs and state under a `.omx/` directory in the repo. The canonical workflow commands — `$deep-interview`, `$ralplan`, `$ultragoal`, `$team`, `$code-review`, `$ultraqa` — are invoked independently, not as a fixed chain.

The recommended day-to-day flow is clarify, approve a plan, then run `$ultragoal` as the durable multi-goal completion wrapper, reaching for `$team` only when a story genuinely needs coordinated parallel work and `$ralph` when you want a single-owner completion loop instead. Research has its own bounded lanes: `$best-practice-research` for ordinary upstream evidence gathering and `$autoresearch` / `$autoresearch-goal` for validator-gated research artifacts, all of which feed back into `$ralplan` for architecture synthesis.

Isolation is taken seriously. `--worktree` launches into a separate git checkout under `../<repo>.omx-worktrees/`, which is the safer default when combined with `--madmax` (OMX shorthand for Codex's `--dangerously-bypass-approvals-and-sandbox`, so it removes approval and sandbox guardrails and belongs only in trusted repositories). Each standard launch owns one writable session pointer under its `OMX_ROOT`, so a second launch from the same checkout fails closed rather than silently sharing state. macOS and Linux are the actively tuned path; native Windows and the Codex App are explicitly not the default experience.

// What it does

• Canonical workflow commands — `$deep-interview`, `$ralplan`, `$ultragoal`, `$team`, `$code-review`, `$ultraqa` — each usable independently
• Git-worktree launch isolation, named or detached, with fail-closed session-root ownership per checkout
• Agent teams over a durable tmux runtime (psmux on Windows), for coordinated parallel work inside one goal
• Durable state under `.omx/` for plans, logs, memory and mode tracking, plus scoped `AGENTS.md` project guidance
• Reasoning-effort shorthands (`--high`, `--xhigh`) and `--madmax` for Codex's bypass mode, with worktree launch recommended alongside it
• `omx doctor` install-shape checks plus an `omx exec` smoke test that proves the live Codex runtime can authenticate and complete a call
• An official Codex plugin layout at `plugins/oh-my-codex` with marketplace metadata, alongside the global CLI

// Getting started

Requirements: Node.js 20+, an installed and authenticated Codex CLI (`codex --version`), and tmux on macOS/Linux for the recommended durable team runtime. Do not reinstall @openai/codex through npm if Homebrew already owns the codex binary — npm can fail with EEXIST.

npm install -g oh-my-codex
# or, if you have no Codex CLI yet:
npm install -g @openai/codex
npm install -g oh-my-codex

omx setup --scope project --merge-agents
# or: omx setup --scope user

omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

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

/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior.

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "turn the approved plan into durable Codex goals"

omx
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Run long refactors through a repeatable clarify → plan → execute → verify loop instead of ad-hoc Codex prompts
• Keep risky bypass-mode sessions off your main checkout by launching each one into its own git worktree
• Split one story across coordinated parallel agents when a single-owner loop is too slow
• Carry plans, logs and mode state in-repo under `.omx/` so a session can be picked up later or by someone else

// How oh-my-codex (OMX) compares

oh-my-codex (OMX) alongside other open-source ai sdlc automation tools AI/TLDR tracks, ranked by GitHub stars.