Quickstart

Follow this page when you want the shortest reliable path from a clean machine to a working OMX session.

OMX runs on top of OpenAI Codex CLI. Install Codex first, then add OMX as the orchestration layer for guided interviews, planning, execution, teams, and verification.

Prerequisites

Item	Requirement
Node.js	22+ recommended, 20+ minimum
Codex CLI	Installed and authenticated
OS	macOS or Linux recommended
tmux	Required for durable team sessions

Native Windows can be inconsistent for the current OMX runtime. Prefer macOS, Linux, WSL, or a remote Linux development host when possible.

Setup

Choose the setup path that matches the way you want to use OMX first.

Local session recommended

Use this path for the first real task in a repository.

Install Codex CLI

npm install -g @openai/codex
codex login

Install OMX

npm install -g oh-my-codex
omx setup

Check the install

omx doctor
codex login status

Launch the leader session

omx --madmax --high

Team runtime

Use this path when a plan needs multiple coordinated lanes or work should survive tmux panes.

npm install -g @openai/codex oh-my-codex
codex login
omx setup
omx --tmux --madmax --high

Then start parallel execution only after the task is clear enough to split:

$team 3:executor "execute the approved plan in parallel"

Verification-only smoke test

Use this path when you only need to prove that the CLI, auth, and model call path work.

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

The expected response is exactly OMX-EXEC-OK.

--madmax bypasses Codex approvals and sandboxing. Use it only in repositories and environments where that execution boundary is intentional.

First session

For your first useful session, send a small but realistic task and walk through the guided default flow.

$deep-interview "clarify the authentication change"
$ralplan "approve the safest implementation path"
$ultragoal "turn the approved plan into durable goals and complete them"

Each command owns a different stage.

Stage	What it does
`$deep-interview`	Clarifies fuzzy requirements before code changes begin
`$ralplan`	Produces a safer implementation and test plan
`$ultragoal`	Turns the approved plan into durable goals, ledger evidence, and completion checkpoints

If the approved plan is naturally parallel, replace the final command with:

$team 3:executor "execute the approved plan in parallel"

Example first prompts

$deep-interview "help me scope a safer signup flow change"
$ralplan "plan the least risky way to add this report export"
$ultragoal "split the approved report export plan into durable goals and complete them"

Quickstart

On this page