OMX
A workflow layer that adds prompts, agent teams, and runtime helpers on top of OpenAI's Codex CLI.Yeachan-Heo/oh-my-codex
- Stars
- 33.7k
- Forks
- 2.5k
- Licence
- MIT
- Language
- TypeScript
- Last update
- 4 days ago
- Type
- Dev tool
What it is
OMX (oh-my-codex) is an add-on for OpenAI's Codex CLI, a coding agent that runs in your terminal. It adds a consistent workflow on top, such as planning, implementation, review, and QA steps invoked with commands like $plan, $team, and $code-review, and it keeps project guidance and state in a .omx/ folder. People use it when they want Codex to handle larger, multi-step tasks in a more structured way.
- Start a long refactor with a durable /goal and then break it into planning and implementation steps
- Run a code review step on changes made in a Codex session using $code-review
- Set up project-level AGENTS.md guidance with omx setup --scope project
- Use omx --worktree to run Codex against a separate git worktree for a specific task
Great for
- Developers already using Codex CLI who want more structure on longer tasks
- Teams that want project guidance stored in AGENTS.md and a .omx/ folder inside a repository
- macOS or Linux users, which the README names as the recommended setup
- Users who want to run planning, review, and QA steps separately instead of in a fixed chain
Not ideal for
- People who do not use or have access to Codex CLI, since OMX is described as a layer on top of it
- Native Windows users, because the README says it is not the default experience and receives less support
- Users who find a heavy workflow layer more than they need; the README itself points to a lighter sibling project, gajae-code, for that case
How to get it
- 1
Install with a package manager
You'll need: Node.js 20 or newer · Codex CLI installed and authenticated on PATH
Install OMX globally with npm
npm install -g oh-my-codexInstall Codex CLI with npm (optional, if you do not already have it)
npm install -g @openai/codex - 2
Run it
- Confirm Codex works by running codex --version
- Install the oh-my-codex package with npm install -g oh-my-codex
- Change into the git project you want Codex to edit
- Start a session with omx --worktree=feat/task --madmax --xhigh, choosing your own task name
- Inside Codex, try a command such as $deep-interview or $ralplan as shown in the README
- 3
Get the most out of it
- Use omx setup --scope project --merge-agents in a repository to keep project guidance in its own AGENTS.md
- Read the docs at docs/getting-started.html and docs/skills.html to learn the available $ commands
- Set OMX_AUTO_UPDATE=0 if you do not want launch-time update checks
- Use /goal for a durable objective and checkpoints on long tasks, as shown in the README example
Downloads
Strengths
- Builds on Codex CLI rather than replacing it, and the README says Codex remains the execution engine
- Workflow steps can be invoked independently, so you can use only the parts you need
- MIT licensed with an active public repository and a published npm package
Trade-offs
- The README describes a number of settings and behaviors (merge policies, auto-update, plugin modes) that add complexity for new users
- Support is strongest on macOS and Linux; Windows and the Codex App may behave inconsistently
- Requires a working, authenticated Codex CLI, so it does not work on its own
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.