# 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 setup leaves `model_context_window` and `model_auto_compact_token_limit` unset so Codex uses the active model defaults. Rerunning setup removes only unchanged legacy values proven to have been seeded by OMX and preserves explicit, unmarked, and edited values.

## 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.

### AGENTS merge policy

Use only the bare selectors `--merge-agents`, `--no-merge-agents`, or `--clear-merge-agents-policy`. An explicit set overrides saved policy; conflicting set/clear choices fail before setup mutations. A successful explicit set stores the choice per working root in `./.omx/setup-scope.json`, including for `--scope user`; it is not a global user preference. Valid matching policies are replayed by both immediate and deferred `omx update` refreshes.

`--merge-agents` takes the existing merge branch. `--no-merge-agents` only suppresses that branch; it does not guarantee preservation or replacement, so existing prompt, skip, managed-refresh, plugin-default, and force behavior remains. Review preserves a matching policy while unrelated settings change. Reset or a scope change removes the inherited policy unless the same run explicitly sets it; clear always removes the policy and cannot be combined with a set selector. Malformed, unknown, nonboolean, or wrong-scope stored data is ignored safely.

`--force` is independent and is never persisted or replayed. Setup atomically commits explicit set or clear intent only after all setup work succeeds; successful guarded setup still records it as future intent when an active-session or plugin-symlink safeguard skips the current write. This does not make merge the default or adopt the rejected #2892 merge-by-default behavior. Older OMX versions can ignore this field safely, but can erase it when rewriting setup preferences.

`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

Issue | What to check
--- | ---
`omx` command not found | Re-run global install and ensure npm global bin is in PATH.
Prompts not available | Confirm files exist in `~/.codex/prompts/` and re-run the matching scoped setup command.
Skills not loading | Verify `~/.codex/skills/*/SKILL.md` files were installed.
Doctor reports config issues | Run `omx doctor` and apply the suggested fixes.
Doctor is green but execution fails | Run `codex login status` and `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"` from the same shell/profile. A green doctor is install evidence, not proof of authenticated model execution.
Custom or profile HOME cannot authenticate | Check the active `~/.codex` or `CODEX_HOME`. Containers, profile shells, and service users may not see the same auth/config as your normal user home.
Local proxy or compatible endpoint returns 401 | If you use a proxy, verify the active `~/.codex/config.toml` contains the expected `openai_base_url`. Proxy keys sent to the wrong endpoint can look like missing bearer auth or an incorrect API key.
`omx doctor --team` sees a dead tmux team | If the team is intentionally abandoned, run `omx team shutdown <team-name> --force --confirm-issues`, then `omx cancel`, then `omx doctor --team`.

Need deeper operator help? See Troubleshooting execution readiness.