codex-grok-bridge 1.0.4 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## Unreleased
+
+## 1.5.0 — 2026-09-12
+
+First cut that accepts **Windows** (`"os": ["darwin", "linux", "win32"]`).
+
+- Isolated win32 wrapper under `%LOCALAPPDATA%\codex-grok-bridge`. Never writes WindowsApps.
+- Launch reads a Store ChatGPT / `resources/codex.exe` pointer when the isolated copies are missing.
+- Grok 4.7 drop prep: any `grok-*` id uses the Grok provider. Extra catalog slugs via `GROK_BRIDGE_MODELS`.
+- UTM Windows 11 ARM64 guest: Node 22.23.2, `node --test` 157/0/3 on 1.5.0, official ChatGPT ARM64 MSIX `OpenAI.Codex_26.903.8094.0`, bundled CLI `codex-cli 0.153.4`, grok 1.0.25, loopback `/v1/models` 200. See `docs/windows-arm64-guest.md`.
+
+Install: `npm install -g codex-grok-bridge@1.5.0`
+
+## 1.0.5 — 2026-09-12
+
+First npm cut that accepts **Linux** (`"os": ["darwin", "linux"]`). Windows stays rejected.
+
+- Input field allowlist for Grok Responses (`#10`) — drops `internal_*` and other fields Grok rejects.
+- Collapse `anyOf` / `oneOf` tool-parameter roots to a plain object (`#12`) — unblocks Linux GUI `invalid_client_tool_schema` 400s.
+- Linux desktop wrapper (`#11`) — `~/.local/share/codex-grok-bridge/app` plus a user `.desktop` file. Does not patch `/usr/lib/chatgpt`.
+- Docs: test gate **150/150**, coverage 97.30 / 87.70 / 90.57, Grok CLI verified **1.0.25**.
+
+Install: `npm install -g codex-grok-bridge@1.0.5`
+
+## 1.0.4 — 2026-09-09
+
+English and Korean README aligned. macOS-only npm package.
+
+## 1.0.3 — 2026-09-09
+
+See GitHub release `v1.0.3`.
+
+## 1.0.2 — 2026-09-09
+
+See GitHub release `v1.0.2`.
+
+## 1.0.1 — 2026-09-09
+
+See GitHub release `v1.0.1`.
+
+## 1.0.0 — 2026-09-09
+
+Initial publish. macOS only.

package/README.md

@@ -4,10 +4,6 @@ Run **Grok 4.6 as the model inside Codex**. Codex still owns tools, permissions,
 history and MCP. Inference uses the installed `grok` CLI login session — not an
 xAI API key.
 
-Codex 안에서 **Grok 4.6**을 모델로 씁니다. 도구·권한·히스토리·MCP는 Codex가
-그대로 가집니다. 추론은 설치된 `grok` CLI의 로그인 세션으로 하며 `XAI_API_KEY`는
-쓰지 않습니다.
-
 ```
 Codex UI/CLI → app-server → scripts/codex-wrapper.mjs (adds grok-4.6 to the model list)
              → localhost /v1/responses (the bridge)
@@ -15,16 +11,13 @@ Codex UI/CLI → app-server → scripts/codex-wrapper.mjs (adds grok-4.6 to the
              → Codex executes every tool call; results return as the next input
 ```
 
-The published package is **macOS-only** (`"os": ["darwin"]`). Linux and Windows
-installs are rejected by npm.
+The published npm package installs on **macOS, Linux, and Windows** (`"os":
+["darwin", "linux", "win32"]`) starting at 1.5.0. Official ChatGPT/Codex
+prefixes stay untouched; `scripts/install-codex-grok-app.sh` and
+`scripts/install-codex-grok-app.ps1` write a separate wrapper.
 
-게시된 패키지는 **macOS 전용**입니다(`"os": ["darwin"]`). Linux·Windows는 npm이
-설치를 거절합니다.
 
 ---
-
-# English
-
 ## What this is
 
 A local bridge that puts Grok 4.6 on Codex’s model list and sends Codex
@@ -36,25 +29,27 @@ The bridge does **not** execute Grok-native tools. It translates Codex tools int
 function calling, streams the upstream Responses events, and rewrites names back
 so Codex still recognizes them.
 
-Thirteen files under `src/`. Zero runtime dependencies. Node.js ≥ 22.
+Fourteen files under `src/`. Zero runtime dependencies. Node.js ≥ 22.
 
-This is not a second-opinion review product, not a Grok 4.7 adapter, and not a
-Grok-native search product. If Codex exposes a web-search tool, Grok can call
+This is not a second-opinion review product and not a Grok-native search
+product. New Grok ids, including 4.7 when the CLI lists them, use the same
+`grok-*` route. Set `GROK_BRIDGE_MODELS=grok-4.7` to show extras in the catalog
+before they are the default. If Codex exposes a web-search tool, Grok can call
 that tool the same way it calls any other Codex tool.
 
 ## Requirements
 
-- macOS
+- macOS, Linux, or Windows 11 with the official ChatGPT/Codex desktop package
 - Node.js ≥ 22
-- `/Applications/Codex.app`
-- `grok` CLI at `~/.grok/bin/grok`
+- `/Applications/Codex.app` (macOS), `/usr/lib/chatgpt/ChatGPT` (Linux), or the official ChatGPT MSIX (Windows)
+- `grok` CLI at `~/.grok/bin/grok` (Windows: `%USERPROFILE%\.grok\bin\grok.exe`)
 - a completed `grok login`
 
 The `.command` launcher resolves paths from its own location, so moving the
 folder does not require edits. Set `NODE=/path/to/node` if `node` is not on
 `PATH`.
 
-Verified against: Codex 0.153.4 / app 26.901.51231, Grok CLI 1.0.24, Node 22.23.0.
+Verified against: Codex 0.153.4 / app 26.901.51231, Grok CLI 1.0.25, Node 22.23.0.
 An app update that changes `CODEX_CLI_PATH` or the app-server protocol needs
 re-verification.
 
@@ -63,7 +58,7 @@ re-verification.
 ### Terminal (npm)
 
 ```sh
-npm install -g codex-grok-bridge   # macOS, Node ≥ 22
+npm install -g codex-grok-bridge   # macOS, Linux, or Windows; Node ≥ 22
 codex-grok                         # launches Codex with Grok 4.6 available
 codex-grok exec --skip-git-repo-check --sandbox workspace-write 'your task'
 ```
@@ -76,15 +71,18 @@ starts, and tears the provider down with that process.
 ```sh
 git clone https://github.com/deximple/codex-grok-bridge.git
 cd codex-grok-bridge
-npm test                        # 132 tests, no network, no inference
+npm test                        # 160 tests, no network, no inference
 node scripts/codex-grok.mjs
 ```
 
 ### Desktop
 
 Double-click **Open Codex with Grok.command** in this folder, or keep a
-**separate** `Codex Grok.app` in sync with
+**separate** desktop wrapper in sync with
 `scripts/install-codex-grok-app.sh` (see [Desktop install and update](#desktop-install-and-update)).
+On Linux that wrapper is `~/.local/share/codex-grok-bridge/app` plus a user
+`.desktop` entry; the stock `/usr/lib/chatgpt` tree is not patched. On Windows
+it is `%LOCALAPPDATA%\codex-grok-bridge`; `WindowsApps` is never written.
 
 In the new Codex window, **select Grok 4.6 / xAI before starting a new
 thread**. Existing GPT models stay on the list. A Codex window that was already
@@ -95,9 +93,9 @@ The dedicated window stores UI data under
 for account, threads and settings. Work and setting changes can show up in other
 Codex windows.
 
-The installer never writes the stock Codex.app bundle, its signature,
-`~/.codex/config.toml`, or Grok auth files. It does not register a launch
-agent or a global environment variable.
+The installer never writes the stock Codex.app bundle, `/usr/lib/chatgpt`,
+their signatures, `~/.codex/config.toml`, or Grok auth files. It does not
+register a launch agent or a global environment variable.
 
 Stop by closing the Codex window this extension opened. Ordinary Codex still
 launches from its usual icon.
@@ -163,7 +161,10 @@ not read Codex’s `imagegen` skill and do not send the picture to OpenAI.
 Plain-text summaries on Codex `reasoning` items are forwarded. Encrypted
 `encrypted_content` and Codex’s own item ids are stripped. This is so a
 multi-call turn can continue its own reasoning. The upstream has been observed
-to accept this shape.
+to accept this shape. The same pass keeps only the fields Grok’s Responses
+input accepts on each item and content part — `status`, unknown Codex keys,
+and every `internal_*` field are dropped so a new client field cannot 422 the
+upstream.
 
 ### Concurrency
 
@@ -279,13 +280,14 @@ Start here when something breaks. Do not open `~/.grok/auth.json` or
 | `GROK_BRIDGE_TRANSPORT=fetch` | Use Node `fetch` instead of `node:http(s)` |
 | `GROK_BRIDGE_INFERENCE=cli` | Fall back to the CLI envelope path |
 | `GROK_BRIDGE_DIAGNOSTICS=off` | Do not write the JSONL log |
+| `GROK_BRIDGE_MODELS` | Extra `grok-*` catalog ids (comma or space), e.g. `grok-4.7` |
 | `NODE` | Absolute `node` binary for the `.command` launcher / desktop scripts |
-| `CODEX_GROK_APP` | Alternate app bundle path for `install-codex-grok-app.sh` (default `/Applications/Codex Grok.app`) |
+| `CODEX_GROK_APP` | Alternate app path for the desktop installer (macOS: `/Applications/Codex Grok.app`; Linux: `~/.local/share/codex-grok-bridge/app`; Windows: `%LOCALAPPDATA%\codex-grok-bridge\app`) |
 
 ## Verify
 
 ```sh
-npm test                    # 132 tests, no remote inference
+npm test                    # 160 tests, no remote inference
 npm run test:coverage       # 80% line / branch / function gate
 npm run verify:app-server   # real app-server routing; also runs against an installed bundle
 npm audit --omit=dev
@@ -299,7 +301,8 @@ inference. A live CLI check spends the user’s quota.
 
 ```sh
 sh scripts/install-codex-grok-app.sh          # sync bridge JS only (default)
-sh scripts/install-codex-grok-app.sh --full   # also rebuild and sign the launcher applet
+sh scripts/install-codex-grok-app.sh --full   # macOS: rebuild and sign the launcher applet
+powershell -File scripts/install-codex-grok-app.ps1
 ```
 
 The default copies this checkout’s `src/` and `scripts/*.mjs` into the bundle,
@@ -308,8 +311,14 @@ never `rm -rf`s the live bundle. It refuses while a Codex Grok window is open
 (`--force` to override). ESM is not hot-reloaded: **reopen the window** after a
 sync.
 
-The script updates an existing `Codex Grok.app`. It does not create one, and it
-does not touch `/Applications/Codex.app`.
+On macOS the script updates an existing `Codex Grok.app`. It does not create
+one, and it does not touch `/Applications/Codex.app`. On Linux it creates
+`~/.local/share/codex-grok-bridge/app` and
+`~/.local/share/applications/codex-grok.desktop`, and it does not write
+`/usr/lib/chatgpt` or `/usr/share/applications/chatgpt.desktop`. On Windows
+`scripts/install-codex-grok-app.ps1` writes
+`%LOCALAPPDATA%\codex-grok-bridge` and may point at a Store `ChatGPT.exe` /
+`resources\codex.exe`; it never writes `WindowsApps`.
 
 ## Security notes
 
@@ -347,24 +356,26 @@ Grok 4.6을 Codex 모델 목록에 넣고, Codex의 `/v1/responses`를
 calling으로 옮기고, 상류 Responses 스트림을 전달한 뒤, Codex가 알아보는
 이름으로 되돌립니다.
 
-`src/` 아래 파일 13개. 런타임 의존성 없음. Node.js 22 이상.
+`src/` 아래 파일 14개. 런타임 의존성 없음. Node.js 22 이상. 1.5.0부터 npm
+`"os"`는 `darwin` / `linux` / `win32`입니다.
 
-코드 리뷰 전용 제품이 아니고, Grok 4.7 어댑터도 아니며, Grok 네이티브 검색
-제품도 아닙니다. Codex가 웹 검색 도구를 노출하면 Grok은 다른 Codex 도구와 같이
-그 도구를 호출할 수 있습니다.
+코드 리뷰 전용 제품이 아니고 Grok 네이티브 검색 제품도 아닙니다. CLI가 새
+id(4.7 포함)를 내놓으면 같은 `grok-*` 경로로 붙습니다. 기본 카탈로그에 먼저
+보이게 하려면 `GROK_BRIDGE_MODELS=grok-4.7`을 씁니다. Codex가 웹 검색 도구를
+노출하면 Grok은 다른 Codex 도구와 같이 그 도구를 호출할 수 있습니다.
 
 ## 필요한 것
 
-- macOS
+- macOS, Linux, 또는 공식 ChatGPT/Codex 데스크톱이 있는 Windows 11
 - Node.js 22 이상
-- `/Applications/Codex.app`
-- `~/.grok/bin/grok`
+- `/Applications/Codex.app` (macOS), `/usr/lib/chatgpt/ChatGPT` (Linux), 또는 공식 ChatGPT MSIX (Windows)
+- `~/.grok/bin/grok` (Windows: `%USERPROFILE%\.grok\bin\grok.exe`)
 - 완료된 `grok login`
 
 `.command` 런처는 자기 위치를 기준으로 경로를 잡으므로 폴더를 옮겨도 수정할
 필요가 없습니다. `PATH`에 `node`가 없으면 `NODE=/path/to/node`로 지정합니다.
 
-검증 버전: Codex 0.153.4 / 앱 26.901.51231, Grok CLI 1.0.24, Node 22.23.0.
+검증 버전: Codex 0.153.4 / 앱 26.901.51231, Grok CLI 1.0.25, Node 22.23.0.
 앱 업데이트가 `CODEX_CLI_PATH`나 app-server 프로토콜을 바꾸면 재검증이
 필요합니다.
 
@@ -373,7 +384,7 @@ calling으로 옮기고, 상류 Responses 스트림을 전달한 뒤, Codex가
 ### 터미널 (npm)
 
 ```sh
-npm install -g codex-grok-bridge   # macOS, Node ≥ 22
+npm install -g codex-grok-bridge   # macOS, Linux, Windows; Node ≥ 22
 codex-grok                         # Grok 4.6이 있는 Codex를 띄움
 codex-grok exec --skip-git-repo-check --sandbox workspace-write '작업 내용'
 ```
@@ -386,15 +397,18 @@ codex-grok exec --skip-git-repo-check --sandbox workspace-write '작업 내용'
 ```sh
 git clone https://github.com/deximple/codex-grok-bridge.git
 cd codex-grok-bridge
-npm test                        # 132건, 네트워크·추론 없음
+npm test                        # 160건, 네트워크·추론 없음
 node scripts/codex-grok.mjs
 ```
 
 ### 데스크톱
 
 이 폴더의 **Open Codex with Grok.command**를 더블 클릭하거나,
-`scripts/install-codex-grok-app.sh`로 **별도의** `Codex Grok.app`을 체크아웃과
+`scripts/install-codex-grok-app.sh`로 **별도의** 데스크톱 래퍼를 체크아웃과
 맞춥니다([데스크톱 설치와 갱신](#데스크톱-설치와-갱신)).
+Linux에서는 `~/.local/share/codex-grok-bridge/app`과 사용자 `.desktop`이고,
+정품 `/usr/lib/chatgpt`는 패치하지 않습니다. Windows에서는
+`%LOCALAPPDATA%\codex-grok-bridge`이고 `WindowsApps`는 쓰지 않습니다.
 
 새로 열린 Codex 창에서 **새 작업을 시작하기 전에 Grok 4.6 / xAI를 선택**하세요.
 기존 GPT 모델도 목록에 남습니다. 이미 열려 있던 일반 Codex 창에는 이 확장이
@@ -404,9 +418,9 @@ node scripts/codex-grok.mjs
 계정·작업·설정은 기존 Codex 홈을 **공유**합니다. 작업 내용과 설정 변경은 다른
 Codex 창에도 보일 수 있습니다.
 
-설치 스크립트는 정품 Codex.app 번들, 코드 서명, `~/.codex/config.toml`, Grok
-인증 파일을 수정하지 않습니다. 자동 시작 서비스나 전역 환경변수도 등록하지
-않습니다.
+설치 스크립트는 정품 Codex.app 번들, `/usr/lib/chatgpt`, 코드 서명,
+`~/.codex/config.toml`, Grok 인증 파일을 수정하지 않습니다. 자동 시작
+서비스나 전역 환경변수도 등록하지 않습니다.
 
 중지하려면 이 확장으로 연 Codex 창을 닫으면 됩니다. 일반 Codex는 기존 아이콘으로
 실행합니다.
@@ -468,7 +482,9 @@ OpenAI로 보내지 말라는 뜻입니다. `GROK_BRIDGE_IMAGE_GEN=off`면 도
 Codex `reasoning` 항목의 평문 요약은 상류로 전달합니다. 암호화된
 `encrypted_content`와 Codex 자체 아이템 id는 제거합니다. 여러 번 호출이 이어지는
 턴에서 모델이 자기 추론을 이어받게 하기 위한 것이며, 상류가 이 형태를 수락하는
-것을 확인했습니다.
+것을 확인했습니다. 같은 과정에서 아이템과 content part는 Grok Responses가
+받는 필드만 남깁니다. `status`, 알 수 없는 Codex 키, `internal_*` 필드는
+버려서 새 클라이언트 필드가 상류 422를 내지 않게 합니다.
 
 ### 동시성
 
@@ -579,13 +595,14 @@ provider에 Codex `request_max_retries` / `stream_max_retries`를 2로 두어
 | `GROK_BRIDGE_TRANSPORT=fetch` | `node:http(s)` 대신 Node `fetch` |
 | `GROK_BRIDGE_INFERENCE=cli` | CLI 봉투 경로로 폴백 |
 | `GROK_BRIDGE_DIAGNOSTICS=off` | JSONL 로그를 쓰지 않음 |
+| `GROK_BRIDGE_MODELS` | 카탈로그에 더할 `grok-*` id (쉼표/공백). 예: `grok-4.7` |
 | `NODE` | `.command` / 데스크톱 스크립트가 쓸 `node` 절대 경로 |
-| `CODEX_GROK_APP` | `install-codex-grok-app.sh`가 쓸 앱 번들 경로 (기본 `/Applications/Codex Grok.app`) |
+| `CODEX_GROK_APP` | 데스크톱 설치기가 쓸 앱 경로 (macOS: `/Applications/Codex Grok.app`; Linux: `~/.local/share/codex-grok-bridge/app`; Windows: `%LOCALAPPDATA%\codex-grok-bridge\app`) |
 
 ## 검증
 
 ```sh
-npm test                    # 132건, 외부 추론 없음
+npm test                    # 160건, 외부 추론 없음
 npm run test:coverage       # line/branch/function 80% 게이트
 npm run verify:app-server   # 실제 app-server 라우팅. 설치된 앱 번들에서도 실행
 npm audit --omit=dev
@@ -599,7 +616,8 @@ CLI 검증은 사용자 계정 사용량을 씁니다.
 
 ```sh
 sh scripts/install-codex-grok-app.sh          # 브리지 JS만 동기화 (기본)
-sh scripts/install-codex-grok-app.sh --full   # 런처 applet 재빌드 + 서명
+sh scripts/install-codex-grok-app.sh --full   # macOS: 런처 applet 재빌드 + 서명
+powershell -File scripts/install-codex-grok-app.ps1
 ```
 
 기본 동작은 이 체크아웃의 `src/`와 `scripts/*.mjs`를 번들에 복사하고, 저장소에
@@ -607,8 +625,13 @@ sh scripts/install-codex-grok-app.sh --full   # 런처 applet 재빌드 + 서명
 `rm -rf`하지 않습니다. Codex Grok 창이 열려 있으면 거부합니다(`--force`로
 무시). ESM은 핫리로드되지 않으므로 **동기화 후 창을 다시 열어야** 합니다.
 
-이 스크립트는 이미 있는 `Codex Grok.app`을 갱신합니다. 번들을 새로 만들지
-않고, `/Applications/Codex.app`은 건드리지 않습니다.
+macOS에서는 이미 있는 `Codex Grok.app`을 갱신하며 `/Applications/Codex.app`은
+건드리지 않습니다. Linux에서는 `~/.local/share/codex-grok-bridge/app`과
+`~/.local/share/applications/codex-grok.desktop`을 만들고 `/usr/lib/chatgpt`와
+정품 `chatgpt.desktop`은 쓰지 않습니다. Windows에서는
+`scripts/install-codex-grok-app.ps1`이 `%LOCALAPPDATA%\codex-grok-bridge`를
+쓰고 Store `ChatGPT.exe` / `resources\codex.exe`를 가리킬 수 있으며,
+`WindowsApps`는 쓰지 않습니다.
 
 ## 보안
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-grok-bridge",
-  "version": "1.0.4",
+  "version": "1.5.0",
   "description": "Run Grok 4.6 as the model inside Codex, with Codex still owning tools, permissions, history and MCP. Uses the grok login session, not an API key.",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,9 @@
     "node": ">=22"
   },
   "os": [
-    "darwin"
+    "darwin",
+    "linux",
+    "win32"
   ],
   "bin": {
     "codex-grok": "scripts/codex-grok.mjs"
@@ -35,9 +37,11 @@
     "scripts/codex-grok.mjs",
     "scripts/codex-wrapper.mjs",
     "scripts/install-codex-grok-app.sh",
+    "scripts/install-codex-grok-app.ps1",
     "scripts/launch-desktop.mjs",
     "Open Codex with Grok.command",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/codex-grok.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { startRuntime } from "../src/runtime.mjs";
+import { resolveCodexBinary } from "../src/paths.mjs";
 const runtime = await startRuntime();
 const userArgs = process.argv.slice(2);
 const overrides = [
@@ -16,7 +17,7 @@ const args =
   userArgs[0] === "exec"
     ? [userArgs[0], ...overrides, ...userArgs.slice(1)]
     : [...overrides, ...userArgs];
-const child = spawn("/Applications/Codex.app/Contents/Resources/codex", args, {
+const child = spawn(resolveCodexBinary(), args, {
   stdio: "inherit",
   env: { ...process.env, CODEX_GROK_BRIDGE_TOKEN: runtime.token },
 });

package/scripts/codex-wrapper.mjs

@@ -4,8 +4,9 @@ import { createInterface } from "node:readline";
 import { randomUUID } from "node:crypto";
 import { startRuntime } from "../src/runtime.mjs";
 import { Router } from "../src/router.mjs";
+import { resolveCodexBinary } from "../src/paths.mjs";
 
-const binary = "/Applications/Codex.app/Contents/Resources/codex";
+const binary = resolveCodexBinary();
 const args = process.argv.slice(2);
 if (!args.includes("app-server")) {
   const child = spawn(binary, args, { stdio: "inherit" });

package/scripts/install-codex-grok-app.ps1

@@ -0,0 +1,67 @@
+# Install or update the dedicated Codex Grok desktop wrapper on Windows.
+# Writes %LOCALAPPDATA%\codex-grok-bridge\app only. Never writes WindowsApps.
+param(
+  [switch]$Force
+)
+
+$ErrorActionPreference = "Stop"
+$Root = Split-Path -Parent $PSScriptRoot
+$App = if ($env:CODEX_GROK_APP) { $env:CODEX_GROK_APP } else { Join-Path $env:LOCALAPPDATA "codex-grok-bridge\app" }
+$UserData = Join-Path $env:LOCALAPPDATA "codex-grok-bridge\desktop"
+
+if ($App -match "(?i)WindowsApps") {
+  Write-Error "refusing to install into the stock ChatGPT/Codex prefix: $App"
+}
+
+if (-not $Force) {
+  $hit = Get-CimInstance Win32_Process -ErrorAction SilentlyContinue |
+    Where-Object { $_.CommandLine -and $_.CommandLine -like "*--user-data-dir=$UserData*" }
+  if ($hit) {
+    Write-Error "Codex Grok is running. Close its window first, or pass -Force."
+  }
+}
+
+New-Item -ItemType Directory -Force -Path (Join-Path $App "scripts"), (Join-Path $App "src") | Out-Null
+Copy-Item (Join-Path $Root "scripts\*.mjs") (Join-Path $App "scripts") -Force
+Copy-Item (Join-Path $Root "src\*.mjs") (Join-Path $App "src") -Force
+
+$Node = if ($env:NODE) { $env:NODE } else { (Get-Command node -ErrorAction Stop).Source }
+$Launcher = Join-Path $App "codex-grok-desktop.cmd"
+@"
+@echo off
+set ROOT=%~dp0
+"$Node" "%ROOT%scripts\launch-desktop.mjs" %*
+"@ | Set-Content -Path $Launcher -Encoding ASCII
+
+$StartDir = Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs"
+New-Item -ItemType Directory -Force -Path $StartDir | Out-Null
+Copy-Item $Launcher (Join-Path $StartDir "Codex Grok.cmd") -Force
+
+function Write-StorePointer([string]$Name, [string[]]$Filters) {
+  $pointerDir = Split-Path -Parent $App
+  if ($pointerDir -match "(?i)WindowsApps") { return }
+  $pkgs = @(Get-AppxPackage -AllUsers -ErrorAction SilentlyContinue | Where-Object { $_.Name -match "OpenAI\.(ChatGPT|Codex)|ChatGPT" })
+  if (-not $pkgs) {
+    $pkgs = @(Get-AppxPackage -ErrorAction SilentlyContinue | Where-Object { $_.Name -match "OpenAI\.(ChatGPT|Codex)|ChatGPT" })
+  }
+  foreach ($filter in $Filters) {
+    foreach ($pkg in $pkgs) {
+      if (-not $pkg.InstallLocation) { continue }
+      $hits = @(Get-ChildItem -Path $pkg.InstallLocation -Filter $filter -Recurse -ErrorAction SilentlyContinue)
+      $hit = $hits | Where-Object { $_.FullName -match '\\resources\\codex\.exe$' } | Select-Object -First 1
+      if (-not $hit) { $hit = $hits | Select-Object -First 1 }
+      if (-not $hit) { continue }
+      New-Item -ItemType Directory -Force -Path $pointerDir | Out-Null
+      Set-Content -Path (Join-Path $pointerDir $Name) -Value $hit.FullName -Encoding ASCII
+      Write-Output "store pointer $Name=$($hit.FullName)"
+      return
+    }
+  }
+}
+
+Write-StorePointer "store-app.txt" @("ChatGPT.exe", "Codex.exe")
+Write-StorePointer "store-codex.txt" @("codex.exe")
+
+Write-Output "win32 wrapper $Launcher"
+Write-Output "bridge in $App matches $Root"
+Write-Output "restart any open Codex Grok window to load it"

package/scripts/install-codex-grok-app.sh

@@ -1,14 +1,13 @@
 #!/bin/sh
-# Install or update the bridge inside /Applications/Codex Grok.app.
+# Install or update the dedicated Codex Grok desktop wrapper.
 #
-# Default is a JS-only sync: the bundle's scripts/ and src/ are brought in line
-# with this checkout, in place. The previous version began with `rm -rf` on the
-# directory that CODEX_CLI_PATH points into, which destroys a running app's
-# entrypoint; nothing here removes a directory, and stale files are pruned one
-# by one only when the repo no longer has them.
+# macOS: sync JS into /Applications/Codex Grok.app (must already exist).
+# Linux: create ~/.local/share/codex-grok-bridge/app and a user .desktop.
+# Windows: create %LOCALAPPDATA%\codex-grok-bridge\app and a Start Menu .cmd.
+# Never writes /Applications/Codex.app, /usr/lib/chatgpt, or WindowsApps.
 #
 #   install-codex-grok-app.sh            sync bridge JS (safe, fast)
-#   install-codex-grok-app.sh --full     also rebuild the launcher applet and sign
+#   install-codex-grok-app.sh --full     macOS: rebuild applet; Linux: rewrite launcher
 #   install-codex-grok-app.sh --force    proceed even if a Codex Grok window is open
 #
 # ESM is not hot-reloaded: an open Codex Grok window keeps running the code it
@@ -16,11 +15,28 @@
 set -eu
 
 ROOT="$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)"
-# CODEX_GROK_APP exists so this script can be exercised against a scratch copy
-# instead of the installed app.
-APP="${CODEX_GROK_APP:-/Applications/Codex Grok.app}"
-BRIDGE="$APP/Contents/Resources/bridge"
-USER_DATA="$HOME/.local/share/codex-grok-bridge/desktop"
+PLATFORM="${CODEX_GROK_PLATFORM:-$(uname -s)}"
+case "$PLATFORM" in
+  Linux|linux) PLATFORM=linux ;;
+  Darwin|darwin) PLATFORM=darwin ;;
+  MINGW*|MSYS*|CYGWIN*|Windows_NT|win32|windows) PLATFORM=win32 ;;
+esac
+if [ "$PLATFORM" = win32 ]; then
+  USER_DATA="${LOCALAPPDATA:-$HOME/AppData/Local}/codex-grok-bridge/desktop"
+else
+  USER_DATA="$HOME/.local/share/codex-grok-bridge/desktop"
+fi
+
+if [ "$PLATFORM" = linux ]; then
+  APP="${CODEX_GROK_APP:-$HOME/.local/share/codex-grok-bridge/app}"
+  BRIDGE="$APP"
+elif [ "$PLATFORM" = win32 ]; then
+  APP="${CODEX_GROK_APP:-${LOCALAPPDATA:-$HOME/AppData/Local}/codex-grok-bridge/app}"
+  BRIDGE="$APP"
+else
+  APP="${CODEX_GROK_APP:-/Applications/Codex Grok.app}"
+  BRIDGE="$APP/Contents/Resources/bridge"
+fi
 
 FULL=0
 FORCE=0
@@ -33,12 +49,19 @@ for arg in "$@"; do
   esac
 done
 
-if [ ! -d "$APP/Contents" ]; then
+case "$APP" in
+  /usr/lib/chatgpt|/usr/lib/chatgpt/*|/usr/bin/chatgpt|/Applications/Codex.app|/Applications/Codex.app/*|*WindowsApps*|*windowsapps*)
+    echo "refusing to install into the stock ChatGPT/Codex prefix: $APP" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$PLATFORM" != linux ] && [ "$PLATFORM" != win32 ] && [ ! -d "$APP/Contents" ]; then
   echo "missing $APP" >&2
   exit 1
 fi
 
-if [ "$FORCE" -eq 0 ] && pgrep -f -- "--user-data-dir=$USER_DATA" >/dev/null 2>&1; then
+if [ "$FORCE" -eq 0 ] && [ "$PLATFORM" != win32 ] && pgrep -f -- "--user-data-dir=$USER_DATA" >/dev/null 2>&1; then
   echo "Codex Grok is running. Close its window first, or pass --force to swap" >&2
   echo "the files under it (the running window keeps its loaded code either way)." >&2
   exit 1
@@ -71,7 +94,64 @@ for dir in scripts src; do
 done
 [ "$status" -eq 0 ] || { echo "bundle did not match the checkout" >&2; exit 1; }
 
-if [ "$FULL" -eq 1 ]; then
+write_linux_wrapper() {
+  NODE="${NODE:-$(command -v node || true)}"
+  [ -n "$NODE" ] || { echo "no node on PATH; set NODE=/path/to/node" >&2; exit 1; }
+  if [ -L "$NODE" ]; then
+    NODE="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$NODE")"
+  fi
+  mkdir -p "$APP/bin"
+  LAUNCHER="$APP/bin/codex-grok-desktop"
+  NODE_Q=$(printf "%s" "$NODE" | sed "s/'/'\\\\''/g")
+  cat > "$LAUNCHER" <<EOF
+#!/bin/sh
+set -eu
+ROOT="\$(CDPATH= cd -- "\$(dirname "\$0")/.." && pwd)"
+exec '$NODE_Q' "\$ROOT/scripts/launch-desktop.mjs" "\$@"
+EOF
+  chmod +x "$LAUNCHER"
+  APPS_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
+  mkdir -p "$APPS_DIR"
+  DESKTOP="$APPS_DIR/codex-grok.desktop"
+  cat > "$DESKTOP" <<EOF
+[Desktop Entry]
+Type=Application
+Name=Codex Grok
+Comment=Codex desktop with Grok via the local bridge
+Exec="$LAUNCHER" %U
+Icon=chatgpt
+Terminal=false
+Categories=Development;
+StartupWMClass=ChatGPT
+EOF
+  update-desktop-database "$APPS_DIR" >/dev/null 2>&1 || true
+  echo "linux wrapper $LAUNCHER"
+  echo "desktop entry $DESKTOP"
+}
+
+write_win32_wrapper() {
+  NODE="${NODE:-$(command -v node || true)}"
+  [ -n "$NODE" ] || { echo "no node on PATH; set NODE=/path/to/node" >&2; exit 1; }
+  mkdir -p "$APP"
+  LAUNCHER="$APP/codex-grok-desktop.cmd"
+  NODE_WIN=$(printf "%s" "$NODE" | tr '/' '\\')
+  {
+    echo "@echo off"
+    echo "set ROOT=%~dp0"
+    echo "\"$NODE_WIN\" \"%ROOT%scripts\\launch-desktop.mjs\" %*"
+  } > "$LAUNCHER"
+  START_DIR="${APPDATA:-$HOME/AppData/Roaming}/Microsoft/Windows/Start Menu/Programs"
+  mkdir -p "$START_DIR"
+  cp "$LAUNCHER" "$START_DIR/Codex Grok.cmd"
+  echo "win32 wrapper $LAUNCHER"
+  echo "start menu $START_DIR/Codex Grok.cmd"
+}
+
+if [ "$PLATFORM" = linux ]; then
+  write_linux_wrapper
+elif [ "$PLATFORM" = win32 ]; then
+  write_win32_wrapper
+elif [ "$FULL" -eq 1 ]; then
   NODE="${NODE:-$(command -v node || true)}"
   [ -n "$NODE" ] || { echo "no node on PATH; set NODE=/path/to/node" >&2; exit 1; }
   if [ -L "$NODE" ]; then