Skip to content
Get packs

Guide · Open source

How to use oh-my-codex: install, run workflows and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

oh-my-codex (OMX) is an open-source add-on for OpenAI's Codex CLI, a coding agent that runs in your terminal. It adds a more structured workflow on top of Codex for longer, multi-step tasks. This guide shows you how to install it, start a session, use its workflow commands, and understand where it stores project guidance.

OMXYeachan-Heo/oh-my-codex · ★ 33.7k · MIT

Quick start

  1. 1Check Codex CLI. Confirm that codex --version runs and that Codex is authenticated. OMX needs a working codex command on your PATH.
  2. 2Install oh-my-codex. Run npm install -g oh-my-codex. This installs the official package globally.
  3. 3Open your project. Change into the git repository you want Codex to work on.
  4. 4Run setup for the project. Run omx setup --scope project --merge-agents so the repository owns its AGENTS.md guidance.
  5. 5Start OMX. Run omx to start a Codex session with OMX's defaults. Use --worktree to name a task branch if you want one.
  6. 6Run workflow steps. Invoke $plan, $team, $code-review or $ultraqa separately as each stage of your task needs them.

What OMX needs before you install

OMX is a layer on top of Codex CLI, so you need Codex CLI working first. The project lists Node.js 20 or newer and a Codex CLI that is installed and authenticated on your PATH as prerequisites.

The README names macOS or Linux with Codex CLI as the recommended setup. Native Windows and the Codex App are not the default experience and receive less support.

  • Node.js 20 or newer
  • Codex CLI installed and authenticated, available as the codex command on PATH
  • macOS or Linux is the recommended setup
codex --version

Install OMX with npm

The official package is oh-my-codex. Install it globally with npm. If you do not have Codex CLI yet, the README shows an optional npm install for it.

If you already installed Codex CLI with Homebrew, do not run a combined npm install over the existing binary. The README warns that npm may fail with EEXIST on a file such as /opt/homebrew/bin/codex. OMX only needs a working, authenticated codex command on PATH, however it was installed.

npm install -g oh-my-codex # optional, only if you do not already have Codex CLI: npm install -g @openai/codex

Start OMX in a project

Run OMX from the git project you want Codex to edit. The README's default example uses a worktree flag with a task-specific branch name, plus the --madmax and --xhigh flags.

Choose the setup scope on purpose. Use project scope when a repository should own its durable AGENTS.md guidance. Use user scope for user-level Codex setup. Avoid project setup from a broad home directory, because a home-level AGENTS.md often holds global rules.

  • Project scope: run omx setup --scope project --merge-agents inside the repository.
  • User scope: run omx setup --scope user when you are not preparing the current directory as an OMX project.
  • Updates: omx update checks npm and then refreshes setup.
omx --worktree=feat/task --madmax --xhigh omx setup --scope project --merge-agents

Use the workflow commands

OMX's canonical workflow commands include $plan, $ultragoal, $team, $code-review and $ultraqa. The README says each can be invoked independently, with no fixed chain, so you can run planning, review or QA on their own.

Inside a Codex session, you can also set a durable objective with /goal and use skills such as $deep-interview and $ralplan before handing an approved plan to $ultragoal.

  • $plan: planning step
  • $team: team-style multi-agent work
  • $code-review: review step
  • $ultraqa: QA step
  • $ultragoal: turns an approved plan into durable checkpoints
/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior. $deep-interview "clarify the authentication change" $ralplan "approve the auth plan and review tradeoffs" $ultragoal

Know where OMX keeps its files

OMX keeps project guidance, plans, logs and state in a .omx/ folder inside the repository. Durable orchestration guidance lives in AGENTS.md, either at ./AGENTS.md for project setup or ~/.codex/AGENTS.md for user setup.

The README says the explicit AGENTS merge choice is recorded in ./.omx/setup-scope.json for the current working root. Setting OMX_AUTO_UPDATE=0 disables the launch-time update check.

  • .omx/ holds project guidance, plans, logs and state
  • AGENTS.md holds the durable guidance layer
  • OMX_AUTO_UPDATE=0 turns off the launch-time update check
  • OMX_AUTO_UPDATE=defer schedules the update without prompting
OMX_AUTO_UPDATE=0

Consider the Codex plugin option

The repository also ships an official Codex plugin layout at plugins/oh-my-codex. The README says this is not a replacement for the global oh-my-codex CLI plus scoped setup. Plugin mode still needs a persistent AGENTS.md as the durable guidance layer.

For most users, follow the global npm install and scoped setup path described above.

What people use it for

  • Planning and implementing a multi-step refactor, such as an authentication change with verification of login, logout and refresh-token behavior.
  • Running a separate review step with $code-review after changes are made.
  • Running a QA pass with $ultraqa on its own, without a fixed sequence.
  • Keeping project-specific guidance and plans in a .omx/ folder inside a repository.

Frequently asked questions

Is oh-my-codex free?

The project is released under the MIT licence, according to its repository. Codex CLI is a separate tool, and the README shows it can be installed with npm as @openai/codex. Check OpenAI's own terms for Codex access.

Do I need Codex CLI to use oh-my-codex?

Yes. OMX is described as a workflow layer for OpenAI Codex CLI. It needs a working, authenticated codex command on your PATH.

Does oh-my-codex work on Windows?

Native Windows is not the default experience according to the README, and it receives less support. The recommended setup is macOS or Linux with Codex CLI.

What is the EEXIST error when installing?

The README says a combined npm install of @openai/codex and oh-my-codex can fail with EEXIST if you already have a Homebrew-owned codex binary such as /opt/homebrew/bin/codex. Install oh-my-codex on its own in that case, since OMX only needs a working codex command.

Is oh-my-codex too heavy for simple tasks?

The README itself points to a lighter sibling project, gajae-code, for users who find OMX more than they need. It describes gajae-code as an SDK-based path that keeps Codex OAuth.

How does oh-my-codex compare with plain Codex CLI?

According to the README, OMX keeps Codex as the execution engine and adds a consistent workflow with commands like $plan, $team and $code-review, plus project state in .omx/. Plain Codex CLI works without that structure, so OMX suits longer tasks that benefit from it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OMX suits developers who already use Codex CLI on macOS or Linux and want planning, review and QA steps on larger tasks, with project guidance kept in AGENTS.md and .omx/. If you do not use Codex CLI, use Windows natively, or find a heavy workflow layer unnecessary, plain Codex CLI or the lighter gajae-code project is the better fit.

Install options & downloads