oh-my-codex/docs/getting-started.html at main · cristph/oh-my-codex · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Getting Started - oh-my-codex Docs</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <header>
      <nav class="container nav" aria-label="Primary">
        <a class="brand" href="./index.html">oh-my-codex</a>
        <a href="./index.html">Home</a>
        <a class="active" href="./getting-started.html">Getting Started</a>
        <a href="./agents.html">Agents</a>
        <a href="./skills.html">Skills</a>
        <a href="./integrations.html">Integrations</a>
      </nav>
    </header>

    <main class="container">
      <h1>Getting Started</h1>
      <p class="muted">End-to-end setup for first-time users.</p>

      <h2>Prerequisites</h2>
      <ul>
        <li>Node.js 20+ and npm.</li>
        <li>OpenAI Codex CLI installed, verified with <code>codex --version</code>, and authenticated (Homebrew or npm are both supported).</li>
        <li>Git (recommended) for project workflows.</li>
      </ul>

      <h2>Installation</h2>
      <p><strong>Official install target:</strong> use the <a href="https://www.npmjs.com/package/oh-my-codex"><code>oh-my-codex</code></a> npm package from the official <a href="https://github.com/Yeachan-Heo/oh-my-codex"><code>Yeachan-Heo/oh-my-codex</code></a> repository. Third-party “OMX v2” projects are not official release lines for this project unless this repository documents that relationship.</p>
      <p>Choose one install path. If Codex CLI is already installed (Homebrew, npm, or another supported method):</p>
      <pre><code>codex --version
npm install -g oh-my-codex
omx doctor</code></pre>
      <p>If you do not have Codex CLI yet and want npm to manage it:</p>
      <pre><code>npm install -g @openai/codex
npm install -g oh-my-codex
omx doctor</code></pre>
      <p>Do not run a combined <code>npm install -g @openai/codex oh-my-codex</code> over an existing Homebrew-owned <code>codex</code> binary such as <code>/opt/homebrew/bin/codex</code>; npm may fail with <code>EEXIST</code> when <code>@openai/codex</code> tries to create the same binary. OMX only needs a working, authenticated <code>codex</code> command on <code>PATH</code>; it does not require Codex to be installed through npm.</p>
      <p>When <code>oh-my-codex</code> 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 <code>omx update</code> 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 <code>OMX_AUTO_UPDATE=0</code> to disable the launch-time check, or <code>OMX_AUTO_UPDATE=defer</code> to schedule the deferred update without prompting. Fresh setup leaves <code>model_context_window</code> and <code>model_auto_compact_token_limit</code> 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.</p>
      <h2>Setup Scope</h2>
      <p>Choose the setup scope deliberately. Use <code>omx setup --scope project --merge-agents</code> from the git project you want OMX to operate on when that repository should own durable <code>AGENTS.md</code> guidance. Use <code>omx setup --scope user</code> for user-level Codex setup when you are not preparing the current directory as an OMX project.</p>
      <p>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 <code>AGENTS.md</code> files often contain global safety and routing rules; keep project-specific OMX runtime guidance in the real repository instead.</p>
      <p><code>omx doctor</code> verifies the install shape. Before treating the runtime as ready, also prove that the active Codex profile can perform a real request:</p>
      <pre><code>codex login status
omx exec --skip-git-repo-check -C . &quot;Reply with exactly OMX-EXEC-OK&quot;</code></pre>

      <h2>Recommended Launch</h2>
      <pre><code>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</code></pre>
      <p><code>--madmax</code> maps to Codex <code>--dangerously-bypass-approvals-and-sandbox</code>, so use it only in trusted repositories and environments. Prefer a named <code>--worktree=&lt;name&gt;</code> with <code>--madmax</code> when launching from a git repository; if you are outside git, omit <code>--worktree</code>. For multiple concurrent <code>--madmax</code> sessions, give each session a distinct named worktree instead of sharing one checkout.</p>
      <p><code>--worktree</code> or <code>-w</code> 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 <code>worktree_target_mismatch</code> until the old detached worktree is removed. <code>--worktree=&lt;name&gt;</code>, <code>--worktree &lt;name&gt;</code>, or <code>-w &lt;name&gt;</code> creates or reuses a named launch worktree and branch. OMX consumes the worktree flag before starting Codex.</p>

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

      <h2><code>/goal</code> and Skill Selection</h2>
      <p>Use <code>/goal</code> 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.</p>
      <pre><code>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"</code></pre>
      <p>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.</p>
      <pre><code># Anti-pattern: loading 20 skills by default before the task is known.
omx --madmax --xhigh
# /skills: add 20 unrelated skills "just in case"</code></pre>

      <h2>Prompt Instruction Source</h2>
      <p>OMX layers project instructions by default (extends Codex behavior, does not replace/bypass Codex core system policies):</p>
      <pre><code>-c model_instructions_file="&lt;cwd&gt;/AGENTS.md"</code></pre>
      <p>Override behavior when needed:</p>
      <pre><code>OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx
OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx</code></pre>

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

    <footer>
      <div class="container">
        <span class="muted">Need broader context? Start from the project README.</span>
      </div>
    </footer>
  </body>
</html>