Getting Started

Install Codex CLI, install oh-my-codex, run omx setup, and invoke your first automated workflow.

oh-my-codex (OMX) is a workflow layer for OpenAI Codex CLI. It keeps Codex as the execution engine and wraps it with role-specific agent prompts, reusable skills, and event-driven hooks so you can go from a vague idea to working code in one consistent loop. This page walks you through installing OMX, verifying the setup, and running your first session.

Prerequisites

Node.js 22+ (20+ is the minimum; 22 is recommended)
Codex CLI installed and authenticated (npm i -g @openai/codex, then codex login)
macOS or Linux — OMX is primarily designed and actively tuned for these platforms. Native Windows may break or behave inconsistently and currently receives less support.
tmux (macOS/Linux) if you want the durable team runtime

Install

Install Codex CLI

npm install -g @openai/codex

Then authenticate:

codex login

Install OMX

npm install -g oh-my-codex

Run setup

omx setup

omx setup wires the Codex-native hooks by writing .codex/config.toml (enables codex_hooks = true) and .codex/hooks.json (registers the OMX hook command). It also creates the .omx/ project-state directory and configures the session prompt with OMX agent context.

Verify the installation

omx doctor

omx doctor checks that all required files exist and are shaped correctly. To also prove the active Codex profile can complete a real model call, run:

codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

First run

Open a new Codex session and try the canonical autopilot skill:

codex
> $autopilot build me a todo app in next.js

What happens under the hood:

The UserPromptSubmit hook detects the $autopilot magic keyword and activates the skill.
OMX routes to $deep-interview to clarify requirements before touching any code.
Once requirements are confirmed, $ralplan drafts and validates a plan with consensus.
executor carries out the implementation step-by-step.
$ultraqa runs a QA iteration loop — test, verify, fix — until the acceptance criteria pass.
verifier collects final evidence and confirms completion.

You can also launch OMX directly with the recommended flags:

omx --madmax --high

Next steps

Core Concepts — understand the agent/skill/hook separation before going deeper
Agents catalog — 33 role-specific prompts across four lanes
Skills catalog — 37 one-shot workflow and utility skills
Integrations — connect OMX to external tooling

Was this page helpful?

Edit this page Report an issue

On this page