Oh My Codex: Building a Workflow Runtime Layer on Top of AI Agent CLI Tools
Hook
Most AI coding assistants force you to choose between simple chat or complex autonomous agents. OMX splits the difference: start with plain Codex, then progressively layer in workflows only when your task actually needs them.
Context
OpenAI’s Codex CLI gives developers a powerful AI agent that can read, write, and execute code. But raw Codex sessions lack structure for complex projects: you lose context between sessions, can’t easily reuse effective prompting patterns, and have no built-in support for multi-agent coordination when tasks grow large enough to benefit from parallelization.
Oh My Codex (OMX) addresses this by building a workflow orchestration layer around Codex rather than replacing it. The philosophy is progressive enhancement: users start with a familiar Codex chat interface, then invoke increasingly sophisticated workflows using dollar-prefixed keywords like $architect, $plan, or $team as their task complexity grows. It’s a middle path between “raw LLM chat” and “fully autonomous agent framework”—keeping the developer in control while making powerful patterns reusable.
Technical Insight
OMX’s architecture reveals smart decisions about how to extend an existing CLI tool without forking it. The core insight is treating Codex as an execution engine while OMX handles workflow routing, state persistence, and multi-agent coordination.
The keyword-based DSL is elegant. Instead of learning new CLI commands or configuration syntax, you invoke workflows naturally within your Codex chat session:
$architect "analyze the authentication flow"
$plan "map the safest implementation path"
$team 3:executor "fix the failing tests with verification"These dollar-prefixed invocations are implemented as reusable prompt templates that inject specific roles and workflows into Codex. The $architect keyword loads analysis-focused prompting, while $executor focuses on implementation. This makes effective prompting patterns shareable and discoverable—users can run /skills to browse installed workflows rather than reinventing prompts each session.
Persistent state lives in a .omx/ directory at your project root. This stores plans, execution logs, agent memory, and runtime mode tracking that survives across sessions. When you run $plan on Monday and return Tuesday, OMX can reference that plan without you re-explaining context. This project-scoped persistence is more practical than pure session memory or global configuration.
The team runtime shows sophisticated coordination architecture. When you invoke $team 3:executor "task", OMX creates three isolated Git worktrees, spawns a tmux session per agent, and coordinates their parallel execution. On Unix systems this uses actual tmux; on Windows it uses psmux for compatibility. Each agent works in process isolation with its own workspace, preventing conflicts when multiple agents modify files simultaneously.
The progressive complexity model deserves emphasis. The recommended entry point is simply omx --madmax --high, which launches an enhanced Codex session. Most users work here, invoking lightweight roles like $architect when needed. Only when tasks grow complex enough—say, refactoring authentication across multiple services—does the agent suggest escalating to $ralph (persistent sequential execution) or $team (coordinated parallel work). You don’t pay the complexity cost of multi-agent orchestration until you need it.
The $deep-interview skill is particularly clever for vague requirements. Instead of jumping to implementation, it enters a clarification loop that iteratively refines intent, scope, and non-goals before handing off to execution workflows. This addresses a common failure mode where developers give underspecified prompts and get overconfident implementations.
Gotcha
OMX has a hard dependency on OpenAI’s Codex CLI. You can’t use it with Anthropic’s Claude, Gemini, or open models—it’s tightly coupled to the Codex ecosystem. This makes sense given OMX’s design as a Codex enhancement layer rather than a general-purpose framework, but it means you’re locked into OpenAI’s pricing, rate limits, and API availability. If Codex CLI changes significantly or gets deprecated, OMX’s value proposition shifts entirely.
The team runtime introduces real operational complexity. You need tmux (or psmux on Windows) installed and working correctly. Multi-agent coordination with Git worktrees sounds powerful but adds failure modes: what happens when agents conflict on shared state? How do you debug when one agent in a three-agent team gets stuck? The monitoring surface exists (omx hud --watch) but durable multi-agent systems are inherently harder to reason about than sequential execution.
The README documents a known Intel Mac performance issue: high syspolicyd / trustd CPU usage during startup, especially with --madmax --high mode. The suggested workarounds include using xattr -dr com.apple.quarantine, adding your terminal to Developer Tools allowlist, or avoiding high concurrency modes—but this indicates platform-specific rough edges that may affect user experience on certain configurations.
Verdict
Use OMX if you’re already invested in OpenAI Codex CLI and regularly hit workflow limitations: you want reusable agent roles, need persistent project context across sessions, or have tasks genuinely complex enough to benefit from multi-agent parallelization. The progressive complexity model is smart—you start simple and only escalate when needed. It’s particularly valuable for teams that have codified effective Codex prompting patterns and want to make them shareable via skills. Skip it if you don’t use Codex CLI, prefer vendor-independent tooling that works with multiple LLM providers, or primarily work on tasks simple enough that plain Codex chat suffices. Also skip if you’re not comfortable with potential platform-specific issues (like the documented Intel Mac performance concerns) or don’t want the operational overhead of multi-agent runtimes. OMX is middleware for power users already comfortable with Codex who need more sophisticated orchestration, not a simpler alternative to raw LLM coding assistants.
