From 62ff23f956f56842fa607c3649370ce1893317bb Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sun, 31 May 2026 06:04:05 +0900 Subject: [PATCH] docs(codex): document windows git bash requirement Plan: plans/codex-windows-git-bash-profile.md --- docs/guide/installation.md | 39 +++++++++++++++++++++++++++++++++ docs/reference/configuration.md | 1 + packages/omo-codex/README.md | 19 ++++++++++++++++ 3 files changed, 59 insertions(+) diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 51da23715..80d68278c 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -42,6 +42,25 @@ bunx lazycodex install --no-tui --codex-autonomous It writes only to `~/.codex/`. No OpenCode interaction, no provider flags. Codex config will register marketplace `sisyphuslabs` from the local built cache under `~/.codex/plugins/cache/sisyphuslabs` and enable plugin `omo@sisyphuslabs`. +On native Windows Codex installs, install Git Bash first: + +```powershell +winget install --id Git.Git -e --source winget +where bash +``` + +If Git is installed somewhere custom, set the path before rerunning the installer: + +```cmd +setx OMO_CODEX_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" +``` + +```powershell +$env:OMO_CODEX_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe" +``` + +Codex may still start Windows shell calls through its own defaults. The Light edition does not write a global Codex shell config; instead it verifies Git Bash is available and injects Windows guidance telling Codex to use Git Bash for shell commands. + > **Clean install note for oh-my-codex / omx users.** Before installing the Light edition into a Codex home that previously used [`oh-my-codex`](https://github.com/Yeachan-Heo/oh-my-codex), uninstall it first with `omx uninstall`, then re-run this installer. Both projects write Codex marketplace plugins, lifecycle hooks, and the `ultrawork`/`ulw` keyword into the same `~/.codex`, so a clean Codex home avoids stale shared `config.toml` keys and duplicate hooks. > > If the uninstall command is unavailable, remove the old Codex plugin/cache entries it created under `~/.codex/`, then run `bunx omo install --platform=codex` again. @@ -175,6 +194,23 @@ fi The installer expects `~/.codex/` to be writable. Codex CLI's first run creates this directory; if it does not exist yet, install Codex CLI and run it once before continuing. +On native Windows Codex installs, Git Bash is also required: + +```powershell +winget install --id Git.Git -e --source winget +where bash +``` + +For a custom Git Bash location, set `OMO_CODEX_GIT_BASH_PATH`: + +```cmd +setx OMO_CODEX_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" +``` + +```powershell +$env:OMO_CODEX_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe" +``` + ### Step 2: Run the installer Run with the platform flag and the subscription flags you collected in Step 0: @@ -267,6 +303,9 @@ ls ~/.local/bin/ | grep -E '^(omo|omo-(comment-checker|lsp|rules|start-work-cont # Codex CLI sees the plugin? codex --help + +# On native Windows, Git Bash is discoverable? +where bash ``` If any of these come back empty, re-run `bunx omo install --platform=codex` — the installer is idempotent and will recompute hook trust hashes. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 7c4f31ebf..13ea0570d 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1009,6 +1009,7 @@ When enabled, OmO registers the hash-anchored `edit` tool and activates the `has | `OMO_DISABLE_POSTHOG` | Legacy telemetry opt-out flag. Set to `1` or `true` to disable PostHog | | `OMO_CODEX_DISABLE_POSTHOG` | Set to `1` or `true` to disable PostHog telemetry for the `omo-codex` adapter only. Does not affect oh-my-opencode telemetry | | `OMO_CODEX_SEND_ANONYMOUS_TELEMETRY` | Set to `0`, `false`, or `no` to disable anonymous telemetry for `omo-codex` only | +| `OMO_CODEX_GIT_BASH_PATH` | Native Windows Codex installs only. Absolute path to Git Bash, for example `C:\Program Files\Git\bin\bash.exe`, when `where bash` cannot find it | | `POSTHOG_API_KEY` | Optional override for the built-in PostHog project API key | | `POSTHOG_HOST` | Override the PostHog ingestion host. Defaults to `https://us.i.posthog.com` | diff --git a/packages/omo-codex/README.md b/packages/omo-codex/README.md index e8b47e459..892ad10d9 100644 --- a/packages/omo-codex/README.md +++ b/packages/omo-codex/README.md @@ -39,6 +39,25 @@ To install **both** the Ultimate edition (OpenCode plugin) and the Light edition The installer copies the built plugin into `~/.codex/plugins/cache/sisyphuslabs/omo//`, writes stable agent TOML links through `~/.codex/.tmp/marketplaces/sisyphuslabs/plugins/omo/`, enables `omo@sisyphuslabs` in `~/.codex/config.toml`, and registers the `sisyphuslabs` marketplace from the local built cache. `lazycodex` is the repo/npm/bin alias; the marketplace identity remains `sisyphuslabs`. +Native Windows installs require Git Bash before the installer mutates `~/.codex/`: + +```powershell +winget install --id Git.Git -e --source winget +where bash +``` + +For a custom Git Bash location: + +```cmd +setx OMO_CODEX_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" +``` + +```powershell +$env:OMO_CODEX_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe" +``` + +The installer does not write a global Codex shell config. The rules component injects conditional Windows guidance telling Codex to use Git Bash for shell commands. + To install both editions in one command, use `--platform=both`. ## Telemetry