OMX: A Workflow Layer That Keeps Codex From Breaking Your Flow
Hook
Most AI coding tools try to replace your workflow. OMX does the opposite: it assumes you already like Codex, and just adds the boring scaffolding—state persistence, role prompts, and team coordination—that Codex itself doesn’t ship with.
Context
OpenAI’s Codex CLI is a powerful autonomous coding agent, but it has no memory between sessions, no reusable workflow patterns, and no coordination layer for multi-step or parallel work. If you want to maintain project context, run durable executions that survive terminal crashes, or coordinate multiple agents working in isolated branches, you’re building that scaffolding yourself—usually with a pile of shell scripts and tmux sessions that grow organically until they’re unmaintainable.
OMX (oh-my-codex) emerged from that exact frustration. Instead of forking Codex or building yet another standalone agent framework, it wraps the existing Codex CLI and adds three missing layers: a prompt library for reusable roles, a skill system for common workflows, and a persistent state directory (.omx/) that survives restarts. The design philosophy is deliberate minimalism—Codex remains the execution engine, and OMX stays out of the way until you need structure.
Technical Insight
OMX’s architecture is a thin TypeScript layer that intercepts Codex launches and injects context before handing control back. When you run omx --madmax --high, it starts a standard Codex session but pre-loads project guidance from AGENTS.md, mounts the .omx/ state directory, and registers skills and prompts. The --madmax flag is syntactic sugar for a stronger default configuration, and --high bumps concurrency limits.
The prompt system uses a /prompts:* namespace to invoke role-specific system messages. For example, /prompts:architect "analyze the authentication flow" loads a curated architect persona optimized for boundary analysis and tradeoff exploration, while /prompts:executor switches to an implementation-focused role. These aren’t magic—they’re just well-tested system prompts that you can inspect, fork, and customize.
Skills are invoked with a $ prefix and represent reusable workflows. The simplest is $plan, which forces structured planning before implementation:
# Inside a Codex session started with omx --madmax --high
$plan "add rate limiting to the API"This writes a plan to .omx/plans/ and logs the intent, creating a structured breakdown. The plan persists across sessions, so if Codex crashes or you close the terminal, the next session can resume from the documented plan instead of starting cold.
The $ralph skill adds persistence to sequential execution. It wraps Codex’s execution loop with checkpointing:
$ralph "refactor the auth module with full test coverage"Ralph maintains execution state so if the process dies, you can restart OMX and resume from the last checkpoint instead of re-explaining context. This is particularly valuable for long-running refactors where interruptions are inevitable.
The most architecturally interesting piece is the team runtime, which coordinates parallel agents using tmux and git worktrees. Unlike the in-session skills, team mode is invoked from the CLI:
omx team 3:executor "fix the failing tests with verification"
omx team status <team-name>
omx team resume <team-name>OMX creates a durable team runtime with tmux/worktree coordination, and writes coordination state to .omx/team-state/. The tmux sessions are detachable, so you can resume from another terminal or even a different machine if you’re using a shared tmux server.
On Windows, OMX uses psmux, a PowerShell-based tmux alternative that provides similar session management without WSL2. The API is intentionally similar—omx team status <team-name> works identically across platforms.
The $deep-interview skill is a less obvious but high-value feature. It implements an interactive clarification loop that helps extract better requirements:
$deep-interview "build a caching layer"Instead of immediately jumping to code, the agent asks one question at a time about intent, non-goals, edge cases, and decision boundaries. After the agent signals sufficient clarity, it can hand off to $plan, $ralph, $team, or $autopilot. This forces better requirement gathering and reduces the “AI confidently built the wrong thing” failure mode.
The .omx/ directory is the persistence foundation. It holds plans, logs, memory, and runtime state for mode tracking and team coordination. Because it’s just files, you can version it in git (though you’ll probably want to .gitignore some of the noisier logs), inspect it with standard tools, and even hand-edit state if OMX gets confused.
Gotcha
OMX’s biggest limitation is its hard dependency on OpenAI’s Codex CLI. If you don’t have Codex CLI installed and configured, OMX is unusable—it’s an enhancement layer, not a standalone tool.
The team mode introduces platform-specific friction. On macOS, some Intel users report significant CPU spikes from syspolicyd and trustd during OMX startup, which appears to be related to macOS Gatekeeper validation. The recommended workarounds include running xattr -dr com.apple.quarantine $(which omx), adding the terminal app to Developer Tools allowlist, or using lower concurrency settings. On Windows, the tmux dependency forces users to either install WSL2 (adding a Linux subsystem just for session management feels heavy) or use psmux, which is less mature. If you’re in a Windows-first environment, the team coordination story is messier than on Unix-like systems.
OMX also appears to have limitations around conflict handling when using team mode with overlapping work, though the exact merge and conflict resolution behavior isn’t fully documented. For complex refactors involving multiple agents, you may need to carefully scope work to minimize conflicts.
Verdict
Use OMX if you already have Codex CLI access and regularly work on multi-step coding tasks where persistence, role prompts, or parallel execution would eliminate repeated context-setting. It’s especially valuable for exploratory work that benefits from $deep-interview’s clarification loop, or complex tasks where team coordination can parallelize independent subtasks. Skip it if you don’t have Codex CLI installed (it’s a non-starter), if you need Windows-first tooling without tmux/psmux complications, if you prefer simpler single-agent tools like Aider, or if your workflow doesn’t involve long-running tasks that justify the overhead of .omx/ state management. OMX is a force multiplier for Codex users, but it’s a specialized enhancement, not a general-purpose AI coding assistant.
