Hi, Lena I am. I wasn't trying to evaluate anything the first time I read through the oh-my-codex documentation. I was looking for something simpler — whether Codex CLI could delegate work the same way I'd seen other agent setups do it. And I found myself reading the same line twice: "Your codex is not alone."
That's an odd thing to put at the top of a tool's README. But I think it's actually the most honest description of what oh-my-codex (OMX) is trying to be.
What oh-my-codex (OMX) Does
Orchestration layer for Claude Code and Codex CLI
OMX acts as an orchestration layer for the OpenAI Codex CLI, overcoming its execution limitations by integrating with Claude Code's capabilities. It resolves issues like tool call timeouts through an async job system, allowing long-running tasks to complete reliably. By providing structured workflows for tasks like autopilot development, TDD, code review, and strategic planning, OMX teaches Codex to effectively delegate complex operations to Claude Code, facilitating autonomous execution.
That description is from the v1 framing. Version 2 of OMX, which is what's currently active, shifted the architecture significantly. OMX v2 is Codex-native. Codex is the first-party executor in v2, and there is no Claude bridge in this release. The Claude-to-Codex delegation model from earlier versions has been replaced by a setup where Codex runs the session natively, and multi-agent work happens through spawned tmux workers — which can be Codex, Claude, or Gemini panes running in parallel.
I'm still not entirely sure how I feel about that architectural shift. The original appeal of OMX, for a lot of people, was the async delegation to Claude Code for long-running tasks. V2 is a different product in some ways.
Core features — delegation, autopilot, TDD integration
The canonical workflow in OMX flows through three entry points: $deep-interview for clarification before anything is built, $ralplan for consensus planning with tradeoff review, and $ralph or $team for execution. OMX provides canonical skills invoked with $skill-name syntax: $team for coordinated parallel execution, $ralph for persistence mode that keeps working until goals are verified complete, $ralplan for consensus planning (Planner → Architect → Critic), and $autopilot for full autonomous execution from idea through QA.
The persistent state layer is worth pausing on. OMX ships with five MCP servers for persistent state and memory, a live HUD for monitoring agent activity, and a hook system for extending behavior at key lifecycle points. It supports mixed-provider teams where Codex, Claude, and Gemini workers run side by side, each in their own worktree.
I went back and looked at the .omx/ directory structure the docs describe: plans, logs, memory, sessions, state, team artifacts. That's a lot of scaffolding to understand before the first real run.
How OMX Changes the Agent Workflow
Task delegation — breaking work into agent-sized chunks
This is where OMX's design philosophy becomes clearest. Rather than giving Codex one large task and hoping it stays coherent across dozens of file edits, OMX decomposes work into structured, reviewable chunks before execution starts.
The core workflow pipeline as shown in official demos begins with intent classification and deep interview to reduce ambiguity before execution. Multi-agent orchestration via tmux spawns parallel workers in isolated git worktrees at .omx/team/<n>/worktrees/worker-N, preventing write conflicts during simultaneous edits.
The worktree isolation detail matters more than it sounds. Anyone who's had parallel agent runs clobber each other's changes — especially in large refactors — will recognize this as a genuine engineering choice, not a marketing point.
The practical effect: instead of one Codex session trying to hold context across an entire codebase change, you get specialized workers with isolated branches, each responsible for a bounded slice. The leader agent integrates their outputs and handles conflicts.
Autopilot mode — when to use it and when not to
Autopilot continues through clear, low-risk, reversible next steps automatically, asking only when the next step is materially branching, destructive, or preference-dependent.
That policy statement from the autopilot SKILL.md is one of the more honest descriptions of how these modes should work. It's not "autopilot runs forever" — it's "autopilot runs until it hits a decision point that requires human judgment."
In practice, this means autopilot is well-suited for feature implementation where the spec is clear and the codebase is familiar. It's less suited for exploratory work, ambiguous requirements, or codebases you've never seen. If the deep-interview step surfaces a lot of unknowns, that's a signal autopilot isn**'t the right entry point yet.
I've noticed — and I could be reading too much into this — that the tooling seems designed to push users toward $deep-interview first, even when they think they know what they want. The intent classification happens before execution. That forced pause is deliberate.
TDD as agent guardrail — tests before code
The TDD integration in OMX isn't just a workflow suggestion. It's closer to a hard constraint. The test-driven-development skill enforces the classic RED-GREEN-REFACTOR cycle — write a failing test, watch it fail, write minimal code, watch it pass, then commit. If Claude tries to write code before tests, the skill makes it delete the code and start over. No exceptions.
This is actually the part that surprised me most when I first looked at OMX carefully. Most agent setups treat testing as something that happens after implementation. OMX treats tests as the specification layer that constrains implementation. That's a meaningful architectural difference, not just a workflow preference.
The practical implication: if you're working on a codebase without test infrastructure, OMX's TDD enforcement creates friction. If you already have a test suite, it becomes a genuine quality gate rather than an afterthought.
OMX vs Superpowers
Different scopes — orchestration vs behavior constraints
This is the question I kept seeing come up in developer discussions, and I think it deserves a direct answer rather than a vague "they're different tools."
Superpowers, the Claude Code plugin from Jesse Luehrs, focuses on constraining agent behavior within a session. The Superpowers Plugin introduces a planning phase before execution — rather than letting the model immediately start writing code, it first produces a structured plan which files it will touch, what changes it will make, and in what order. You review and approve that plan before any code is written.
OMX, by contrast, focuses on runtime infrastructure. The HUD, the worktree isolation, the MCP state servers, the multi-provider team spawning — these are execution environment features, not behavior constraint features.
One way to think about the difference: Superpowers makes a single agent smarter and more disciplined within one session. OMX makes a multi-agent system run reliably across sessions with persistent state.
Can they work together?
Probably yes, in principle. There's nothing structurally incompatible. But it's worth being honest: combining two orchestration layers adds complexity that may not be warranted for most workflows. If your pain point is a single agent going off in the wrong direction, Superpowers addresses that directly. If your pain point is coordinating parallel work across multiple agents with isolated state, OMX addresses that. Using both simultaneously means understanding both, which is its own overhead.
I'm not ready to call this one yet. I'd want to watch the behavior across more sessions before recommending a combined setup.
What Orchestration Doesn't Solve
Delegation without memory — tasks complete, learning evaporates
Here's the part that caught my attention in a way I didn't expect.
OMX has persistent state — the .omx/ directory stores task graphs, session artifacts, memory files. But persistent state is not the same as capability inheritance. The state records what happened. It doesn't package how a hard problem was solved into something a different agent — or the same agent on a different project — can inherit.
A worker completes a complex authentication refactor. The task is marked done. The artifacts are logged. The next agent that faces a similar authentication problem, in a different project or even in the same codebase three months later, starts from roughly the same position as the first one. The hard-won reasoning path isn't preserved as a reusable asset. It's in logs, if it's anywhere.
No capability inheritance between delegated agents
This is the gap that sits outside what OMX, or most orchestration tools, currently solve. Orchestration controls how work runs. Capability inheritance would address how successful problem-solving compounds over time.
The EvoMap GEP protocol documentation describes this distinction explicitly — packaging successful execution paths as verifiable, shareable assets that other agents can adopt, rather than leaving them in session logs. Whether that approach proves durable in practice is still an open question for me. But the problem it's pointing at is real.
OMX is honest about its scope: it's better task routing, better workflow, better runtime. That framing, directly from the oh-my-codex GitHub repository, is accurate. It doesn't claim to solve learning transfer. It claims to make execution more reliable and coordinated. Those are different problems.
Limits and Tradeoffs
A few things worth knowing before installing:
Platform constraints. OMX is primarily designed and actively tuned for macOS or Linux with Codex CLI. Native Windows and Codex App are not the default experience, may break or behave inconsistently, and currently receive less support.
The learning curve is real. The tmux requirement, the .omx/ directory structure, the skill syntax, the agent roles — this isn't a tool you pick up in ten minutes. The documentation is thorough, but thorough isn't the same as accessible.
Context overhead. Injecting AGENTS.md, skill prompts, and MCP server context into every session consumes tokens before any actual work begins. For simple, contained tasks, this overhead may cost more than the orchestration saves. OMX earns its keep on complex, multi-file work.
v1 vs v2 architecture difference. If you read older OMX write-ups describing Claude Code as the primary execution engine with Codex delegating to it — that's the v1 model. The current version inverts that relationship. Worth checking the official OMX documentation for the current architecture before investing time in setup.
FAQ
What is oh-my-codex (OMX)?
OMX is an open-source orchestration layer for the OpenAI Codex CLI. It adds multi-agent team coordination, persistent state via MCP servers, structured workflows (autopilot, TDD, planning), and a live monitoring HUD on top of standard Codex. It keeps Codex as the execution engine rather than replacing it
How does oh-my-codex work with Claude Code?
In v2, the relationship is different from v1. Rather than delegating long-running tasks from Codex to Claude Code via an async job system, OMX now supports mixed-provider teams where Claude (or Gemini) workers run in separate tmux panes alongside Codex workers. Each worker gets an isolated git worktree. The architecture is Claude Code compatible via the sister project oh-my-claudecode, which applies the same orchestration pattern to Claude Code specifically.
What is the difference between oh-my-codex and Superpowers?
Superpowers constrains agent behavior within a session — planning before coding, TDD enforcement, structured review cycles. OMX provides runtime infrastructure — worktree isolation, multi-agent coordination, persistent state, HUD monitoring. Superpowers makes one agent smarter. OMX makes a system of agents run reliably. The scopes are different enough that comparing them directly misses the point.
Does oh-my-codex support TDD workflows?
Yes. The TDD skill enforces the red-green-refactor cycle as a hard constraint, not a suggestion. Tests must be written before implementation code. If the agent tries to write implementation first, the skill enforces deletion and restart. This applies within the $tdd workflow path specifically.
Can oh-my-codex agents remember what they learned?
OMX maintains persistent state — session logs, task artifacts, project memory files in .omx/. An agent can retrieve context from past sessions within the same project. What it doesn't do is package successful problem-solving paths as transferable capabilities that can be inherited by different agents on different projects. That distinction — between state persistence and capability inheritance — is where current orchestration tools generally stop.
I'll keep watching how the v2 architecture settles. There's a part of me that's still a bit unclear on whether the shift away from the Claude delegation model was the right tradeoff — or just the necessary one.
Previous Posts:
👉 If you want a clearer mental model of where orchestration fits in the agent stack, read:OpenHarness and GEP: The Three Layers of the Agent Stack
👉 For a deeper look at why execution systems don’t solve learning transfer:ARC-AGI-3 and the Agent Learning Gap: What’s Still Missing
👉 If you're comparing persistent state vs actual capability reuse across agents:Agent Skills vs GEP Assets: What Actually Transfers Between Agents
👉 To understand how memory systems differ from true cross-session learning:Hermes Agent vs EvoMap: Memory vs Capability Inheritance
👉 And if you’re exploring whether agents can evolve beyond orchestration layers:EvoSkills: Can Agents Actually Improve Themselves Over Time?
