Getting Started

End-to-end setup for first-time users.

Prerequisites

• Node.js 20+ and npm.
• OpenAI Codex CLI installed, verified with codex --version, and authenticated (Homebrew or npm are both supported).
• Git (recommended) for project workflows.

Installation

Official install target: use the oh-my-codex npm package from the official Yeachan-Heo/oh-my-codex repository. Third-party “OMX v2” projects are not official release lines for this project unless this repository documents that relationship.

Choose one install path. If Codex CLI is already installed (Homebrew, npm, or another supported method):

codex --version
npm install -g oh-my-codex
omx doctor

If you do not have Codex CLI yet and want npm to manage it:

npm install -g @openai/codex
npm install -g oh-my-codex
omx doctor

Do not run a combined npm install -g @openai/codex oh-my-codex over an existing Homebrew-owned codex binary such as /opt/homebrew/bin/codex; npm may fail with EEXIST when @openai/codex tries to create the same binary. OMX only needs a working, authenticated codex command on PATH; it does not require Codex to be installed through npm.

When oh-my-codex actually bumps to a newer version, the global npm install now prints an explicit reminder instead of launching setup automatically. When you're ready, rerun the scoped setup command below or use omx update to check npm and then run the same setup refresh path. OMX also checks for npm updates at launch on a throttled cadence and prompts before scheduling the update after the current session exits. Set OMX_AUTO_UPDATE=0 to disable the launch-time check, or OMX_AUTO_UPDATE=defer to schedule the deferred update without prompting. Fresh OMX-managed gpt-5.5 configs now recommend model_context_window = 250000 and model_auto_compact_token_limit = 200000 only when those keys are missing.

Setup Scope

Choose the setup scope deliberately. Use omx setup --scope project --merge-agents from the git project you want OMX to operate on when that repository should own durable AGENTS.md guidance. Use omx setup --scope user for user-level Codex setup when you are not preparing the current directory as an OMX project.

A broad home directory or operating hub is usually not the right target for project-scoped setup unless that directory is intentionally the project under review. Home-level AGENTS.md files often contain global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead.

omx doctor verifies the install shape. Before treating the runtime as ready, also prove that the active Codex profile can perform a real request:

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

Recommended Launch

omx --worktree=feat/task --madmax --xhigh # trusted git repo, named launch worktree
omx --worktree=fix/flaky-tests --madmax --xhigh   # concurrent trusted session, separate worktree
omx                                              # standard launch

--madmax maps to Codex --dangerously-bypass-approvals-and-sandbox, so use it only in trusted repositories and environments. Prefer a named --worktree=<name> with --madmax when launching from a git repository; if you are outside git, omit --worktree. For multiple concurrent --madmax sessions, give each session a distinct named worktree instead of sharing one checkout.

--worktree or -w with no name creates or reuses a detached launch worktree. Treat that unnamed form as a one-off convenience: after the source checkout advances, a later unnamed launch can fail with worktree_target_mismatch until the old detached worktree is removed. --worktree=<name>, --worktree <name>, or -w <name> creates or reuses a named launch worktree and branch. OMX consumes the worktree flag before starting Codex.

First Run Walkthrough

1. Create or enter a project directory.
2. Install or update OMX globally.
3. After install or real OMX version bumps, rerun the scoped setup command when you're ready, use omx update when you also want npm to update OMX first, or set OMX_AUTO_UPDATE=defer for no-prompt deferred launch-time updates.
4. Run omx doctor, then the codex login status plus omx exec smoke test above.
5. Start Codex CLI with omx --madmax --xhigh for a normal strong trusted session, or add --worktree=<task> when launching from a git repository.
6. Use $deep-interview "clarify the auth change" when intent or boundaries are still unclear.
7. Use $ralplan "approve the auth plan and review tradeoffs" to lock the implementation plan; hand off only after Architect review evidence and then Critic review evidence are recorded.
8. Choose $autopilot, $ultrawork, or $ralph as the execution spine when appropriate; add /goal when the task needs durable objective/checkpoint structure.

/goal and Skill Selection

Use /goal when Codex should keep a durable objective and checkpoint structure across turns. Start with a focused execution spine, then add only the relevant supporting skills.

omx --madmax --xhigh
/goal Ship the checkout bug fix with checkpoints for reproduction, implementation, regression tests, and final verification.
$ralplan "approve the checkout bug-fix plan and review tradeoffs"
$ultrawork "execute the approved checkout fix with checkpoint evidence"

By default, add only 2-5 relevant skills. More is allowed when the task scope justifies it, but loading a large catalog is usually a context-budget and attention-quality problem, not a hard parser/runtime blocker unless a concrete command errors.

# Anti-pattern: loading 20 skills by default before the task is known.
omx --madmax --xhigh
# /skills: add 20 unrelated skills "just in case"

Prompt Instruction Source

OMX layers project instructions by default (extends Codex behavior, does not replace/bypass Codex core system policies):

-c model_instructions_file="<cwd>/AGENTS.md"

Override behavior when needed:

OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx
OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx

Troubleshooting

Need deeper operator help? See Troubleshooting execution readiness.