Skip to content
/

oh-my-codex (Yeachan-Heo)

oh-my-codex-yeachan · Yeachan-Heo/oh-my-codex · ★ 30k · last commit 2026-05-26

Add structured planning, durable state, and multi-agent team coordination to OpenAI Codex CLI without replacing it.

Best whenExecution quality is bottlenecked by intent clarity, not implementation detail; a Socratic ambiguity-gating interview is mandatory before planning.
Skip ifReplacing Codex with OMX, Using team mode for in-session parallelism (use native subagents instead)
vs seeds
superpowersby shipping a full CLI binary…
Primitive shape 116 total
Skills 46 Subagents 20 Hooks 5 MCP tools 45
00

Summary

oh-my-codex (Yeachan-Heo) — Summary

oh-my-codex (OMX) by Yeachan-Heo is the original and largest implementation of the "oh-my-codex" naming meme: a workflow layer for OpenAI Codex CLI that adds structured planning, multi-agent coordination via tmux, durable state under .omx/, and a rich CLI binary (omx). With 29,662 stars and 30 contributors, it is the canonical project; all other "oh-my-codex" forks explicitly disclaim being official continuations. The framework ships 46 skills, 20+ agent persona files, an MCP server family with state/task/memory/team tool groups, and a TypeScript + Rust codebase with both npm and native binary artifacts. Its flagship workflow is $deep-interview$ralplan$ultragoal, with $team providing tmux-based parallel multi-agent execution. Durable state lives in .omx/ (plans, logs, memory, ultragoal ledger) and survives context compaction and session interruption. Closest seed comparisons: it resembles superpowers in its skills-only surface for Claude Code, but adds a full CLI runtime, tmux team coordination, and durable goal ledger that superpowers lacks; it resembles claude-flow in MCP integration and multi-agent scope but targets Codex CLI rather than Claude Code natively.

01

Overview

oh-my-codex (Yeachan-Heo) — Overview

Origin

Created by Yeachan Heo (@Yeachan-Heo) with co-maintainer HaD0Yun. The project launched as a workflow layer for OpenAI Codex CLI, inspired by oh-my-zsh's plugin philosophy for shell enhancement. Grew to 29,662 stars and a Discord community with ~1,452+ members.

Philosophy

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

"Start OMX strongly, clarify first when needed, approve the plan, optionally use $prometheus-strict for interview-driven plan hardening on high-risk work, then use $ultragoal as the default durable completion wrapper."

"Most users should think of OMX as better task routing + better workflow + better runtime, not as a command surface to operate manually all day."

Disambiguation

The README explicitly states: "Third-party projects or forks that use names such as 'OMX v2' are not official continuations, replacements, or release lines for this repository unless this README or the docs explicitly say so." The official npm package is oh-my-codex.

Design Principles

  • Intent-first: every workflow begins with $deep-interview to remove ambiguity before planning
  • Durable state: .omx/ persists plans, sessions, and goal ledgers across context windows
  • Mode separation: ultragoal (durable sequential goals), team (tmux parallel execution), ralph (single-owner persistence loop) are distinct, composable primitives
  • Socratic gating: deep-interview uses quantitative ambiguity scoring (thresholds 0.15/0.20/0.30) before permitting planning handoff
  • Research-bounded: $autoresearch and $best-practice-research are wrappers that gate research artifacts with validators before feeding into planning

Sigrid Jin (sigridjineth) is listed as an Ambassador

The sigridjineth fork of oh-my-codex is explicitly from an ambassador, not a competitor.

02

Architecture

oh-my-codex (Yeachan-Heo) — Architecture

Distribution

  • npm package: oh-my-codex (global install)
  • Binary: omx (TypeScript compiled to dist/cli/omx.js)
  • Also ships a Codex plugin layout at plugins/oh-my-codex with marketplace metadata

Install

npm install -g oh-my-codex
omx setup

Or if Codex CLI not yet installed:

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

Required Runtime

  • Node.js >= 20
  • Codex CLI (Homebrew or npm)
  • macOS/Linux (tmux required for team mode)
  • Optional: Rust toolchain (for omx-explore-harness native binary)

Directory Tree

oh-my-codex/
├── src/
│   ├── cli/          — omx CLI commands
│   ├── hooks/        — Codex lifecycle hook handlers
│   ├── mcp/          — MCP server implementations
│   ├── team/         — tmux team runtime
│   ├── hud/          — usage telemetry and HUD state
│   ├── ralph/        — ralph persistence loop
│   ├── agents/       — agent config/selection
│   └── ...
├── skills/           — 46 SKILL.md files (workflow definitions)
├── prompts/          — legacy prompt files
├── plugins/          — Codex plugin marketplace bundle
├── crates/           — Rust crate (omx-explore-harness)
├── .agents/          — plugin marketplace metadata
├── missions/         — mission-style workflow docs
└── dist/             — compiled JS output

Target AI Tools

  • Primary: OpenAI Codex CLI
  • Secondary: Claude CLI (team workers can be launched as Claude CLI via OMX_TEAM_WORKER_CLI=claude)
  • Plugin surface also targets Codex plugin marketplace

State Root

.omx/ in the project directory:

.omx/
├── hud-config.json
├── logs/
├── memory/
├── plans/
├── research/
├── sessions/
├── state/
├── ultragoal/
│   ├── goals.json
│   ├── brief.md
│   └── ledger.jsonl
└── team/
03

Components

oh-my-codex (Yeachan-Heo) — Components

CLI Binary: omx

Subcommand Purpose
omx setup Install OMX skill/agent/hook artifacts into Codex home
omx doctor Validate install shape and environment
omx exec Smoke-test Codex runtime (auth, model call)
omx --madmax --high Launch OMX in recommended tmux mode
omx --direct Launch without tmux/HUD management
omx team ... Manage tmux team workers
omx session Session state management
omx ultragoal Durable multi-goal plan management
omx hud HUD state queries
omx question Structured interview question in tmux pane
omx state read/write Per-session state management
omx sparkshell Shell-native read-only evidence collection
omx autoresearch Bounded research artifact generation
omx explore Deprecated; replaced by repo inspection tools
omx update Check and apply npm updates

Skills (46 total)

Skill Purpose
deep-interview Socratic ambiguity-gated clarification loop before execution
ultragoal Durable repo-native multi-goal plans over Codex goal mode
team tmux-based N-agent parallel execution
ralplan Plan approval and architecture synthesis
prometheus-strict Interview-driven plan hardening for high-risk work
ralph Single-owner persistence loop
ralph-init Initialize ralph state
visual-ralph Ralph with visual verdict support
ultrawork Full autonomous pipeline wrapper
ultraqa QA-heavy validation cycles
autopilot Broad autonomous execution
pipeline Ordered stage handoff between agents
swarm N-agent coordinated execution
ecomode Cost-sensitive execution mode
autoresearch Bounded validator-gated research artifacts
autoresearch-goal Goal-mode research missions
best-practice-research Pre-planning official/upstream evidence wrapper
plan Durable planning state management
design Architecture/design workflow
trace Code tracing and investigation
code-review Code review workflow
security-review Security-focused review
tdd Test-driven development enforcement
analyze Code analysis
deepsearch Deep codebase search
build-fix Build failure recovery
git-master Git workflow management
hud HUD state and telemetry display
doctor Environment health check
omx-setup OMX setup from within Codex
skill Skill authoring workflow
worker Worker-mode prompt
ask General ask pattern
ask-claude Claude-specific ask
ask-gemini Gemini-specific ask
note Note-taking during sessions
help Help routing
cancel Cancel active operations
configure-notifications Setup notification system
web-clone Web page cloning
wiki Wiki-style knowledge queries
frontend-ui-ux Frontend/UX workflow
performance-goal Performance-focused goal setting
ai-slop-cleaner Remove AI-generated filler from outputs
visual-verdict Visual review verdict

Agent Personas (prompts/ directory, 20+ files)

analyst, api-reviewer, architect, build-fixer, code-reviewer, code-simplifier, critic, debugger, dependency-expert, designer, executor, explore-harness, explore, git-master, information-architect, performance-reviewer, planner, product-analyst, product-manager, prometheus-strict-metis

MCP Server Families

Family Tools
omx_task_* Task creation, listing, updating
omx_state_* Session state read/write
omx_memory_* Memory persistence
omx_note_* Note management
omx_explore_* Codebase exploration
omx_team_* Team lifecycle management
omx_plugin_* Plugin management
omx_hook_* Hook status/management
omx_agent_* Agent catalog queries

Hooks

Lifecycle events handled: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop

Hook presets (via omx hooks install): memory, safety, review, telemetry, workspace-context

05

Prompts

oh-my-codex (Yeachan-Heo) — Prompts

Verbatim Excerpt 1: deep-interview/SKILL.md (Ambiguity Gating)

Prompting technique: Socratic gating with quantitative ambiguity scoring; single-question-per-round discipline; source classification taxonomy

<Execution_Policy>
- Ask ONE question per round (never batch multiple interview rounds into one `questions[]` form)
- Ask about intent and boundaries before implementation detail
- Target the weakest clarity dimension each round after applying the stage-priority rules below
- Treat every answer as a claim to pressure-test before moving on: the next question should usually demand evidence or examples, expose a hidden assumption, force a tradeoff or boundary, or reframe root cause vs symptom
- Do not rotate to a new clarity dimension just for coverage when the current answer is still vague; stay on the same thread until one layer deeper, one assumption clearer, or one boundary tighter
- Before crystallizing, complete at least one explicit pressure pass that revisits an earlier answer with a deeper, assumption-focused, or tradeoff-focused follow-up
- Gather codebase facts via `explore` before asking user about internals
- Route facts before judgment in the Ouroboros style: before presenting a user-facing interview round, classify whether the needed information is a discoverable fact, a fact needing confirmation, or a human decision.
</Execution_Policy>

Source classification labels:
- `[from-code][auto-confirmed]` — exact, high-confidence codebase facts
- `[from-code]` — inferred codebase findings needing confirmation
- `[from-research]` — externally sourced facts; facts only, not decisions
- `[from-user]` — goals, preferences, business logic, scope, non-goals, acceptance criteria

Verbatim Excerpt 2: ultragoal/SKILL.md (Durable Goal Loop)

Prompting technique: Procedural loop with explicit state commands; ledger-anchored checkpoint discipline; steering invariants

## Complete goals

Loop until `omx ultragoal status` reports all goals complete:

1. Run `omx ultragoal complete-goals`.
2. Read the printed handoff.
3. Call `get_goal`.
4. If no active Codex goal exists, call `create_goal` with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
5. Complete the current OMX story only.
6. Run a completion audit against the story objective and real artifacts/tests.
7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({status: "complete"})` only after that gate is clean.

Verbatim Excerpt 3: team/SKILL.md (tmux Worker Coordination)

Prompting technique: Operational contract with hard error conditions; worker CLI routing via env vars; state-file protocol

When user triggers `$team`, the agent must:
1. Invoke OMX runtime directly with `omx team ...`
2. Avoid replacing the flow with in-process `spawn_agent` fanout
3. Verify startup and surface concrete state/pane evidence
4. If active team mode state is missing, initialize/sync it from canonical team runtime state before proceeding
5. Keep team state alive until workers are terminal (unless explicit abort)
6. Handle cleanup and stale-pane recovery when needed

If `omx team` is unavailable, stop with a hard error.
09

Uniqueness

oh-my-codex (Yeachan-Heo) — Uniqueness

Differs From Seeds

Closest seeds: superpowers (skills-only behavioral framework) and claude-flow (MCP-anchored multi-agent). OMX differs from superpowers in having a full CLI runtime (omx), tmux team coordination, and a durable multi-goal ledger — superpowers is purely Claude Code skills with no binary. OMX differs from claude-flow in targeting Codex CLI (not Claude Code) as primary, shipping tmux-based team coordination rather than hive-mind MCP tools, and using file-based .omx/ state rather than SQLite. Unlike taskmaster-ai, OMX's goal decomposition happens through a Socratic interview process rather than AI-driven task analysis. Unlike BMAD-METHOD, OMX has no persona-based role switching — roles are per-worker CLI launch parameters. OMX is architecturally unique in the corpus for combining: (1) quantitative ambiguity gating in deep-interview, (2) Codex native goal mode integration via ultragoal, and (3) mixed Codex+Claude worker teams in tmux.

Positioning

  • The original, largest "oh-my-codex" project (29,662 stars vs 65 and 14 for the other two)
  • Targets Codex CLI specifically (not Claude Code first)
  • The only framework with a dedicated omx question interactive interview tool for tmux panes
  • Ships a Rust codebase component (omx-explore-harness) for native code exploration
  • Ambassador sigridjineth's fork is explicitly an extension/derivative, not competition

Observable Failure Modes

  • tmux dependency: team mode silently degrades without tmux; README warns about Windows path
  • Codex App vs CLI difference: some features (tmux, HUD) only work in CLI, not Codex App
  • Plugin vs native agent stale files: README warns explicitly that both can coexist and cause shadowing bugs
  • Version drift: omx update is throttled and deferred; running stale OMX against new Codex can break hook contracts
  • Context budget overrun: deep-interview has explicit rules about oversized context but requires agent discipline to enforce
  • omx explore deprecation: multiple skill files still reference omx explore while recommending normal tools instead

Canonical Status

This is the official/canonical project. The oh-my-codex npm package is controlled by this repo. Other "oh-my-codex" projects (scalarian, sigridjineth) are derivatives.

04

Workflow

oh-my-codex (Yeachan-Heo) — Workflow

Canonical Flow

$deep-interview → $ralplan → [$prometheus-strict] → $ultragoal
                                                  → $team (parallel)
                                                  → $ralph (single-owner)

Phases and Artifacts

Phase Skill Artifact Approval Gate
Clarification deep-interview Intent spec in .omx/specs/ or chat Ambiguity score <= threshold
Planning ralplan Plan in .omx/plans/ User approval of plan
Hardening (opt.) prometheus-strict .omx/plans/prometheus-strict/ artifacts User review
Research (opt.) autoresearch .omx/research/ artifacts Validator-gated
Goal creation ultragoal create-goals .omx/ultragoal/goals.json, brief.md User inspects goals.json
Execution ultragoal complete-goals .omx/ultragoal/ledger.jsonl Per-story completion audit
Parallel exec team .omx/state/team/ files Worker terminal evidence
Verification Post-execution Test output, build logs Required before close

Approval Gates

  1. Ambiguity threshold gate — deep-interview blocks handoff until weighted ambiguity score <= 0.15/0.20/0.30 (depth-profile-dependent)
  2. Plan approval — ralplan produces plan; user must approve before ultragoal execution begins
  3. prometheus-strict gate — optional interview-critique-synthesis loop for risky plans
  4. Ultragoal story completion audit — each story requires omx ultragoal checkpoint with evidence before advancing
  5. Final quality gate — mandatory cleanup/review gate before update_goal({status: "complete"}) on final story
  6. Team worker evidence — orchestrator reads terminal evidence before advancing to next wave

Deep-Interview Ambiguity Gating

  • Quick profile: threshold <= 0.30, max 5 rounds
  • Standard profile: threshold <= 0.20, max 12 rounds (default)
  • Deep profile: threshold <= 0.15, max 20 rounds
  • Autoresearch mode: convergence on validator-ready mission artifacts

State Contract

After a complete ultragoal run, the following must exist:

  • .omx/ultragoal/goals.json — completed stories
  • .omx/ultragoal/ledger.jsonl — structured audit trail
  • .omx/ultragoal/brief.md — original brief
  • Per-story checkpoint entries with get_goal snapshots
06

Memory Context

oh-my-codex (Yeachan-Heo) — Memory & Context

State Storage

All state lives under .omx/ in the project root:

Path Content Persistence
.omx/ultragoal/goals.json Multi-story goal plan with status Project
.omx/ultragoal/ledger.jsonl Append-only checkpoint + steering audit log Project
.omx/ultragoal/brief.md Original brief for the ultragoal run Project
.omx/plans/ Planning artifacts per phase Project
.omx/research/ Autoresearch mission artifacts Project
.omx/sessions/ Session state for resume Project
.omx/state/team/ Team worker inbox/status files Project
.omx/memory/ Memory store (format: unspecified) Project
.omx/logs/ Session logs Project
.omx/hud-config.json HUD configuration Project

CLI State Commands

  • omx state write/read --input '<json>' --json — per-session state management
  • omx ultragoal checkpoint --goal-id ... --status ... --evidence ... — durable ledger writes
  • omx session start/resume — session lifecycle

MCP-Bridged Memory

The omx_memory_* MCP tool family provides structured memory access within Codex sessions.

Context Compaction Handling

The framework explicitly handles context compaction:

  • Plans and goal ledgers persist to .omx/ so re-reading artifacts after compaction restores context
  • .omx/ultragoal/ledger.jsonl uses fresh_leader_get_goal_required checkpoint policy
  • Session resume restores team worker state from filesystem

Cross-Session Handoff

$ultragoal is designed as the durable cross-session handoff primitive: each story checkpoint includes a get_goal snapshot so a fresh Codex session can inspect goals.json and continue at the next incomplete story.

Deep Interview Context Budget

The deep-interview skill explicitly manages prompt budget:

"If initial context is oversized or would exceed the prompt budget, do not paste or forward the raw payload into interview prompts; request and record a prompt-safe initial-context summary first."

07

Orchestration

oh-my-codex (Yeachan-Heo) — Orchestration

Multi-Agent: Yes

OMX supports two coordination modes:

1. tmux Team Mode ($team)

  • Spawns N real Codex and/or Claude CLI sessions in tmux split panes
  • Coordination through .omx/state/team/ files + omx team api ... CLI
  • Worker type: N:agent-type (e.g., 3:executor, 2:reviewer)
  • Mixed worker CLIs: OMX_TEAM_WORKER_CLI=claude, OMX_TEAM_WORKER_CLI_MAP=codex,claude
  • Subagent count: configurable per-run (up to tmux resource limits)
  • Isolation: each worker has its own Codex/Claude CLI process with its own context window

2. Codex Native Subagents

  • For bounded in-session parallelism where leader can fan out and wait directly
  • Used inside ultrawork for independent task parallelism
  • NOT a replacement for tmux team runtime's stateful coordination

Orchestration Pattern

hierarchical (leader/T0 + N workers) + parallel-fan-out within waves

Isolation Mechanism

  • Each worker has its own CLI process (process isolation)
  • No shared state between agent processes except .omx/state/ files
  • No git worktree isolation mentioned (workers edit shared repo)

Multi-Model

Partial multi-model support:

  • Claude teammates launched as claude CLI (any model)
  • OMX_TEAM_WORKER_LAUNCH_ARGS="--model claude-..." configures model per worker
  • Default is Codex (GPT) for workers; Claude available via env override
  • No fixed model-role mapping in config files found; runtime-configured

Execution Mode

  • Interactive-loop (omx session in tmux) + continuous-ralph (ralph loop) + one-shot (omx exec)

Consensus Mechanism

None — leader receives worker evidence and decides; no byzantine/raft protocol.

Prompt Chaining

Yes: $deep-interview output (intent spec) IS the input to $ralplan; $ralplan output IS the input to $ultragoal; worker evidence IS the input to leader checkpoint.

Context Compaction

Handled via .omx/ artifacts + omx session resume + ledger checkpoints.

08

Ui Cli Surface

oh-my-codex (Yeachan-Heo) — UI & CLI Surface

Dedicated CLI Binary

Binary: omx
Install: npm install -g oh-my-codex
Is thin wrapper: No — omx has its own runtime (team management, session state, ultragoal ledger, question system, HUD, MCP servers)

Key CLI Subcommands

  • omx setup / omx doctor — install and validate
  • omx --madmax --high — recommended launch (attaches tmux, starts HUD)
  • omx --direct — launch without tmux/HUD
  • omx team [N:type] "<task>" — spawn tmux worker team
  • omx ultragoal create-goals|complete-goals|status|checkpoint|steer — goal lifecycle
  • omx session start|resume — session management
  • omx question — structured interview question in tmux pane
  • omx state read|write — session state access
  • omx hud — HUD state display
  • omx exec — smoke-test Codex runtime
  • omx update — npm update check

Launch Policy

OMX_LAUNCH_POLICY=direct|tmux|detached-tmux|auto environment variable controls tmux behavior. CLI flags override env.

HUD (Heads-Up Display)

  • tmux-integrated status display showing active sessions, worker state, notifications
  • Configured in .omx/hud-config.json
  • omx hud CLI queries current state

Local Web Dashboard

None — no web dashboard detected.

IDE Integration

None — no VSCode extension or IDE plugin.

Observability

  • .omx/logs/ — session logs
  • .omx/ultragoal/ledger.jsonl — append-only structured audit log for goal operations
  • HUD displays runtime state in tmux panes
  • omx cost-report mentioned in README for tracking (via MCP tools)

Notifications

$configure-notifications skill — notification system (Codex native notifications or external channel configuration)

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…