docs(codex): document windows git bash requirement

Plan: plans/codex-windows-git-bash-profile.md
2026-05-31 06:04:05 +09:00
parent 644be5df7a
commit 62ff23f956
3 changed files with 59 additions and 0 deletions
@@ -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.
@@ -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` |

@@ -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/<version>/`, 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