Oh My Codex (OMX)
Add reusable development workflows, specialist roles, and runtime coordination to Codex CLI.
- Source repo
- Yeachan-Heo/oh-my-codex
- Stars
- ★ 34k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 61/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Codex CLI developers who want a repeatable flow for clarifying requirements, reviewing a plan, and executing work.
- Not a fit if
- Teams needing native support for Claude Code or non-Codex agent platforms
- Teams needing Windows to receive the same support as macOS/Linux
- Source review
- 61/100 · Some gaps
What does this agent do, and when should you use it?
OMX is a workflow layer built around OpenAI Codex CLI, which remains responsible for carrying out coding tasks. Its CLI provides workflows such as $deep-interview, $ralplan, $ultragoal, and $team, which can be used independently or combined, plus reusable roles and skills. Scoped setup can install prompts, skills, AGENTS guidance, and hooks, while plans, logs, and runtime state live under .omx/. On macOS/Linux, tmux and Git worktrees support persistent team sessions; the CLI also includes HUD, diagnostics, and session inspection commands. The repository ships a Codex plugin layout too, but the plugin still relies on the installed omx CLI; the documented default path is an authenticated Codex CLI with OMX.
Install the omx command with npm install -g oh-my-codex, then configure it for a project or user with omx setup --scope project or --scope user. At launch, OMX can place Codex in a named Git worktree and manage sessions through tmux on macOS/Linux. In a Codex session, use $deep-interview to clarify requirements, $ralplan to produce a plan, and $ultragoal to execute with durable checkpoints; use $team when parallel work is needed. OMX stores guidance, plans, logs, and state in locations including AGENTS.md and .omx/, and offers omx doctor, omx hud, and omx session commands for checks and inspection. It invokes the Codex CLI available in the environment, so a real model call also requires Codex authentication.
- Codex CLI developers who want a repeatable flow for clarifying requirements, reviewing a plan, and executing work.
- Individual developers or teams who need durable
.omx/ultragoalcheckpoints for long tasks. - Engineers who want to isolate a high-privilege Codex session in a separate Git worktree.
- Teams coordinating multiple Codex workers in tmux on macOS/Linux.
- OMX users who need to inspect session usage, timelines, or terminal status.
How do you install or deploy this agent?
Requires Node.js 20+ and an installed, authenticated Codex CLI. If Codex is already installed, install OMX globally:
npm install -g oh-my-codexFrom the target Git project, configure project scope:
omx setup --scope project --merge-agentsAlternatively, configure user scope:
omx setup --scope userThe recommended team runtime uses tmux on macOS/Linux. Native Windows is a less-supported path.
How do you use this agent?
Check the installation and authentication, then launch a named worktree from the target Git project:
omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
omx --worktree=feat/task --madmax --xhighIn the Codex session, run the workflow stages you need:
$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "execute the approved plan with checkpoint evidence"Use $team within the execution path when a task benefits from parallel work. --madmax bypasses approval and sandbox guardrails; the README recommends it only in trusted environments and preferably with a worktree.
What are this agent's strengths and limitations?
- Workflow stages can be invoked separately or chained through
$autopilotfrom requirements clarification to planning and execution. $ultragoalpersists checkpoints for multi-stage work in.omx/ultragoal, supporting follow-up across turns.- Provides Git worktree launches, a tmux team runtime, a HUD, and session diagnostics.
- Supports project or user setup and stores project plans, logs, and state under
.omx/.
- Core operation depends on OpenAI Codex CLI and its authentication; the README does not document switching to another agent runtime.
- The recommended experience targets macOS/Linux; native Windows and Codex App receive less support and may behave inconsistently.
- The team runtime recommends tmux on macOS/Linux; the Windows path uses psmux and is less supported.
- Setup involves a global npm install, choosing a scope, and persistent guidance files; team coordination adds runtime setup.
How does this agent compare with similar options?
The README positions OMX as an added workflow layer for Codex and says users who want plain Codex may not need it. It also identifies gajae-code as a simpler, lighter-weight related option.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Oh My Codex (OMX) This agent | 61 · Some gaps | CLIFree + model costs | ★ 34k | today | TypeScript | Codex |
| AgentsMesh | 45 · Major gaps | Self-hosted serviceFreemium | ★ 2.4k | 26d ago | Go | Codex · Claude Code |
| Pi Dynamic Workflows | 88 · Good | Agent plugin / skillFree + model costs | ★ 555 | 13d ago | TypeScript | — |
| Bernstein | 78 · Good | CLIFree + model costs | ★ 1.3k | today | Python | Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README says launch-time npm updates are checked and scheduled or prompted after the session, and explicitly warns that --madmax removes Codex approval and sandbox protections while recommending worktrees. This supports informed use and some confirmation. Deductions: the candidate includes hooks, teams, MCP, and session export, but the supplied files do not show a complete permission model, data-flow inventory, or sensitive-data handling policy; session export is not redacted by default. Dependencies and override ranges are listed, but no vulnerability audit or dependency governance evidence is supplied. Maintainers are named; publisher identity remains unknown as specified.
The README distinguishes Codex CLI, Node, tmux/Windows psmux prerequisites, documents some conflicts and worktree states, and gives doctor and real-call checks. The CI excerpt declares formatting, static checks, builds, and tests. Deductions: these are documentation and workflow definitions, not evidence that this revision passed them; the supplied CI excerpt is incomplete, and external tools and services may be unavailable.
The README identifies users who already use Codex CLI and want workflow and runtime support, and describes planning, execution, team, queue, and advanced scenarios. It states that native Windows and Codex App receive less support and explains the --madmax boundary. Deductions: skill and hook trigger boundaries are only partly described in the supplied material, and environment details do not prove behavior across environments.
The README has a clear information structure, quick start, command examples, and substantial limitations; the supplied root includes an MIT license, Cargo.toml and package.json agree on the version, and the README names maintainer roles. Deductions: the supplied material has no changelog or detailed maintenance and update commitments; the version manifests establish current consistency, not version-history governance.
OMX offers reusable workflows, skills, team execution, HUDs, and persistent state, with concrete commands that help Codex users assess its potential use. Deductions: the broad feature set adds runtime dependencies, configuration, and state; the files do not quantify time or cost benefits or demonstrate output quality.
Many README installation and capability claims have concrete commands or documentation entry points; package.json lists dependencies and scripts, and the CI file lists intended checks. Deductions: the CI material is incomplete and includes no pass results; cross-file corroboration is limited, so configuration cannot be treated as an executed result.
- The README states that --madmax removes approval and sandbox protections; treat it as a high-risk launch mode and follow the documented worktree isolation guidance.
- Session export omits system and developer messages by default, but text is not automatically redacted; inspect exports for sensitive information before sharing.
- The material lists dependencies, update behavior, and check commands, but supplies neither actual check results for this revision nor a complete data-flow review.
FAQ
What do I need to run OMX?
Does OMX replace Codex for code execution?
Is --madmax appropriate for every repository?
Can I use only the Codex plugin to run OMX?
omx CLI. The plugin does not replace the global CLI and scoped setup.