@minhspark/codex-mcp-bridge 1.26.5 → 1.26.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/.codex-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +22 -0
  3. package/README.md +51 -735
  4. package/docs/new-macos-setup.md +10 -6
  5. package/docs/new-windows-setup.md +14 -3
  6. package/docs/project-onboarding.md +7 -3
  7. package/package.json +1 -1
  8. package/plugin.json +1 -1
  9. package/scripts/install-native-relay.mjs +1 -1
  10. package/scripts/update.mjs +6 -3
  11. package/src/claude-bridge.mjs +1 -1
  12. package/src/codex-bridge-launcher.mjs +35 -7
  13. package/src/index.mjs +1 -1
  14. package/src/native-relay-companion.mjs +1 -1
  15. package/src/setup.mjs +1 -1
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-mcp-bridge",
3
- "version": "1.26.5",
3
+ "version": "1.26.7",
4
4
  "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
5
5
  "author": {
6
6
  "name": "Bui Dang Minh"
package/CHANGELOG.md CHANGED
@@ -4,6 +4,28 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [1.26.7] - 2026-11-03
8
+
9
+ ### Fixed
10
+
11
+ - Isolate setup test filesystem targets beneath their temporary fixture directory and independently verify configuration discovery. This removes the data flow reported by 12 CodeQL path-injection alerts in the setup tests.
12
+ - Isolate the postinstall failure test from installed Claude executables so authentication probes cannot create unrelated configuration files in its temporary home.
13
+
14
+ ### Verification
15
+
16
+ - Setup tests and the complete Node 22/24 CI matrix pass on Windows, macOS and Linux. CodeQL reports no findings on the fix pull request. This release changes test isolation and version metadata only; application runtime behavior is unchanged.
17
+
18
+ ## [1.26.6] - 2026-11-02
19
+
20
+ ### Added
21
+
22
+ - One short command for a complete terminal install or update: `npx.cmd -y @minhspark/codex-mcp-bridge@latest` on Windows, or `npx -y @minhspark/codex-mcp-bridge@latest` on macOS/Linux. A bare npm-exec launch with interactive input and output runs the full updater; Windows selects the per-user npm prefix automatically. Package installation, managed setup and live relay verification remain part of the same command.
23
+ - An explicit `codex-mcp-bridge update` subcommand for installed-package automation. Existing piped MCP launches, direct MCP invocation, setup, telemetry and version commands retain their routing.
24
+
25
+ ### Documentation
26
+
27
+ - Reduce the README from 817 to 133 lines, keeping installation, prerequisites, verification, everyday use and documentation links.
28
+
7
29
  ## [1.26.5] - 2026-11-02
8
30
 
9
31
  ### Fixed
package/README.md CHANGED
@@ -15,803 +15,119 @@
15
15
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge" height="20" alt="license" /></a>
16
16
  </p>
17
17
 
18
- Connect **Claude, Codex, and Antigravity** through MCP using native Desktop handoffs or independent CLI background workers. Native handoffs preserve each app's conversation identity and permission checks; workers have separate sessions and enforce provider permissions and project authorization. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
18
+ Connect **Claude, Codex, and Antigravity** through MCP. Send work between native Desktop conversations or use independent CLI background workers.
19
19
 
20
- The **background worker relay** supports all six directions between Codex, Claude and Antigravity CLI workers, independently of Desktop responsiveness. The optional **native Antigravity bridge** connects existing Desktop conversations in the same project and offers separate bridge-owned CLI streaming sessions. Native App replies remain in the App. [Background workers](#independent-background-workers) · [Antigravity native and streaming-session limits](#antigravity-app-and-cli).
20
+ Supports Windows, macOS, and Linux. Native Desktop integration supports Windows and macOS.
21
21
 
22
22
  https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
23
23
 
24
24
  ## Installation
25
25
 
26
- One npm command installs or updates the global package, applies all managed Claude, Codex and Antigravity settings, and configures the independent worker relay. Native handoffs require the selected Desktop apps; background work requires the selected provider CLIs and their own authentication. Setup preserves existing project restrictions and custom settings; it does not sign in, grant workspace trust, change permission modes, or restart running apps.
27
-
28
26
  ### Package — npm
29
27
 
30
- **macOS / Linux / WSL**
31
-
32
- ```bash
33
- npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
34
- ```
28
+ Requires **Node.js 22.13+**. Use the same command for a fresh install or an update.
35
29
 
36
30
  **Windows PowerShell**
37
31
 
38
32
  ```powershell
39
- npx.cmd --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user
40
- ```
41
-
42
- Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. **Use this same single command for a fresh install and every update**, including upgrades from 1.26.0 or 1.26.1. On Windows, `--user` selects `%APPDATA%\npm`, avoiding protected `Program Files` prefixes and administrator rights even when switching Node installations. npm fetches the latest updater into its cache without running setup there. The updater installs that exact resolved version globally with lifecycle scripts disabled, applies managed setup directly using Node, and verifies the global version, saved settings and service activation separately. A second installation command is not required.
43
-
44
- For an enabled legacy Windows relay from 1.26.0 or 1.26.1, the updater moves only this package's owned service to newer code using private relay storage as its working directory before replacing the global package. The temporary service runtime points to the downloaded updater package; changing the working directory releases the old package lock. It waits for active work to drain and the replacement transport to become ready without killing processes or opening apps or chats. If migration is still pending after its bounded wait, it reports `UPDATE_RELAY_PENDING`; keep the existing jobs and receipts and rerun the same command after they finish. Intentionally disabled services stay disabled and are not reported as ready.
45
-
46
- Managed setup migrates historical automatic Codex navigation to `CODEX_BRIDGE_OPEN_IN_APP=0`, enables Claude's native background preference and updates Antigravity's existing Windows background preference where supported. Accounts, project grants, unrelated custom registrations and existing permission denials remain unchanged. Setup adds only the four worker-relay communication grants required by headless Antigravity; it does not enable broad permission bypasses. If a native Codex CLI is missing, setup installs a pinned official `@openai/codex` package in the current user's `~/.config/GptClaudeBridge/tools` (or the corresponding `XDG_CONFIG_HOME` path); no separate CLI install command is needed.
47
-
48
- ### Independent background workers
49
-
50
- `worker_status`, `list_workers`, `send_to_worker` and `read_worker_delivery` address separate Codex, Claude and Antigravity CLI workers. The `worker-relay` command provides status, list, send and receipt-read operations from a terminal. All six worker directions are supported: Codex ↔ Claude, Codex ↔ Antigravity and Claude ↔ Antigravity. A native handoff still addresses its original native task; an uncertain native send is never silently replayed through a CLI worker.
51
-
52
- The service and worker processes run independently of Desktop hosts. Submitted background jobs and worker-to-worker communication can continue while those apps are closed or frozen. A frozen window cannot accept new user input or display new results until it responds again. Submit authorized background work or inspect its receipts through `worker-relay` in a terminal or another responsive MCP client; this does not repair or reopen the frozen UI.
53
-
54
- The operating system and per-user service must be running, the selected CLI must be installed and authenticated, and the project must be authorized. Provider access, network connectivity, quota and tool permissions still apply. Setup supplies a missing Codex CLI; install Claude Code and `agy` separately when those workers are needed. Sleep, shutdown, a disabled service or a provider failure can prevent execution.
55
-
56
- `authentication-unverified` with `canAcceptWork: true` is an informational state for a CLI without a supported authentication probe. It is not an authentication failure. Actual failed jobs have a durable diagnostic receipt. Keep the original request ID when inspecting or retrying an uncertain submission; after a terminal `failed` receipt confirms `not_sent`, fix the reported cause before creating a new authorized request.
57
-
58
- The package update configures per-user startup: Task Scheduler on Windows, a LaunchAgent on macOS and a systemd user service on Linux. It starts the service without opening apps or chats, preserves intentional disabled choices, and drains active jobs before adopting updated code. `worker-relay status` reports transport availability, provider authentication checks and recent errors separately. A saved configuration is not proof of live activation or model access.
59
-
60
- CLI authentication is separate from Desktop sign-in. Workers use each provider's official credential handling; the bridge does not copy Desktop tokens. Codex and Claude use ephemeral CLI sessions. Antigravity starts a fresh CLI-owned conversation and never resumes a Desktop conversation; its CLI may retain history according to provider behavior and uses its shared MCP inventory. Setup preserves other MCP entries and effective provider permissions. No worker opens or navigates that history.
61
-
62
- Background dispatch uses the existing shared project-policy file. Select a project explicitly with `bridge-projects allow-project <absolute-project-path>` if it is not already authorized; updates preserve grants and revocations. Each child delegation stays in the same canonical project. Existing provider permissions remain enforced, including denials that prevent unattended execution.
63
-
64
- Keep the same request UUID for retries and read its durable receipt. Queued work can survive relay restarts; work that might already have reached a worker is marked unknown and is never replayed automatically. Failure reports remain readable after the original window closes, with error/cause codes, delivery certainty and report IDs. Errors from tool calls appear in their Claude/Codex/Antigravity tool results; this package does not create a separate Desktop popup or reopen a chat to show them.
65
-
66
- Worker delegation is bounded. `WORKER_DELEGATION_CAPACITY` means the destination has no free execution slot and that delegation was not sent or queued behind waiting workers. Inspect or finish existing delegated work before retrying the same unsent request. Queue and delegation limits are reported explicitly.
67
-
68
- The updater disables npm lifecycle scripts for both the cached download and the global installation, then runs the installed package's managed setup directly using Node. This avoids npm script-policy differences, lifecycle shell failures and client MCP registrations pointing into a temporary npm cache directory. A direct global npm install remains an advanced alternative, but it skips the updater's migration of an old service that can lock the package on Windows.
69
-
70
- | Client | Installed entry | Purpose |
71
- | --- | --- | --- |
72
- | Claude Code | `codex-bridge` | Native Codex Desktop handoffs on Windows/macOS; local app-server mode on Linux |
73
- | Claude Desktop shared connectors | `codex-bridge-desktop` | Local Codex app-server sessions from ordinary chat |
74
- | Codex | `claude-bridge` | Send to Claude and observe replies |
75
- | Codex Desktop, Windows/macOS | `codex-native-relay` | Native delivery, pipe forwarding, and relay executor bootstrap |
76
- | Codex and Claude Code | `antigravity-bridge` | Send to Antigravity App or bridge-owned CLI sessions |
77
- | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound agent messages and native App connectivity |
78
- | Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
79
-
80
- For native Claude-to-Codex handoffs, use an existing native Claude **Code** session and the same local project saved in Codex Desktop. The shared `codex-bridge-desktop` connector has its own legacy route; it does not establish a native Code sender identity. Setup applies saved configuration without opening or restarting apps. Saved configuration is not proof of a live connection; available supervisors reload compatible workers when idle. Complete [verification](#verify-the-installation) with the tools already available in the actual clients. If a native host is unloaded, report the diagnostic instead of opening chats to load a relay.
81
-
82
- Managed setup runs **after the updater's global npm installation succeeds**, outside npm's lifecycle hook. Local `npm install` and `npm ci` do not change app settings. For a deliberate package-only installation, use a direct global npm install with `CODEX_BRIDGE_SKIP_SETUP=1` or `--ignore-scripts`; the complete updater always applies and verifies setup, and refuses an explicit `CODEX_BRIDGE_SKIP_SETUP=1` opt-out. The optional [workflow skill](#workflow-skill--npx-skills), VS Code preview, and hosted ChatGPT pairing retain their separate setup steps.
83
-
84
- ### Setup recovery and checks
85
-
86
- If service migration, installation or managed setup fails, the updater returns a nonzero exit and reports the failed step. Inspect that component and the installed version, correct the reported cause, and rerun the same update command above. A completed package installation is preserved if managed setup fails. For configuration-only repair of an already installed package, the following is an optional alternative:
87
-
88
- ```bash
89
- codex-bridge-setup
90
- ```
91
-
92
- On Windows use `codex-bridge-setup.cmd`. `codex-mcp-bridge setup` is an equivalent entry point. Repeated setup reapplies managed bridge settings and reports conflicts rather than overwriting unrelated registrations. `configured: true` confirms saved configuration; `liveVerified: false` means running clients have not been verified to load it. Setup never opens an app or chat, uses Computer Use, or interrupts active work to load a relay. Missing or unsupported native background preferences are reported separately.
93
-
94
- ```bash
95
- codex-bridge-setup --check
96
- codex-bridge-setup --dry-run
97
- ```
98
-
99
- `--check` inspects saved registrations without sending work. Explicit setup and `--check` exit with a nonzero status when configuration is incomplete. `--dry-run` lists planned components and configuration paths without downloads or writes. Add `--json` for structured output, or `--no-download` to require an already available Codex CLI. Setup never labels a saved registration as a verified live exchange.
100
-
101
- ### Package — Homebrew
102
-
103
- On macOS or Linux you can install with [Homebrew](https://github.com/buidangminh23/homebrew-tap) instead, which brings its own Node.js:
104
-
105
- ```bash
106
- brew install buidangminh23/tap/codex-mcp-bridge
107
- ```
108
-
109
- **Homebrew — update**
110
-
111
- ```bash
112
- brew upgrade codex-mcp-bridge
33
+ npx.cmd -y @minhspark/codex-mcp-bridge@latest
113
34
  ```
114
35
 
115
- Run `codex-bridge-setup` after installing through Homebrew. The installers record Homebrew's stable `opt` paths, so registrations keep working after an upgrade and running bridges reload compatible code changes. Keep one install channel: whichever of npm or Homebrew comes first on `PATH` provides the commands.
116
-
117
- [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Claude Code](#register-claude-code) · [Antigravity](#antigravity-app-and-cli) · [VS Code](#vs-code-extensions--windows-preview) · [Linux / WSL](#linux--wsl-bash) · [NPX Skills](#workflow-skill--npx-skills) · [ChatGPT plugin](#chatgpt-plugin)
118
-
119
- | Integration | Setup |
120
- | --- | --- |
121
- | Claude Desktop Code → Codex Desktop | Automatic native setup on Windows/macOS |
122
- | Claude Code CLI → local Codex app-server | Automatic on Linux; optional manual CLI mode on Windows/macOS |
123
- | Claude Desktop shared MCP → local Codex app-server | Automatic `codex-bridge-desktop` registration |
124
- | Codex → Claude Desktop Code | Automatic `claude-bridge` registration |
125
- | Codex / Claude Desktop Code → Antigravity App or CLI | Automatic Antigravity registrations |
126
- | Antigravity App → Codex / Claude Desktop Code | Automatic outbound registration and sidecar |
127
- | Codex ↔ Claude ↔ Antigravity CLI workers | Automatic independent relay setup; provider CLIs, authentication and project grants required |
128
- | Claude Code ↔ Codex inside VS Code | Separate Windows preview registrations below |
129
- | ChatGPT → paired Codex Desktop | Hosted plugin plus `codex-sites-connector --pair` |
130
-
131
- ### Antigravity App and CLI
132
-
133
- The global npm setup registers all Antigravity components, including the independent `worker-relay` MCP entry and its four scoped CLI communication grants. Install and sign in to the Antigravity App for native conversations or the `agy` CLI for CLI work. The following commands configure only the native bridge and its legacy streaming-session tools; use the global setup above to configure the independent worker service as well:
36
+ **macOS / Linux / WSL**
134
37
 
135
38
  ```bash
136
- antigravity-mcp-bridge-install --all
39
+ npx -y @minhspark/codex-mcp-bridge@latest
137
40
  ```
138
41
 
139
- **Windows PowerShell — all native bridge components**
42
+ Run the command directly in an interactive terminal. It installs the package, applies Claude/Codex/Antigravity settings, and verifies the background relay. Windows installs into `%APPDATA%\npm` without administrator rights. Existing permissions, project grants, custom settings, and disabled services are preserved.
140
43
 
141
- ```powershell
142
- antigravity-mcp-bridge-install.cmd --all
143
- ```
44
+ For native handoffs, sign in to the Desktop apps and open the same saved project in Codex Desktop and Claude Desktop's **Code tab**. The shared Claude chat connector is a separate local app-server route.
144
45
 
145
- **Codex → Antigravity App / CLI**
46
+ Setup supplies a missing Codex CLI. Install and authenticate Claude Code and `agy` separately for their workers; CLI authentication is separate from Desktop sign-in.
146
47
 
147
- ```bash
148
- antigravity-mcp-bridge-install --codex
149
- ```
48
+ [Windows setup](docs/new-windows-setup.md) · [macOS setup](docs/new-macos-setup.md) · [Project permissions](docs/project-onboarding.md)
150
49
 
151
- **Claude Desktop Code → Antigravity App / CLI**
50
+ ### Independent background workers
152
51
 
153
- ```bash
154
- antigravity-mcp-bridge-install --claude
155
- ```
52
+ Codex ↔ Claude, Codex ↔ Antigravity, and Claude ↔ Antigravity workers communicate through a per-user service, even while Desktop apps are closed or unresponsive. Workers use separate CLI sessions and require an authenticated provider, a running service, and an authorized project.
156
53
 
157
- **Antigravity App sidecar and outbound bridge**
54
+ - MCP tools: `worker_status`, `list_workers`, `send_to_worker`, `read_worker_delivery`.
55
+ - Terminal: `worker-relay status`, `worker-relay list`, `worker-relay send`, `worker-relay read`.
56
+ - Authorize a selected project with `bridge-projects allow-project <absolute-project-path>`.
158
57
 
159
- ```bash
160
- antigravity-mcp-bridge-install --desktop
161
- ```
58
+ On Windows, add `.cmd` to terminal commands. Provider quotas and tool permissions still apply. [Worker setup and authorization](docs/project-onboarding.md)
162
59
 
163
- **Preview the installation without changing configuration**
60
+ ### Verify the installation
164
61
 
165
62
  ```bash
166
- antigravity-mcp-bridge-install --all --dry-run
63
+ codex-bridge-setup --check
64
+ worker-relay status
167
65
  ```
168
66
 
169
- Use `.cmd` for each command on Windows. `--all` includes the Codex, Claude and Antigravity native bridge components; the individual commands are alternatives when only some clients are needed. The installer preserves unrelated configuration and native permissions. Managed MCP supervisors adopt compatible updates when idle; an old direct process remains on its loaded version until the host reconnects normally. No app or chat is opened to force readiness. Antigravity launches its own sidecar from `~/.gemini/config/sidecars/codex-bridge/sidecar.json`; do not run that sidecar manually or copy authentication environment variables between processes.
67
+ On Windows use `codex-bridge-setup.cmd --check` and `worker-relay.cmd status`. The first command checks saved settings; the second checks the independent service and CLI readiness.
170
68
 
171
- The `agy` CLI must be installed and signed in separately. The legacy `start_antigravity_cli_session` tool creates streaming sessions owned by the calling bridge process; independent background work instead uses `send_to_worker` with `agent: "antigravity"`. There is no separate `--cli` installer flag. Set `ANTIGRAVITY_CLI_BIN` to the absolute `agy` executable path in the MCP server environment if automatic discovery cannot find it.
69
+ Check native connections with the tools available inside each client:
172
70
 
173
- | Tool | Behavior |
71
+ | Client | Status tool |
174
72
  | --- | --- |
175
- | `antigravity_bridge_status` | Reports native sidecar connectivity, CLI capabilities, and the separate outbound Desktop route. Outbound readiness requires `agent_bridge_status` inside Antigravity. |
176
- | `list_antigravity_conversations` | Lists the selected surface in the verified sender's exact project directory. |
177
- | `send_to_antigravity_conversation` | Sends to an exact existing App conversation or a CLI session owned by this bridge. |
178
- | `start_antigravity_cli_session` | Starts an explicitly authorized CLI streaming session with its initial prompt. |
179
- | `read_antigravity_delivery` | Reads the original receipt without resending. |
180
- | `close_antigravity_cli_session` | Closes an idle CLI session owned by the sender. |
181
-
182
- For these native bridge and legacy streaming-session tools, generate a new `requestId` UUID for each intentional delivery and reuse it only when inspecting or retrying that same delivery. A pending or unknown receipt must be inspected before further action. Receipts survive process restarts; live streaming CLI processes do not. A CLI timeout retains its conversation identity for inspection. No mode or permission-bypass flag is added; headless tool requests requiring interaction may be denied by Antigravity.
183
-
184
- The App adapter uses the official [sidecar `agentapi`](https://antigravity.google/docs/sidecars), verifies native workspace metadata, and refuses busy or ambiguous destinations. An App `accepted` receipt confirms native acceptance, not a completed agent reply. Its response remains in the exact native App conversation and can be read when that UI is responsive. The CLI adapter uses the official [streaming JSON interface](https://antigravity.google/docs/cli/headless) and returns the agent's final result. It creates bridge-owned headless sessions; it does not attach to an already running interactive terminal. The two surfaces never substitute for one another.
185
-
186
- The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.gemini/config/mcp_config.json`. Once the host has loaded that registration, use the tools available in the intended Antigravity conversation: check `agent_bridge_status`, call `list_agent_tasks` for `codex` or `claude`, then use `send_to_agent_task` with the exact destination ID, project directory, prompt, and a fresh request UUID. Claude destinations also require their native `taskId`. Read `read_agent_delivery` without resending; `read_agent_task` reads the selected Codex task's response or Claude's native task metadata.
187
-
188
- Native outbound calls verify Antigravity's per-call MCP metadata, Desktop process ancestry, native workspace/project, and effective permission settings. The sender is attributed as Antigravity. Codex keeps its native task settings; Claude's inbound policy and permission-class checks remain in effect. A socket write to Claude is `sent_unconfirmed`, not acceptance or completion. After MCP restart, a saved receipt remains available but live Claude reply tracking may be unavailable; inspect the exact native task before further action.
189
-
190
- If a caller says the bridge only supports one-way messaging, compare its loaded version with the installed package: older initialization instructions incorrectly denied the separate native outbound route. A managed worker can reload when idle; an old direct MCP process requires a normal host reconnection. An unavailable inbound sidecar does not prove that the App is closed or that outbound messaging is unsupported. Use available `agent_bridge_status` diagnostics to verify the native outbound route independently, and `worker_status` for the independent workers.
191
-
192
- Native outbound support targets existing local Codex tasks and live Claude Desktop Code sessions in the same project. That route rejects nested Antigravity callers and CLI callers claiming Desktop identity; App conversation creation and automatic App reply forwarding are not implemented. These native limits do not restrict the separately authorized CLI workers, which communicate through `worker-relay` in all six directions. Windows Desktop is the native live verification platform; macOS ancestry has unit coverage and Linux native outbound host verification fails closed. The existing Codex↔Claude native bridge remains separate. Use `antigravity-mcp-bridge-install --all --remove` to remove only the native bridge registrations; independent worker configuration and delivery receipts are retained.
193
-
194
- ### Windows (PowerShell)
195
-
196
- Install and sign in to [Codex Desktop](https://developers.openai.com/codex/app) and [Claude Desktop](https://claude.com/download). Save the project in Codex Desktop and open the same directory in Claude Desktop's **Code tab**. The [global npm command](#package--npm) configures both apps, the shared `codex-bridge-desktop` connector, and Antigravity. Then [verify](#verify-the-installation).
197
-
198
- <details>
199
- <summary>Optional manual native setup</summary>
200
-
201
- These advanced commands require an existing Codex CLI on PATH. If it is missing, use `codex-bridge-setup.cmd` to resolve or install it automatically. A separately managed CLI can instead be installed with `winget install --id OpenAI.Codex --exact` and signed in with `codex.exe login`.
202
-
203
- ```powershell
204
- $env:CODEX_EXE = (Get-Command codex.exe).Source
205
- codex-native-relay-install.cmd --desktop-tasks
206
- $env:CODEX_BRIDGE_DESKTOP_TASKS = "1"
207
- claude-mcp-bridge-install.cmd
208
- ```
209
-
210
- For manual setup, also [register Claude Code](#register-claude-code) and check [relay pipe forwarding](#native-relay-pipe-forwarding).
211
-
212
- </details>
213
-
214
- ### macOS (Terminal)
215
-
216
- Install and sign in to Codex Desktop and Claude Desktop. Save the project in Codex Desktop and open the same directory in Claude Desktop's **Code tab**. Run the [global npm command](#package--npm), then [verify](#verify-the-installation). Setup selects the trusted app-bundled relay runtime when available and initializes the relay executor.
217
-
218
- <details>
219
- <summary>Optional manual native setup</summary>
220
-
221
- ```bash
222
- npm install -g @openai/codex@latest
223
- codex login
224
- codex-native-relay-install --desktop-tasks
225
- CODEX_BRIDGE_DESKTOP_TASKS=1 claude-mcp-bridge-install
226
- ```
227
-
228
- Keep bootstrap enabled on the first manual relay install. Also [register Claude Code](#register-claude-code) and check [relay pipe forwarding](#native-relay-pipe-forwarding).
229
-
230
- </details>
231
-
232
- ### Register Claude Code
233
-
234
- Global npm setup creates the user-level Code registration automatically. Claude Desktop and Claude Code have separate MCP registrations. The commands below are optional manual alternatives; they require the [Claude Code CLI](https://code.claude.com/docs/en/setup). Replace the example project path with the actual directory and preserve custom settings if `codex-bridge` is already registered.
235
-
236
- Native Desktop handoffs require a verified Claude Desktop **Code** session. A shared Desktop chat MCP registration cannot establish that sender identity. Automatic setup safely renames a recognized shared `codex-bridge` entry to `codex-bridge-desktop`, retaining its contents, so it cannot shadow the Code registration. A conflicting target or unknown entry is reported for review. For manual edits, close Claude first and keep the two entry names distinct.
237
-
238
- <details>
239
- <summary>Windows PowerShell</summary>
240
-
241
- ```powershell
242
- $bridgeRoot = Join-Path ((npm.cmd root -g).Trim()) '@minhspark/codex-mcp-bridge'
243
- claude mcp add --scope user codex-bridge `
244
- -e "CODEX_BIN=$((Get-Command codex.exe).Source)" `
245
- -e CODEX_BRIDGE_DESKTOP_TASKS=1 `
246
- -e CODEX_BRIDGE_AUTOSTART=0 `
247
- -e CODEX_BRIDGE_THREAD_POLICY=roots `
248
- -e "CODEX_BRIDGE_ALLOWED_ROOTS=C:\Projects\YourProject" `
249
- -- (Get-Command node.exe).Source (Join-Path $bridgeRoot 'src/mcp-supervisor.mjs') index.mjs
250
- ```
251
-
252
- </details>
253
-
254
- <details>
255
- <summary>macOS Terminal</summary>
256
-
257
- ```bash
258
- bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
259
- claude mcp add --scope user codex-bridge \
260
- -e CODEX_BIN="$(command -v codex)" \
261
- -e CODEX_BRIDGE_DESKTOP_TASKS=1 \
262
- -e CODEX_BRIDGE_AUTOSTART=0 \
263
- -e CODEX_BRIDGE_THREAD_POLICY=roots \
264
- -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
265
- -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
266
- ```
267
-
268
- For a Homebrew install, use this complete command with stable `opt` paths instead:
269
-
270
- ```bash
271
- bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
272
- node_bin="$(brew --prefix)/opt/node/bin/node"
273
- claude mcp add --scope user codex-bridge \
274
- -e CODEX_BIN="$(command -v codex)" \
275
- -e CODEX_BRIDGE_DESKTOP_TASKS=1 \
276
- -e CODEX_BRIDGE_AUTOSTART=0 \
277
- -e CODEX_BRIDGE_THREAD_POLICY=roots \
278
- -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
279
- -- "$node_bin" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
280
- ```
281
-
282
- </details>
283
-
284
- Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
285
-
286
- `codex-bridge-code-install --install` now creates or updates the supervised Code entry; `--install --dry-run` previews it. The complete `codex-bridge-setup` command also supplies the other registrations and prerequisites. The helper's existing `--check` and policy migration modes remain available; see [project onboarding](docs/project-onboarding.md).
287
-
288
- ### Claude Desktop shared MCP — legacy option
289
-
290
- Global setup includes this connector as **`codex-bridge-desktop`** in Claude Desktop's shared MCP configuration. It connects ordinary chat to local Codex app-server sessions. For verified handoffs into Codex Desktop conversations, use the Code-tab route above. The following commands are optional manual alternatives and require an available, signed-in Codex CLI.
291
-
292
- **Windows PowerShell**
293
-
294
- ```powershell
295
- $env:CODEX_EXE = (Get-Command codex.exe).Source
296
- $env:CODEX_BRIDGE_DESKTOP_TASKS = "0"
297
- $env:CODEX_BRIDGE_AUTOSTART = "1"
298
- codex-mcp-bridge-install.cmd --entry-name codex-bridge-desktop
299
- ```
300
-
301
- **macOS Terminal**
302
-
303
- ```bash
304
- CODEX_BRIDGE_DESKTOP_TASKS=0 CODEX_BRIDGE_AUTOSTART=1 codex-mcp-bridge-install --entry-name codex-bridge-desktop
305
- ```
306
-
307
- Running clients may retain their previously loaded configuration; setup reports live activation as unverified and does not interrupt them. A fresh `--entry-name codex-bridge-desktop` registration defaults to legacy mode even when the native relay is configured. Existing custom modes are preserved. `--desktop-tasks` does not make a shared Desktop chat server a verified Code sender.
308
-
309
- ### VS Code extensions — Windows preview
310
-
311
- For existing Claude Code and Codex extension conversations inside the same VS Code project, register the separate preview bridge in both clients. Install the npm package first and replace the example root with the real project directory. These registrations preserve extension sender checks and do not provide Desktop access.
312
-
313
- ```powershell
314
- $bridgeRoot = Join-Path ((npm.cmd root -g).Trim()) '@minhspark/codex-mcp-bridge'
315
- $nodeBin = (Get-Command node.exe).Source
316
- $projectRoot = 'C:\Projects\YourProject'
317
- claude mcp add --scope user codex-vscode-bridge `
318
- -e "VSCODE_BRIDGE_ALLOWED_ROOTS=$projectRoot" `
319
- -- $nodeBin (Join-Path $bridgeRoot 'src/vscode-bridge.mjs') claude
320
- codex.exe mcp add claude-vscode-bridge `
321
- --env "VSCODE_BRIDGE_ALLOWED_ROOTS=$projectRoot" `
322
- -- $nodeBin (Join-Path $bridgeRoot 'src/vscode-bridge.mjs') codex
323
- ```
324
-
325
- Reload the VS Code window after registration. Separate multiple explicit project roots with `;`; drive roots are not accepted. See [preview behavior and limits](REFERENCE.md#vs-code-extension-bridge-windows-preview).
326
-
327
- ### Native relay pipe forwarding
328
-
329
- On Windows and macOS, `codex-native-relay-install` adds this to the relay's entry in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and keeps its other settings:
330
-
331
- ```toml
332
- [mcp_servers.codex-native-relay]
333
- env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
334
- ```
335
-
336
- If you register the relay by hand, add the same line and append the variable name if `env_vars` already exists. Only the name is saved, never the temporary pipe path. The changed environment takes effect when the native host next reconnects that MCP process; setup does not restart the app or open a chat to force it.
337
-
338
- ### Linux / WSL (Bash)
339
-
340
- The global npm command configures local app-server mode on Linux/WSL and resolves the Codex CLI automatically. Use Node.js 22.13+ and signed-in Codex and Claude Code under the same Linux user. Native Desktop integration requires Windows or macOS. WSL and Windows have separate paths and registrations. The following commands are optional manual alternatives.
341
-
342
- <details>
343
- <summary>CLI registration commands</summary>
344
-
345
- ```bash
346
- npm install -g @openai/codex@latest
347
- codex login
348
- CODEX_BRIDGE_DESKTOP_TASKS=0 claude-mcp-bridge-install
349
- bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
350
- claude mcp add --scope user codex-bridge \
351
- -e CODEX_BIN="$(command -v codex)" \
352
- -e CODEX_BRIDGE_DESKTOP_TASKS=0 \
353
- -e CODEX_BRIDGE_AUTOSTART=1 \
354
- -e CODEX_BRIDGE_THREAD_POLICY=roots \
355
- -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
356
- -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
357
- ```
358
-
359
- Replace `$HOME/YourProject` with the actual project directory. WSL and Windows use separate paths and registrations.
360
-
361
- </details>
362
-
363
- <details>
364
- <summary>Linux Homebrew registration commands</summary>
365
-
366
- ```bash
367
- npm install -g @openai/codex@latest
368
- codex login
369
- CODEX_BRIDGE_DESKTOP_TASKS=0 claude-mcp-bridge-install
370
- bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
371
- node_bin="$(brew --prefix)/opt/node/bin/node"
372
- claude mcp add --scope user codex-bridge \
373
- -e CODEX_BIN="$(command -v codex)" \
374
- -e CODEX_BRIDGE_DESKTOP_TASKS=0 \
375
- -e CODEX_BRIDGE_AUTOSTART=1 \
376
- -e CODEX_BRIDGE_THREAD_POLICY=roots \
377
- -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
378
- -- "$node_bin" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
379
- ```
380
-
381
- Replace `$HOME/YourProject` with the actual project directory. The bridge and Node paths remain stable across Homebrew upgrades.
382
-
383
- </details>
384
-
385
- ### Workflow skill — NPX Skills
386
-
387
- The repository includes one portable skill, `codex-bridge`, for the [hosted Codex Bridge workflow](#chatgpt-plugin). These commands install its Markdown instructions only. Using the workflow requires a client with the hosted plugin's MCP tools and a paired connector; copying the skill does not install the local bridges, configure authentication, or make a client a supported native sender.
388
-
389
- Use a Node.js version supported by the current [Skills CLI](https://github.com/vercel-labs/skills). The examples target the current project; add `-g` for a user-wide install. In Windows PowerShell use `npx.cmd` instead of `npx`.
390
-
391
- **NPX Skills — select the workflow skill**
392
-
393
- ```bash
394
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge
395
- ```
396
-
397
- **List available skills without installing**
398
-
399
- ```bash
400
- npx skills add buidangminh23/codex-mcp-bridge --list
401
- ```
402
-
403
- **Claude Code**
404
-
405
- ```bash
406
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a claude-code
407
- ```
408
-
409
- **Codex**
410
-
411
- ```bash
412
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a codex
413
- ```
414
-
415
- **Cursor**
416
-
417
- ```bash
418
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a cursor
419
- ```
420
-
421
- **Gemini CLI**
422
-
423
- ```bash
424
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a gemini-cli
425
- ```
426
-
427
- **Antigravity**
428
-
429
- ```bash
430
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a antigravity
431
- ```
432
-
433
- **Antigravity CLI**
434
-
435
- ```bash
436
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a antigravity-cli
437
- ```
438
-
439
- **Cline**
440
-
441
- ```bash
442
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a cline
443
- ```
444
-
445
- **OpenCode**
446
-
447
- ```bash
448
- npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge -a opencode
449
- ```
450
-
451
- **All Skills CLI agents — user-wide, without prompts**
452
-
453
- ```bash
454
- npx skills add buidangminh23/codex-mcp-bridge --all -g
455
- ```
456
-
457
- `--all` installs every skill in the repository for every supported Skills CLI agent, not just detected apps. Choose an individual `-a` command above for a narrower install. Agent names and scope flags follow the [Skills CLI reference](https://github.com/vercel-labs/skills/blob/main/docs/commands.md).
458
-
459
- **Legacy `add-skill` command**
460
-
461
- ```bash
462
- npx add-skill buidangminh23/codex-mcp-bridge
463
- ```
464
-
465
- `add-skill` is deprecated and forwards to `npx skills add`; use the current command above, especially on Windows where the legacy wrapper may fail to find `npx`.
466
-
467
- **Marketplace and Gemini extension installs**
468
-
469
- This repository ships a hosted ChatGPT plugin and the skill above. It does not currently publish a Claude/Codex marketplace catalog or a `gemini-extension.json` package. Consequently, `/plugin marketplace add`, `codex plugin marketplace add`, and `gemini extensions install` are not installation routes for this repository. Use the native bridge setup, NPX skill commands, or [hosted plugin setup](#chatgpt-plugin) as appropriate.
470
-
471
- ### Verify the installation
472
-
473
- Run `codex-bridge-setup --check` (`codex-bridge-setup.cmd --check` on Windows) to inspect saved registrations. An incomplete result names the component requiring attention; rerun setup after correcting it.
474
-
475
- Use the bridge tools already available in the actual clients. Configuration checks do not prove that a running client loaded new registrations. Setup does not open, kill or restart apps or chats. If a tool is unavailable, retain that exact failure for reporting. Run these **MCP tools** when available:
476
-
477
- | Client | Tool |
478
- |---|---|
479
73
  | Claude Code | `codex_bridge_status` |
480
- | Codex | `claude_bridge_status` |
481
- | Codex Desktop | `native_relay_status` |
482
- | Codex / Claude Desktop Code with Antigravity installed | `antigravity_bridge_status` |
483
- | Antigravity App | `agent_bridge_status` |
484
- | Any configured background relay client | `worker_status` |
485
-
486
- For the independent service, `worker-relay status` (`worker-relay.cmd status` on Windows) works from a terminal without a responsive Desktop app. Inspect transport, CLI authentication and recent execution errors separately. A CLI with unverified authentication still needs a successful authorized job before model access is established.
487
-
488
- To check CLI registrations without sending work:
74
+ | Codex | `claude_bridge_status`, `native_relay_status` |
75
+ | Codex / Claude with Antigravity | `antigravity_bridge_status` |
76
+ | Antigravity | `agent_bridge_status` |
489
77
 
490
- ```bash
491
- codex mcp list
492
- claude mcp list
493
- ```
494
-
495
- These optional CLI checks require the respective CLI on PATH; the complete setup check can also use its managed Codex CLI. On Windows use `codex.exe mcp list`. An installed skill is listed separately with `npx skills list` (add `-g` for user-wide skills); it is not an MCP registration.
496
-
497
- For an authorized live check, send a short message and confirm its reply on each selected route. Check worker-to-worker routes separately from native conversations; registration alone does not prove delivery.
78
+ Confirm a reply on each route used. Saved configuration alone does not verify live delivery.
498
79
 
499
80
  ## Use
500
81
 
501
82
  - **Claude → Codex:** “Send this review to my Codex task in this project and wait for its reply.”
502
83
  - **Codex → Claude:** “Send this result to my Claude Desktop Code session in this project.”
503
- - **Codex → Codex on another computer:** configure an SSH project mapping, then use `remote_codex` to list, read or message an existing Desktop task. Different Codex accounts on the two computers are supported. See [remote Codex setup](REFERENCE.md#codex-to-codex-over-ssh).
504
- - **New work:** “Create a new Codex conversation for this feature and send the brief there.”
84
+ - **Background work:** “Send this task to a Claude worker in this project.”
85
+ - **Another computer:** use [`remote_codex` over SSH](REFERENCE.md#codex-to-codex-over-ssh) with an existing Desktop task.
505
86
 
506
- Continue unfinished work with its original `threadId`. For an authorized new Desktop task, use `delegate_to_codex` or `start_codex_thread` with a fresh UUID `requestId`; retain that ID on retries. If a send times out, use `wait_codex_reply` with the original `deliveryId` before retrying the message.
87
+ Native handoffs preserve the actual sender and destination permissions. Antigravity App replies stay in their App conversation; independent workers return separate delivery receipts.
507
88
 
508
- [Daily handoffs](docs/daily-handoffs.md) · [Project permissions](docs/project-onboarding.md) · [All tools and settings](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md)
89
+ Continue unfinished work in its original conversation. If delivery times out or is uncertain, inspect the original receipt before sending again. [Daily handoffs](docs/daily-handoffs.md)
509
90
 
510
91
  ## ChatGPT plugin
511
92
 
512
- [Open Codex Bridge](https://codex-mcp-bridge.buidangminh23.chatgpt.site) to connect ChatGPT to a selected project on a Windows or macOS computer. After installing the package and native relay above, pair the connector:
93
+ [Open Codex Bridge](https://codex-mcp-bridge.buidangminh23.chatgpt.site) to connect ChatGPT to a selected project on Windows or macOS. After installing the package, pair the connector:
513
94
 
514
95
  ```bash
515
96
  codex-sites-connector --pair --site https://codex-mcp-bridge.buidangminh23.chatgpt.site --roots "/absolute/project/path"
516
97
  ```
517
98
 
518
- In PowerShell use `codex-sites-connector.cmd` and a Windows path such as `C:\Projects\YourProject`. Open the printed pairing URL, sign in, and select **Connect this computer**. Keep Codex Desktop and the connector running; use `codex-sites-connector` to reconnect later.
519
-
520
- The MCP endpoint is `https://codex-mcp-bridge.buidangminh23.chatgpt.site/mcp`. Plugin availability follows [OpenAI's Sites access rules](https://help.openai.com/en/articles/20001547-hosting-a-plugin-with-chatgpt-sites); a public directory listing is not claimed.
521
-
522
- <details>
523
- <summary>Hosted data and privacy</summary>
524
-
525
- The service is operated by Bui Dang Minh on OpenAI Sites. It stores a Site-scoped account ID, connector ID and token hash, timestamps, tool arguments (including prompts), and returned Desktop results. The operator can access these records. Local credentials and receipts stay in `~/.codex/sites-bridge`.
526
-
527
- Dispatch expires after two minutes; operation history remains stored. Disconnecting revokes the connector and cancels queued work, but does not erase history or stop dispatched tasks. For deletion requests, contact the operator through the repository's support link without posting private content publicly. The hosted Worker implements no advertising or analytics collection.
528
-
529
- </details>
530
-
531
- ## Troubleshooting
532
-
533
- Start by identifying the failed layer: installation, saved registration, live MCP connection, sender identity, delivery, or reply observation. A successful npm install proves neither that setup completed nor that an already-open app loaded the new server. An accepted delivery can still have an unavailable reply.
534
-
535
- ### Check the installation and saved settings
536
-
537
- On Windows, run these in PowerShell:
538
-
539
- ```powershell
540
- node --version
541
- npm.cmd --version
542
- npm.cmd list -g @minhspark/codex-mcp-bridge --depth=0
543
- codex-mcp-bridge.cmd --version
544
- codex-bridge-setup.cmd --check --json
545
- ```
546
-
547
- Node.js 22.13+ is required. If a command is missing, open a new terminal and check that Node and the global npm command directory are on `PATH`. Use the `.cmd` launchers when PowerShell blocks an npm `.ps1` shim; changing the machine's execution policy is unnecessary. On macOS/Linux, omit `.cmd`.
548
-
549
- If the package or registrations are missing, use the complete installation command:
99
+ On Windows use `codex-sites-connector.cmd` and a Windows project path. Open the printed pairing URL and select **Connect this computer**. Keep Codex Desktop and the connector running.
550
100
 
551
- ```powershell
552
- npx.cmd --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user
553
- ```
101
+ The hosted service stores account/connector identifiers, prompts, and returned results; its operator, Bui Dang Minh, can access these records. Disconnecting revokes access but does not erase history or stop dispatched tasks. Request deletion through [support](https://github.com/buidangminh23/codex-mcp-bridge/issues) without posting private content publicly. Availability follows [OpenAI's Sites access rules](https://help.openai.com/en/articles/20001547-hosting-a-plugin-with-chatgpt-sites).
554
102
 
555
- This runs the latest updater outside the global package directory, handles an owned legacy service that can lock that directory, installs the exact resolved package into the per-user npm prefix, then directly applies and verifies managed setup. Lifecycle scripts remain disabled during npm installation. If a previous update reported `UPDATE_NPM_FAILED` or `UPDATE_INSTALL_PERMISSION` because npm selected a protected directory, `--user` selects the user-writable destination. If a previous direct install printed `1 package had install scripts blocked`, this same updater command installs and applies the managed settings together. Intentional setup opt-outs and disabled-service choices are not silently removed. On macOS/Linux, use the installation command above; optional `--user` selects `~/.local`, whose `bin` directory must be on `PATH` for terminal commands.
556
-
557
- For an already-installed package, these optional commands preview or repair configuration without updating package files:
558
-
559
- ```powershell
560
- codex-bridge-setup.cmd --dry-run
561
- codex-bridge-setup.cmd
562
- codex-bridge-setup.cmd --check
563
- ```
103
+ ### Optional workflow skill
564
104
 
565
- `--dry-run` does not write settings or download tools. Setup resolves an existing Codex CLI or installs its managed official copy; `--no-download` requires one to be available already. Failed setup or update returns a nonzero exit; inspect the reported component and installed version, correct the cause, then rerun the same updater command. Package rollback does not guarantee that settings or command shims return to their previous state. Explicit setup and `--check` also return a nonzero exit code for incomplete configuration. Running the same command cannot resolve a deliberate opt-out or an unrelated conflicting registration.
105
+ Install the hosted workflow's Markdown instructions with:
566
106
 
567
- ### Missing module, stale source path, or a different running version
568
-
569
- **Symptoms:** `Cannot find module ... mcp-supervisor.mjs`, followed by `CONNECTION_CLOSED`; or npm reports a new version while the actual bridge still reports an older one.
570
-
571
- Check the installed entry point without starting an MCP server:
572
-
573
- ```powershell
574
- $bridgeRoot = Join-Path ((npm.cmd root -g).Trim()) '@minhspark/codex-mcp-bridge'
575
- Test-Path -LiteralPath (Join-Path $bridgeRoot 'src\mcp-supervisor.mjs')
576
- Get-Content -LiteralPath (Join-Path $bridgeRoot 'package.json') | ConvertFrom-Json | Select-Object name, version
577
- ```
578
-
579
- If the entry point is absent, reinstall with the command above. If it exists, compare that directory with the `command` and `args` of the **affected client's** MCP entry. A registration pointing into an old source checkout will continue running that checkout even after a global npm upgrade. `codex-mcp-bridge --version` reports the command on `PATH`; `codex_bridge_status` in Claude and `claude_bridge_status` / `native_relay_status` in Codex report the processes those apps actually loaded.
580
-
581
- In `claude_bridge_status`, read the text line `bridge: claude-bridge <version>` together with `runtime pid`, `loaded source`, `disk source` and `runtime state`. Its structured `runtime` object carries source/runtime metadata, not a separate version field. The native companion prints its version on the `companion: codex-native-relay <version>` line.
582
-
583
- Run setup from the intended installation, then [reconnect the affected MCP](#reconnect-the-actual-client). Setup retargets recognized original bridge launchers from older package/source paths and preserves their custom environment, project scope, and other supported settings. A missing previously recorded absolute `CODEX_BIN` can be repaired with the resolved binary; valid customized binary paths remain preserved. Setup refuses an unknown wrapper, conflicting transport, or unrelated entry using the same name. Inspect such a conflict and retain its settings before making an intentional manual change; deleting all MCP entries or replacing the whole configuration is unnecessary. Project-specific Code entries are preserved and may still shadow the new user-level entry.
584
-
585
- ### Claude Code sender ancestry and the two connector names
586
-
587
- **Symptom:** `This MCP process has no registered Claude Desktop Code session in its parent ancestry`.
588
-
589
- This is a sender-identity failure, not proof that Codex is offline. A shared Claude Desktop MCP process cannot establish which native Code task sent the request. Use the matching registration:
590
-
591
- | Entry | Loaded by | Route |
592
- |---|---|---|
593
- | `codex-bridge` | Claude Code user configuration: `~/.claude.json`, or `CLAUDE_CONFIG_DIR/.claude.json` when set | Verified Claude Desktop **Code** task to native Codex Desktop on Windows/macOS |
594
- | `codex-bridge-desktop` | Claude Desktop's shared `claude_desktop_config.json` | Ordinary Chat to the legacy local Codex app-server |
595
-
596
- Run setup to create the user-level Code registration. It can rename a recognized shared `codex-bridge` entry to `codex-bridge-desktop`; if that name is already occupied, it reports the collision instead of discarding either entry. Check project-specific overrides if the problem persists. Then reconnect `codex-bridge` **inside the intended Code session**, and run `codex_bridge_status` there with the exact project directory saved in Codex Desktop.
597
-
598
- The shared connector's presence in Claude settings does not prove the Code registration is active. Setting native mode on a shared Chat connector does not create the missing Code ancestry. Existing custom routing modes remain preserved during setup; choose the Code route when the intended destination is a native Codex Desktop conversation.
599
-
600
- If an older installation has only a shared native-mode entry, migration seeds the Code registration from its existing settings and restrictions. The shared entry's native mode is preserved and reported as incomplete by `--check`, because ordinary Chat cannot supply Code ancestry. To explicitly use that shared connector for **local app-server** sessions, apply this targeted repair after its active work finishes:
601
-
602
- ```powershell
603
- $setupPreviewJson = codex-bridge-setup.cmd --dry-run --json
604
- if (-not $? -or $LASTEXITCODE -ne 0) { throw 'Setup preview failed; no settings were changed.' }
605
- $setupPreview = $setupPreviewJson | ConvertFrom-Json -ErrorAction Stop
606
- if ($setupPreview.dryRun -ne $true -or @($setupPreview.files).Count -lt 2) {
607
- throw 'Setup preview did not select a shared configuration file; no settings were changed.'
608
- }
609
- $sharedConfig = $setupPreview.files[1]
610
- if ($sharedConfig -isnot [string] -or [string]::IsNullOrWhiteSpace($sharedConfig) -or
611
- -not (Test-Path -LiteralPath $sharedConfig -PathType Leaf)) {
612
- throw 'The selected shared configuration file is missing; finish setup before this repair.'
613
- }
614
- $previousDesktopConfig = $env:CLAUDE_DESKTOP_CONFIG
615
- $previousDesktopTasks = $env:CODEX_BRIDGE_DESKTOP_TASKS
616
- $previousAutostart = $env:CODEX_BRIDGE_AUTOSTART
617
- try {
618
- $env:CLAUDE_DESKTOP_CONFIG = $sharedConfig
619
- $env:CODEX_BRIDGE_DESKTOP_TASKS = '0'
620
- $env:CODEX_BRIDGE_AUTOSTART = '1'
621
- codex-mcp-bridge-install.cmd --entry-name codex-bridge-desktop --quiet
622
- if ($LASTEXITCODE -ne 0) { throw 'Shared connector repair failed; review the installer error.' }
623
- } finally {
624
- $env:CLAUDE_DESKTOP_CONFIG = $previousDesktopConfig
625
- $env:CODEX_BRIDGE_DESKTOP_TASKS = $previousDesktopTasks
626
- $env:CODEX_BRIDGE_AUTOSTART = $previousAutostart
627
- }
628
- codex-bridge-setup.cmd --check
629
- ```
630
-
631
- The preview selects the shared configuration path, including an unambiguous MSIX installation; the standalone installer uses that exact file. The temporary environment values are restored even if the repair fails. Then reconnect the shared connector. This explicitly selects its legacy route; native Code handoffs still use `codex-bridge`. Setup does not silently change an existing routing choice to make a check pass.
632
-
633
- ### Microsoft Store Claude or multiple data directories
634
-
635
- **Symptoms:** setup reports multiple Claude Desktop data roots, or discovery cannot match the signed-in account/task despite the correct Code registration.
636
-
637
- Setup detects both the ordinary `%APPDATA%\Claude` directory and Microsoft Store/MSIX package data under `%LOCALAPPDATA%\Packages\...\LocalCache\Roaming\Claude`. It uses verified account state and existing roots to select an unambiguous location; it does not guess between competing installations.
638
-
639
- If selection is ambiguous, identify the data directory used by the running Claude installation and pass that exact directory. Replace the placeholder below before running it:
640
-
641
- ```powershell
642
- $env:CLAUDE_DESKTOP_USER_DATA = 'C:\path\to\active\Claude'
643
- codex-bridge-setup.cmd --dry-run
644
- codex-bridge-setup.cmd
645
- codex-bridge-setup.cmd --check
646
- ```
647
-
648
- `CLAUDE_DESKTOP_USER_DATA` selects the **data directory** used for account/task verification. `CLAUDE_DESKTOP_CONFIG` is a separate optional override for the full path to the shared `claude_desktop_config.json` file. Neither is `CLAUDE_CONFIG_DIR`, which selects the Code configuration directory. If an existing bridge entry pins a different data root, review and update that explicit setting as well: setup preserves custom environment values. Reconnect afterwards. Do not copy sign-in files between roots or publish their contents to diagnose this problem.
649
-
650
- ### Reconnect the actual client
651
-
652
- **Symptoms:** the connector still says `Failed`, tools remain missing, or status still shows the old runtime after installation or a window reload.
653
-
654
- 1. Save the original task/delivery IDs and let active work finish before replacing its connection. A pending or uncertain delivery can intentionally defer automatic worker reload.
655
- 2. In the affected Claude **Code** session, open `/mcp`, select `codex-bridge`, and reconnect. In ordinary Chat, inspect the separate `codex-bridge-desktop` connector. Reconnect the relevant Codex MCP entries in their actual task as needed.
656
- 3. If the client cannot reload that connection, retain its diagnostic until the host reconnects normally. Do not open or create a chat to bootstrap a relay. A window's **Reload** action may refresh its UI while retaining the old Code process and MCP failure state. Separately authorized background work remains available through the independent service when its own prerequisites are satisfied.
657
- 4. Call the status tool from that client and compare its runtime version, registration and sender/relay state. A standalone process answering `initialize`, or printing `ready`, does not verify the app's connection.
658
-
659
- An old worker cannot learn a newly written client environment from a disk update alone. Compatible source changes can reload through the supervisor when idle, but changed launchers/environment or a blocked old connection may still require reconnecting. Do not restart active work merely to clear a receipt or make a status indicator green.
660
-
661
- ### Codex accepted the message, but no answer was returned
662
-
663
- **Symptoms:** `deliveryStatus: accepted`, `turnId: null`, an empty response, or repeated 40-second waits even though a reply is visible in Codex Desktop.
664
-
665
- Acceptance and reply correlation are separate. A null `turnId` means the bridge has not established the exact response turn; it does not mean the prompt was never delivered. A 40-second observation timeout does not cancel the task. Preserve the original `threadId` and `deliveryId`.
666
-
667
- For a normal pending result with `nextAction: wait_codex_reply`, call this **MCP tool**, using the returned receipt:
668
-
669
- ```json
670
- {"deliveryId":"<original-delivery-UUID>","timeoutSec":40}
671
- ```
672
-
673
- Call `wait_codex_reply` sequentially with that same ID while it remains pending. Do not resend the prompt to obtain its answer. Since [1.24.1](CHANGELOG.md#1241---2026-10-29), an accepted send whose reply cannot be verified reports `observation_unavailable` rather than a generic send failure. [1.25.0](CHANGELOG.md#1250---2026-10-30) also ends the specific wait where a new native turn stays finished and idle but cannot be correlated after a bounded grace period and a fresh state check. That change reports uncertainty; it does not invent or recover a reply marker.
674
-
675
- When `nextAction` is `inspect_existing_task`, read the original task with `read_codex_thread`:
676
-
677
- ```json
678
- {"threadId":"<original-thread-ID>","limit":10}
107
+ ```bash
108
+ npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge
679
109
  ```
680
110
 
681
- If an exact response `turnId` was verified, include it for an authoritative turn read. Without it, recent history can omit items and does not prove a visible answer belongs to this delivery. Inspect that original conversation in Codex Desktop when correlation remains unavailable. Retain the receipt and check whether the original work completed before any distinct follow-up. Do not send the original action again, create a replacement task, or attribute the latest unrelated turn to it. An unknown receipt after reconnecting is also not evidence of non-delivery.
682
-
683
- ### Connection timeout versus sender inspection timeout
684
-
685
- These failures occur at different stages:
686
-
687
- | Error | Meaning | Next step |
688
- |---|---|---|
689
- | `CONNECT_TIMEOUT` / connection timed out after `30000ms` | The host did not finish MCP initialization within its connection deadline. | Verify the installed entry point, selected runtime path, setup result and actual client reload; then collect startup timing if it recurs. |
690
- | `process_inspection:INSPECTOR_START_TIMEOUT` | The Windows identity helper did not become ready within its startup deadline. | Retry one read-only status call after the machine settles; retain the startup diagnostic if it repeats. |
691
- | `process_inspection:INSPECTION_TIMEOUT` | The bounded caller-ancestry read could not complete, so the sender remains unverified. | Update both sides and retry status/read/wait sequentially. Inspect the existing receipt if a send may already have been accepted. |
692
-
693
- Setup prewarms immutable runtime snapshots. A line such as `prepared index.mjs runtime ... (reused)` means the runtime **directory** was reused; it does not guarantee a metadata-cache hit or eliminate integrity checks. Several simultaneous MCP starts and slow preparation were observed in a timeout report, but they did not establish its root cause. The reported 30-second initialization timeout was not reproduced during the fix and is **not claimed resolved** by prewarming or configuration repair.
694
-
695
- The older Windows inspector fix in [1.19.1](CHANGELOG.md#1191---2026-09-29) separated helper startup from the ancestry-read deadline. [1.25.0](CHANGELOG.md#1250---2026-10-30) shares only an identical **in-flight** inspection among concurrent callers. Completed results and failures are discarded; later calls still verify current process, task and account identity. This is not a permanent authorization cache or a guarantee that a heavily loaded machine cannot time out.
696
-
697
- For a repeatable failure, capture the app/OS/Node versions, the version reported by the actual MCP, which installation its command uses, the elapsed preparation time, the exact timeout code, and whether several sessions started together. Share sanitized diagnostics, excluding tokens, account data, conversation contents and personal paths. Do not bypass sender verification or raise unrelated timeouts as a substitute for identifying the failed stage.
698
-
699
- ### Relay unavailable, stale pipe, or an active writer
700
-
701
- Normal task creation and delivery run without navigating or focusing Codex Desktop. Use `openInApp: true` only when the user wants to see the target task. The comprehensive install/update command migrates older `CODEX_BRIDGE_OPEN_IN_APP=1` settings to `0`. The internal relay executor is not a user conversation and cannot be opened through the bridge.
702
-
703
- Closing an application window and quitting its native host have different effects. Antigravity's native `runInBackground` setting keeps its sidecar running after the last window closes; Windows defaults to quitting when this setting is off. On Windows, use Codex's native startup task for background startup instead of an additional foreground `shell:AppsFolder` launcher. A healthy loaded relay can recover its worker, but cannot cold-start an unloaded Codex MCP. No periodic task-opening loop is used to simulate readiness.
704
-
705
- **Symptoms:** `RELAY_UNAVAILABLE`, `connect ENOENT`, a missing native relay socket, or `thread ... already has an active writer`.
706
-
707
- Native Desktop handoffs require Codex Desktop to be installed, signed in and running on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. These native-host requirements do not apply to [independent background workers](#independent-background-workers). Recovery never navigates to a task, launches a window, or activates Codex. The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff; pending requests fail without replay, and later requests use the recovered worker. Inherited native pipe hints are rediscovered through the original Desktop process ancestry when they become stale. Requests that never reached the relay wait up to 20 seconds, within their original deadline, for its transport to recover. `CODEX_BRIDGE_RELAY_WAKE=0` disables that wait; the retired `CODEX_BRIDGE_RELAY_KEEPER` flag cannot enable UI navigation.
708
-
709
- Use the available `native_relay_status` and `codex_bridge_status` tools without opening a chat to load them. Native status performs a read-only `list_projects` probe and reports native dispatch separately from socket availability. Recovery requires the original Desktop-owned supervisor to remain alive: it cannot cold-start an unloaded native MCP, and it stops when the MCP client closes. After five unsuccessful worker replacements, report the exact diagnostic. Never open an old, new, empty, failed or internal **Native Relay** chat to bootstrap readiness. Rerun setup if registration/executor configuration is missing, and verify [native relay pipe forwarding](#native-relay-pipe-forwarding). Never persist a pipe address copied from a different app process. Worker hot reload cannot replace a running supervisor from an older release; configuration success alone does not prove that process is upgraded.
710
-
711
- An active-writer error usually identifies the legacy app-server route attempting to attach to a thread already owned by Desktop. Use the registered native Code-to-Desktop route for that conversation. Do not start another app-server or terminate shared work to force access. The ordinary `codex-bridge-desktop` Chat connector remains a legacy app-server connection; it is not a substitute for the verified native sender. An unused `CODEX_APP_SERVER_URL` alongside `external app-server disabled` is not by itself a native connection failure.
712
-
713
- ### Codex cannot reach an existing Claude conversation
714
-
715
- Use native session discovery and peer delivery from the Codex task:
111
+ Use `npx.cmd` on Windows. The skill requires the hosted plugin and a paired connector; it does not install the local bridges.
716
112
 
717
- 1. Call `list_claude_sessions` with the exact absolute `expectedCwd`.
718
- 2. Verify the returned `entrypoint: claude-desktop`, `sessionId`, native `desktop.taskId`, and project directory. Use `read_claude_transcript` with that session identity to confirm the intended unfinished work when needed; a title alone is insufficient.
719
- 3. Call `send_to_claude_session` with the exact session identity as `target`, the independently verified `expectedCwd`, and the returned native ID as `expectedTaskId`. `target: "auto"` plus `expectedTaskId` rediscovers the exact live endpoint without opening the app or chat. A dormant saved task returns `CLAUDE_SESSION_NOT_READY`, `sent: false`.
720
- 4. Preserve the returned `msgId`. After a timeout, inspect it with `read_claude_delivery`; read `read_claude_inbox` for late replies and correlated bridge-status notifications.
721
-
722
- If no eligible session appears, inspect sign-in, data-root selection and sender status using available bridge diagnostics. Saved history does not prove that a native Code endpoint is running. There is no supported silent cold-start API for a dormant Claude task. The bridge reports this limitation instead of opening a chat, using Computer Use, or launching a substitute CLI. Closing a window can preserve native background work; fully quitting the native host removes its receiving endpoint.
723
-
724
- Antigravity's `list_agent_tasks` also reports verified dormant Claude tasks with `status: "dormant"`, `recoverable: false` and `code: "CLAUDE_SESSION_NOT_READY"`. Discovery and sends never open the application or a chat to load its endpoint. Archived tasks, changed accounts, mismatched directories and uncertain sends remain blocked.
725
-
726
- `PEER_REPLY_PENDING` protects an earlier unresolved message. A `held` receipt, `CLAUDE_RECIPIENT_INBOUND_POLICY`, or `CLAUDE_RECIPIENT_CLASS_MISMATCH` identifies an actual recipient policy/permission boundary. Inspect the original receipt and task; resolve the stated policy through the user's intended host settings. Installing a newer bridge does not authorize changing permissions. An `interrupted` bridge-status notification ends observation only: it is not Claude's answer, does not cancel background work, and does not make retrying the original action safe.
727
-
728
- ### Screenshot-ready error reports
729
-
730
- Failures include a **Bridge diagnostic** block in the tool result and `structuredContent.diagnostic` for clients. Capture that block when filing an issue. It contains the exact error and cause codes, component, tool, phase, bridge/Node/platform versions, UTC timestamp, report ID and available request/message/delivery IDs. It excludes request prompts, tokens and account identities and redacts common credential, URL, email and private-path patterns from the error reason. Review any surrounding output before sharing it.
731
-
732
- | Diagnostic | Meaning |
733
- |---|---|
734
- | `RELAY_UNREACHABLE` | Native relay transport could not be reached; this alone does not prove the app is closed. |
735
- | `NATIVE_PIPE_UNAVAILABLE` | The native dispatch pipe could not be verified. |
736
- | `CLAUDE_SESSION_NOT_READY` | The exact saved task has no live native Code endpoint; silent cold-start is unavailable. |
737
- | `CLAUDE_RECIPIENT_INBOUND_POLICY` / `CLAUDE_RECIPIENT_CLASS_MISMATCH` | Native recipient policy or permission classes block the handoff. |
738
- | `CLAUDE_REPLY_TIMEOUT` | A send has no confirmed reply yet; retain its message ID. |
739
- | `MCP_WORKER_EXITED` | A worker exited while handling a request; its delivery may already have happened. |
740
- | `MCP_WORKER_UNAVAILABLE` | This new request was refused before dispatch while its worker was unavailable. |
741
-
742
- `deliveryState: not_sent` means this operation did not send a message. `unknown` means delivery remains uncertain; inspect the original receipt and never automatically resend. `not_applicable` marks a diagnostic read rather than a send. A diagnostic does not instruct an agent to create/open chats, use Computer Use, or change permissions to make the error disappear.
743
-
744
- ### Normal startup output labelled as an error
745
-
746
- Claude may label stderr as `ERR: Server stderr`, including ordinary `[bridge-supervisor] preparing`, `prepared`, and `[codex-mcp-bridge] ready` lines. The label alone is not a failure. Look for the actual connection result, exception, or timeout and verify the tool from the client. Keep diagnostics on stderr: stdout is reserved for MCP protocol messages, and redirecting logs there can break initialization.
747
-
748
- ### Historical fixes by release
749
-
750
- The catalog below records user-visible failures fixed in earlier releases. It is not a list of bugs known to remain in the current version. A similar symptom can have a different cause; use the linked recovery section and verify the **loaded** runtime after upgrading. The changelog links identify the actual fix versions, including later follow-up fixes.
751
-
752
- <details>
753
- <summary>Installation, upgrades, settings and startup</summary>
754
-
755
- | Historical symptom | Fix version and cause | Current recovery |
756
- |---|---|---|
757
- | npm installed the package, but a fresh Code registration or Store-app configuration was missing | [1.25.0](CHANGELOG.md#1250---2026-10-30): complete global setup, initial Code registration, distinct shared connector, MSIX selection and recognized legacy-path migration. | Run the scoped one-command install, `--check`, and the [registration/data-root steps](#claude-code-sender-ancestry-and-the-two-connector-names). Reconnect afterwards. |
758
- | A successful npm install printed “installed version could not be verified” in Claude Code's Bash tool | [1.22.17](CHANGELOG.md#12217---2026-10-22): shell snapshots kept the npm wrapper but dropped its separate helper. | Upgrade and reload an explicitly installed footer's shell/profile; verify the package with `npm list -g`. Do not infer package failure from the old footer warning. |
759
- | Codex entries stayed stale, or installer migration refused an entry containing `env_vars` | [1.22.12](CHANGELOG.md#12212---2026-10-20): launcher migration now preserves the existing TOML entry and inherited native-pipe environment. | Run current setup and reconnect. Custom settings that cannot be preserved automatically still require reviewing the reported conflict. |
760
- | Homebrew upgrade/cleanup removed a registered Cellar path; a symlinked supervisor exited without serving MCP | [1.22.7](CHANGELOG.md#1227---2026-10-20): stable `opt` paths, symlink entry detection and upgrade tracking. | Run `brew upgrade buidangminh23/tap/codex-mcp-bridge`, then `codex-bridge-setup`. Verify command paths use the intended install channel. Later [1.22.12](CHANGELOG.md#12212---2026-10-20) also handles the old `env_vars` migration obstacle. |
761
- | Project-local installation failed with `ENOENT` / `scandir ... node_modules` | [1.19.2](CHANGELOG.md#1192---2026-09-29): runtime preparation now follows Node's hoisted dependency graph instead of requiring a nested dependency directory. | Upgrade the actual local dependency if keeping that installation, or select global setup deliberately. A global update does not replace a separately registered local copy. |
762
- | Updating files did not update an already-running MCP; cached startup repeatedly reread dependency contents | [1.15.0](CHANGELOG.md#1150---2026-09-07): stable supervisors and idle reload. [1.15.1](CHANGELOG.md#1151---2026-09-14): validated hash metadata and startup timing. | Migrate old direct launchers through setup, reconnect once and inspect reload blockers. Pending deliveries are not disposable; cached preparation does not guarantee a connection deadline. |
763
- | Re-running the Desktop installer erased custom roots, allowed threads or newer entry properties | [1.11.1](CHANGELOG.md#1111---2026-08-23), extended in [1.15.0](CHANGELOG.md#1150---2026-09-07): preserve existing settings during upgrades. | Use current setup without resetting configuration. If an old version already removed values, recover only the intended settings from a verified backup. |
764
- | The second bridge reported a hardcoded older version | [1.10.1](CHANGELOG.md#1101---2026-08-20): version synchronization covers both bridge entry points. | Compare installed version and actual client status. Current mismatches usually require checking the selected path or running process rather than trusting one CLI banner. |
765
- | Windows Git Bash found no sessions under a custom `HOME`; a trimmed GUI `PATH` broke startup | [1.10.0](CHANGELOG.md#1100---2026-08-20): consistent Windows home resolution. [1.1.0](CHANGELOG.md#110---2026-08-17) / [1.2.0](CHANGELOG.md#120---2026-08-17): child PATH and process-tool startup fixes. | Verify the intended home/config overrides and resolved Node command. Reopen the terminal after PATH changes and regenerate the affected registration. |
766
- | Legacy app-server startup failed because an administrator-managed Codex policy omitted `read-only` | [1.19.4](CHANGELOG.md#1194---2026-10-02): report the policy incompatibility before a generic connection failure. [1.19.6](CHANGELOG.md#1196---2026-10-02): correct readability of policies created by the explicit administrator setup. | Have the policy owner review the reported compatibility/readability error. Ordinary bridge setup does not rewrite administrator policy or require blanket Full access. |
767
- | Closed MCP clients left orphan workers/sockets; Windows cleanup found files still in use | [1.19.2](CHANGELOG.md#1192---2026-09-29): inspector cleanup. [1.22.11](CHANGELOG.md#12211---2026-10-20) / [1.22.14](CHANGELOG.md#12214---2026-10-21): worker shutdown, draining and dead-socket cleanup. | Upgrade and close affected clients after accepted work finishes. Inspect remaining process ownership instead of killing every Node process or deleting active sockets. |
768
-
769
- </details>
770
-
771
- <details>
772
- <summary>Native relay, project selection and sender/recipient identity</summary>
773
-
774
- | Historical symptom | Fix version and cause | Current recovery |
775
- |---|---|---|
776
- | Relay vanished after app restart or was absent when a companion first started | [1.25.2](CHANGELOG.md#1252---2026-10-31): silent worker recovery and stale-pipe rediscovery replace the historical task wake and keeper. | Follow [relay recovery](#relay-unavailable-stale-pipe-or-an-active-writer). Reconnect MCP once after upgrading the supervisor; an idle app with no loaded MCP session cannot be cold-started by silent recovery. |
777
- | `No handler registered for method: tools/call` or `RELAY_UNAVAILABLE` after a Codex Desktop update | [1.18.2](CHANGELOG.md#1182---2026-09-26): native caller-source compatibility. [1.22.13](CHANGELOG.md#12213---2026-10-20): discover Windows `codex-app-tools-*` pipes instead of probing only browser pipes. | Update/reload the native companion as well as the sending bridge. Check `native_relay_status`; never copy a foreign process's pipe to bypass discovery. |
778
- | A Windows task opened successfully, but `open_codex_thread` or relay wake reported failure | [1.22.14](CHANGELOG.md#12214---2026-10-21): replace reliance on `explorer.exe`'s misleading exit code with the native URI launcher. | Upgrade/reconnect and inspect the opened task. A navigation error is not evidence that an accepted prompt should be sent again. |
779
- | A macOS companion appeared installed but every native delivery was unconfirmed | [1.13.4](CHANGELOG.md#1134---2026-09-06): use the Codex-bundled runtime trusted by Desktop. | Run current setup with Codex Desktop installed and reconnect. Keep the runtime selected by the installer; an arbitrary Homebrew/nvm Node may not satisfy native host checks. |
780
- | “Already has an active writer” / “open in another app” when sending to a visible Codex task | [1.12.0](CHANGELOG.md#1120---2026-09-04): native delivery avoids a second writer. [1.13.1](CHANGELOG.md#1131---2026-09-05): Desktop mode no longer depends on the external app-server. | Use the native Code-to-Desktop route. Legacy app-server tasks and shared Chat routing retain their separate behavior; do not stop other delegations to force access. |
781
- | Windows replies were one-way or live sessions disappeared during registry rewrites | [1.11.3](CHANGELOG.md#1113---2026-09-03) / [1.12.1](CHANGELOG.md#1121---2026-09-05): Windows named pipes and stable session discovery. [1.15.2](CHANGELOG.md#1152---2026-09-14): accept Claude's `procStart` identity field alongside `procStartFt`. | Update both registrations, reopen the intended Code session if needed, and verify its exact native task and session identity. |
782
- | An account switch, a large task database or a concurrent metadata update hid an otherwise valid Claude task | [1.14.0](CHANGELOG.md#1140---2026-09-07): per-call account discovery, including Store data. [1.18.1](CHANGELOG.md#1181---2026-09-25): bounded discovery beyond 32 MiB. [1.22.3](CHANGELOG.md#1223---2026-10-15): retry changed metadata snapshots. | Check sign-in and [data-root selection](#microsoft-store-claude-or-multiple-data-directories), then rediscover. Conflicting, archived or persistently changing identities still fail closed; shared Chat still cannot prove Code ancestry. |
783
- | Windows ancestry checks expired while PowerShell was still starting | [1.19.1](CHANGELOG.md#1191---2026-09-29): separate startup/read deadlines. [1.25.0](CHANGELOG.md#1250---2026-10-30): coalesce identical simultaneous inspections. | Use the [timeout diagnostic steps](#connection-timeout-versus-sender-inspection-timeout). These changes do not establish a fix for every MCP initialization timeout. |
784
- | Ordinary managed Codex tasks were rejected as unverified senders; some review flags caused incorrect permission classification | [1.19.0](CHANGELOG.md#1190---2026-09-29): support verified managed prompting profiles. [1.13.6](CHANGELOG.md#1136---2026-09-06): correct human-review classification. | Upgrade and inspect `claude_bridge_status`. A real recipient class/inbound-policy mismatch remains a denial; do not change sandbox or approval settings merely to suppress it. |
785
- | Dormant Claude tasks could not resume; a new Windows conversation opened in “No folder”; an app update broke its URI launcher | [1.19.7](CHANGELOG.md#1197---2026-10-02): exact-task recovery and composer verification. [1.25.3](CHANGELOG.md#1253---2026-11-01): removes implicit app/chat reopening from recovery. | `target: "auto"` rediscovers an existing live endpoint only. A dormant task reports `CLAUDE_SESSION_NOT_READY`; never open or create a chat to load a relay. A moved directory remains an unverified discovery candidate. |
786
- | A listed human-created thread returned `NOT AUTHORIZED`; a path from another computer resolved incorrectly | [1.11.0](CHANGELOG.md#1110---2026-08-23): explicit thread policy. [1.8.0](CHANGELOG.md#180---2026-08-19) / [1.11.2](CHANGELOG.md#1112---2026-08-28): usable cross-machine path resolution. | Verify the exact saved project and intended grant/thread policy. Listing and mutation have different authorization requirements; setup preserves existing restrictions and cannot authorize a different project. |
787
- | An Antigravity App restart could leave a sidecar attached to the retired parent | [1.24.0](CHANGELOG.md#1240---2026-10-28): sidecars track native parent identity and exit when that parent stops. | Use current setup and reconnect through the active App. An App receipt confirms native acceptance only; App reply forwarding and new App conversation creation remain unsupported. |
788
-
789
- </details>
113
+ ## Troubleshooting
790
114
 
791
- <details>
792
- <summary>Missing replies, pending receipts, duplicate prevention and legacy connection failures</summary>
115
+ Rerun the installation command to update, or `codex-bridge-setup` to repair settings. Use `--dry-run` to preview changes and `--check --json` to inspect configuration. Add `.cmd` on Windows.
793
116
 
794
- | Historical symptom | Fix version and cause | Current recovery |
795
- |---|---|---|
796
- | An accepted Codex send looked failed, or waited despite a finished visible turn | [1.24.1](CHANGELOG.md#1241---2026-10-29): distinguish unavailable observation and accept valid causal-root metadata. [1.25.0](CHANGELOG.md#1250---2026-10-30): bound stable-idle unmatched observation. | Follow [accepted-delivery recovery](#codex-accepted-the-message-but-no-answer-was-returned). Neither fix permits attaching an unrelated visible reply or resending the original action. |
797
- | Claude stayed at `PEER_REPLY_PENDING` after a background command completed or another peer interrupted it | [1.22.20](CHANGELOG.md#12220---2026-10-24): recognize interruption boundaries. [1.22.21](CHANGELOG.md#12221---2026-10-26): inline completion attachments and out-of-order ancestry. [1.24.1](CHANGELOG.md#1241---2026-10-29): correlated interruption notifications. | Keep the original `msgId`, inspect `read_claude_delivery` and the existing task. A genuine pending background command remains protected; interruption is not cancellation. |
798
- | Claude's reply appeared in the app but the bridge timed out when the message arrived mid-turn or after compaction | [1.13.7](CHANGELOG.md#1137---2026-09-07) / [1.13.9](CHANGELOG.md#1139---2026-09-07): queued-message formats. [1.22.5](CHANGELOG.md#1225---2026-10-19) / [1.22.15](CHANGELOG.md#12215---2026-10-22): verified compaction continuations. | Inspect the same receipt/transcript. `replyAbsorbed: true` means the turn's closing text may not answer the injected message; do not assume it is a separate completed response. |
799
- | A short `wait_codex_reply` falsely said another operation held the thread | [1.22.18](CHANGELOG.md#12218---2026-10-22): distinguish an exhausted caller-check budget from an actual held thread. | Update and continue sequential waits with the original delivery ID. If an operation really holds the thread, retain its receipt and wait for it rather than starting another send. |
800
- | Older Codex tasks had no trusted pre-send watermark or returned empty replies | [1.22.14](CHANGELOG.md#12214---2026-10-21): read `.jsonl.zst` rollouts and follow rematerialization as plain JSONL. | Update and use Node with zstd support (22.15+ or 23.8+). The package's 22.13 minimum alone does not guarantee compressed-rollout support. Inspect the original task; do not manufacture a new watermark by resending. |
801
- | `A rollout segment changed while reading`, or a same-size Claude transcript update was missed | [1.22.10](CHANGELOG.md#12210---2026-10-20): bounded retry of concurrent rollout appends. [1.22.9](CHANGELOG.md#1229---2026-10-20): precise transcript change detection. | Repeat the original read/wait after updating. Persistently incomplete, replaced or conflicting files still report unavailable; do not edit transcripts or receipts to force validation. |
802
- | Reply observation broke after relay recovery, or large tool output overflowed transport limits | [1.21.6](CHANGELOG.md#1216---2026-10-12): bounded snapshot fallback and larger response frames. [1.22.0](CHANGELOG.md#1220---2026-10-12): filtered/cursor-paged reads. | Update both bridge and companion. Use exact-turn reads or bounded `responsePreferences` pages; default history omits tool output and is not a complete transcript export. |
803
- | A completed Codex reply failed exact validation because of a separate memory citation | [1.22.0](CHANGELOG.md#1220---2026-10-12): reconstruct validated citation metadata. [1.22.5](CHANGELOG.md#1225---2026-10-19): preserve exact empty citation formatting and same-turn replies. | Retry observation of the original delivery on the updated runtime. A real reply-ID/hash/history conflict is still rejected. |
804
- | An accepted creation lost its ID after an account switch temporarily reported workspace `/`; acceptance became unconfirmed after reload | [1.22.6](CHANGELOG.md#1226---2026-10-20): preserve the accepted creation and wait for workspace assignment. [1.22.5](CHANGELOG.md#1225---2026-10-19): persist send acceptance. | Retain `threadId`/`deliveryId` and continue `wait_codex_reply`. A wrong project or changed account still blocks access; never recreate the task just to get its answer. |
805
- | Concurrent calls created duplicate tasks, or a new independent task reused an older task with the same title | [1.13.2](CHANGELOG.md#1132---2026-09-05): durable creation deduplication. [1.19.0](CHANGELOG.md#1190---2026-09-29): explicit independent `requestId`. [1.21.0](CHANGELOG.md#1210---2026-10-06): durable reply continuation. | Keep the same request ID for recovery of one creation; use a fresh ID only for separately authorized independent work. Continue unfinished work in its original thread. |
806
- | A socket write looked like confirmed Claude delivery; Unicode split across frames was corrupted; another delegation stopped during handoff | [1.12.4](CHANGELOG.md#1124---2026-09-05): authenticated Windows transport and correlated receipts. [1.12.2](CHANGELOG.md#1122---2026-09-05): UTF-8 framing, independent thread lifecycle and no unsafe fallback retry. | Read the original receipt/inbox. Socket acceptance, recipient acceptance and completed reply remain distinct; never route an uncertain send through a second backend. |
807
- | Legacy app-server turns hung after disconnect, failed `turn/start` killed MCP, or a permissions/tool request silently stalled | [1.5.0](CHANGELOG.md#150---2026-08-18): reconnect and disconnect handling. [1.6.0](CHANGELOG.md#160---2026-08-19): contain failed-turn rejection. [1.4.0](CHANGELOG.md#140---2026-08-18): correct server-request responses. | Upgrade the actual legacy runtime, reread the original thread after reconnect, and handle any real approval/input request through the host. A transport recovery does not prove unfinished work should be repeated. |
117
+ Include the **Bridge diagnostic** block when [reporting an issue](https://github.com/buidangminh23/codex-mcp-bridge/issues). Retain the original request/delivery ID after a timeout and remove private data from surrounding logs.
808
118
 
809
- </details>
119
+ ## Documentation
810
120
 
811
- [Full changelog](CHANGELOG.md) · [Additional reference](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#troubleshooting) · [Report an issue](https://github.com/buidangminh23/codex-mcp-bridge/issues)
121
+ - [Windows setup and recovery](docs/new-windows-setup.md)
122
+ - [macOS setup and recovery](docs/new-macos-setup.md)
123
+ - [Project authorization](docs/project-onboarding.md)
124
+ - [Daily Desktop handoffs](docs/daily-handoffs.md)
125
+ - [Tools, settings, SSH, and technical details](REFERENCE.md)
126
+ - [Homebrew installation](https://github.com/buidangminh23/homebrew-tap)
127
+ - [Changelog](CHANGELOG.md) · [Releases](https://github.com/buidangminh23/codex-mcp-bridge/releases)
812
128
 
813
129
  ## Optional active-install statistics
814
130
 
815
- Usage reporting is **off by default**. Manage it with `codex-mcp-bridge telemetry enable`, `telemetry status`, or `telemetry disable`. Reports contain a random installation ID, UTC day, version, and OS; no chat content, paths, account identity, or credentials. `DO_NOT_TRACK=1` or `CODEX_BRIDGE_TELEMETRY=0` disables reporting. Disabling removes the local ID; submitted records expire after 90 days during ingestion.
131
+ Usage reporting is **off by default**. Use `codex-mcp-bridge telemetry status` to inspect it, or `telemetry enable` / `telemetry disable` to change it. Reports include a random installation ID, UTC day, version, and OS; no chats, paths, accounts, or credentials. `DO_NOT_TRACK=1` or `CODEX_BRIDGE_TELEMETRY=0` disables reporting.
816
132
 
817
- [Analytics dashboard](https://buidangminh23.github.io/codex-mcp-bridge/) · [Release notes](https://github.com/buidangminh23/codex-mcp-bridge/releases) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE)
133
+ [Analytics](https://buidangminh23.github.io/codex-mcp-bridge/) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE)
package/docs/new-macos-setup.md CHANGED
@@ -15,17 +15,22 @@ separately authenticated provider CLIs and do not require open Desktop apps.
15
15
  Use the same command for a fresh installation and every update:
16
16
 
17
17
  ```bash
18
- npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
18
+ npx -y @minhspark/codex-mcp-bridge@latest
19
19
  ```
20
20
 
21
- npm downloads the latest updater into its cache. `--ignore-scripts` suppresses
22
- setup in that temporary location. The updater installs its exact resolved
21
+ Run this directly in an interactive terminal. The bare npm package launch
22
+ selects the complete updater. The updater installs its exact resolved
23
23
  version globally with lifecycle scripts disabled, runs managed setup directly
24
24
  using Node and verifies the global version and configuration. No second installation or
25
25
  setup command is required. Existing disabled choices, authentication and custom
26
26
  project grants are preserved; the updater does not open apps or chats or kill
27
27
  processes. A pending service migration is reported instead of interrupting work.
28
28
 
29
+ For scripts or redirected input/output, use
30
+ `npx -y --ignore-scripts -p @minhspark/codex-mcp-bridge@latest codex-bridge-update`.
31
+ MCP clients keep using the normal stdio launch; piped launches do not select
32
+ the terminal updater.
33
+
29
34
  Setup registers the local bridges, adds native pipe forwarding, and bootstraps
30
35
  the relay executor. It reuses an available Codex CLI or installs a pinned
31
36
  official package under `~/.config/GptClaudeBridge/tools` (or
@@ -106,9 +111,8 @@ managed setup directly after package installation. For Homebrew, run
106
111
  `codex-bridge-setup` after installing the formula. A pinned source checkout can
107
112
  use `node scripts/setup.mjs`.
108
113
 
109
- The [manual macOS commands](../README.md#macos-terminal) and
110
- [Claude Code registration commands](../README.md#register-claude-code) remain
111
- available for selective configuration. `codex-bridge-code-install --install`
114
+ See [project onboarding](project-onboarding.md) for shared authorization and
115
+ selective configuration. `codex-bridge-code-install --install`
112
116
  can create a missing user-level Code entry; its existing policy migration mode
113
117
  is described in [project onboarding](project-onboarding.md). Use intended
114
118
  project paths when setting explicit `CODEX_BRIDGE_ALLOWED_ROOTS`; macOS
package/docs/new-windows-setup.md CHANGED
@@ -7,17 +7,28 @@ does not require the Desktop apps to be open. Use this one PowerShell command
7
7
  for a fresh installation or an update, including from 1.26.0 or 1.26.1:
8
8
 
9
9
  ```powershell
10
- npx.cmd --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user
10
+ npx.cmd -y @minhspark/codex-mcp-bridge@latest
11
11
  ```
12
12
 
13
- npm downloads the latest updater into its cache. `--user` selects `%APPDATA%\npm`
14
- instead of a protected Node installation directory such as `Program Files`;
13
+ Run this directly in an interactive terminal. The bare npm package launch
14
+ selects the complete updater and defaults to `%APPDATA%\npm` on Windows instead
15
+ of a protected Node installation directory such as `Program Files`;
15
16
  administrator rights are not required. The updater installs its exact resolved
16
17
  version globally with lifecycle scripts disabled, then runs managed setup
17
18
  directly using Node. It displays progress and verifies the global version,
18
19
  saved settings and relay activation.
19
20
  No second installation or setup command is required.
20
21
 
22
+ For scripts or redirected input/output, select the updater explicitly:
23
+
24
+ ```powershell
25
+ npx.cmd -y --ignore-scripts -p @minhspark/codex-mcp-bridge@latest codex-bridge-update --user
26
+ ```
27
+
28
+ MCP clients keep using the package's normal stdio launch. Piped launches do not
29
+ select the terminal updater. An installed package also accepts
30
+ `codex-mcp-bridge.cmd update` for an explicit update from that package version.
31
+
21
32
  An older Windows background service can keep the global npm package directory
22
33
  locked as its working directory. Before replacing the package, the updater
23
34
  moves only this package's owned legacy service to newer code using private relay
package/docs/project-onboarding.md CHANGED
@@ -4,11 +4,15 @@ One command installs or updates the global package, registers the bridges and
4
4
  configures the independent worker relay automatically:
5
5
 
6
6
  ```sh
7
- npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
7
+ npx -y @minhspark/codex-mcp-bridge@latest
8
8
  ```
9
9
 
10
- In Windows PowerShell use `npx.cmd --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update --user` to select the per-user npm prefix without administrator rights. npm fetches the latest updater into its
11
- cache with setup disabled there. The updater moves an owned legacy service to
10
+ Run it directly in an interactive terminal. In Windows PowerShell use
11
+ `npx.cmd -y @minhspark/codex-mcp-bridge@latest`; it selects the per-user npm
12
+ prefix without administrator rights. For scripts or redirected terminals, use
13
+ the explicit updater in the [Windows](new-windows-setup.md) or
14
+ [macOS](new-macos-setup.md) guide. Normal MCP client launches keep serving stdio.
15
+ The updater moves an owned legacy service to
12
16
  newer code using private relay storage as its working directory when needed,
13
17
  temporarily using the downloaded updater package. It waits for active work to
14
18
  drain, then installs its exact resolved version globally with lifecycle scripts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minhspark/codex-mcp-bridge",
3
- "version": "1.26.5",
3
+ "version": "1.26.7",
4
4
  "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
5
5
  "keywords": [
6
6
  "mcp",
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "codex-mcp-bridge",
4
- "version": "1.26.5",
4
+ "version": "1.26.7",
5
5
  "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
6
6
  "author": {
7
7
  "name": "Bui Dang Minh",
package/scripts/install-native-relay.mjs CHANGED
@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
25
25
 
26
26
  exitForVersionRequest(import.meta.url);
27
27
 
28
- const VERSION = "1.26.5";
28
+ const VERSION = "1.26.7";
29
29
  const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
30
30
  const entry = path.join(root, "src", "mcp-supervisor.mjs");
31
31
  const entryArgs = ["native-relay-companion.mjs"];
package/scripts/update.mjs CHANGED
@@ -211,9 +211,7 @@ export async function runUpdate({ args = [], env = process.env, platform = proce
211
211
  return { updated: true, configured: true, version, previousVersion, migrated, service, opensApps: false, opensChats: false };
212
212
  }
213
213
 
214
- if (isMainModule(process.argv[1], import.meta.url)) {
215
- exitForVersionRequest(import.meta.url);
216
- const args = process.argv.slice(2);
214
+ export async function runUpdateCli(args = process.argv.slice(2)) {
217
215
  try {
218
216
  process.chdir(neutralDirectory([ROOT], process.env));
219
217
  const result = await runUpdate({ args, onProgress: message => process.stderr.write(`${message}\n`) });
@@ -226,3 +224,8 @@ if (isMainModule(process.argv[1], import.meta.url)) {
226
224
  process.exitCode = 1;
227
225
  }
228
226
  }
227
+
228
+ if (isMainModule(process.argv[1], import.meta.url)) {
229
+ exitForVersionRequest(import.meta.url);
230
+ await runUpdateCli();
231
+ }
package/src/claude-bridge.mjs CHANGED
@@ -31,7 +31,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
31
31
 
32
32
  exitForVersionRequest(import.meta.url);
33
33
 
34
- const VERSION = "1.26.5";
34
+ const VERSION = "1.26.7";
35
35
  void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
36
36
  const FORWARD_MIN_INTERVAL_MS = 5000;
37
37
  const FORWARD_MAX_PER_SESSION = 50;
package/src/codex-bridge-launcher.mjs CHANGED
@@ -1,11 +1,39 @@
1
1
  #!/usr/bin/env node
2
2
  import { runSupervisor } from "./mcp-supervisor.mjs";
3
3
  import { handleTelemetryCommand } from "./telemetry.mjs";
4
- if (process.argv[2] === "setup") {
4
+ import { exitForVersionRequest } from "./cli-version.mjs";
5
+ import { isMainModule } from "./install-paths.mjs";
6
+
7
+ async function applySetup(args) {
5
8
  const { runSetup, printSetup } = await import("./setup.mjs");
6
- try {
7
- const result = runSetup({ args: process.argv.slice(3) });
8
- printSetup(result, { json: process.argv.includes("--json") });
9
- if (result.configured === false && !result.dryRun) process.exitCode = 1;
10
- } catch (error) { process.stderr.write(`Bridge setup: ${error.message}\n`); process.exitCode = 1; }
11
- } else if (!await handleTelemetryCommand(process.argv.slice(2))) await runSupervisor("index.mjs");
9
+ const result = runSetup({ args });
10
+ printSetup(result, { json: args.includes("--json") });
11
+ return result;
12
+ }
13
+
14
+ export async function runLauncher({ args = process.argv.slice(2), env = process.env, platform = process.platform,
15
+ input = process.stdin, output = process.stdout, errorOutput = process.stderr, supervise = runSupervisor,
16
+ telemetry = handleTelemetryCommand, setup = applySetup,
17
+ updateCli = async args => (await import("../scripts/update.mjs")).runUpdateCli(args) } = {}) {
18
+ const terminalUpdate = args.length === 0 && env.npm_command === "exec" && input.isTTY === true && output.isTTY === true;
19
+ if (terminalUpdate || args[0] === "update") {
20
+ const updateArgs = terminalUpdate ? [] : args.slice(1);
21
+ return updateCli(platform === "win32" && !updateArgs.includes("--user") ? ["--user", ...updateArgs] : updateArgs);
22
+ }
23
+ if (args[0] === "setup") {
24
+ try {
25
+ const result = await setup(args.slice(1));
26
+ return result.configured === false && !result.dryRun ? 1 : 0;
27
+ } catch (error) {
28
+ errorOutput.write(`Bridge setup: ${error.message}\n`);
29
+ return 1;
30
+ }
31
+ }
32
+ if (!await telemetry(args)) return supervise("index.mjs");
33
+ }
34
+
35
+ if (isMainModule(process.argv[1], import.meta.url)) {
36
+ exitForVersionRequest(import.meta.url);
37
+ const exitCode = await runLauncher();
38
+ if (Number.isInteger(exitCode)) process.exitCode = exitCode;
39
+ }
package/src/index.mjs CHANGED
@@ -44,7 +44,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
44
44
 
45
45
  exitForVersionRequest(import.meta.url);
46
46
 
47
- const VERSION = "1.26.5";
47
+ const VERSION = "1.26.7";
48
48
  void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
49
49
  const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
50
50
 
package/src/native-relay-companion.mjs CHANGED
@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
43
43
 
44
44
  exitForVersionRequest(import.meta.url);
45
45
 
46
- const VERSION = "1.26.5";
46
+ const VERSION = "1.26.7";
47
47
  const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
48
48
 
49
49
  function errorResponse(code, message, sent, details) {
package/src/setup.mjs CHANGED
@@ -179,7 +179,7 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
179
179
 
180
180
  export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
181
181
  const options = setupArguments(args);
182
- if (options.help) return { help: `Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings with: ${platform === "win32" ? "npx.cmd" : "npx"} --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update${platform === "win32" ? " --user" : ""}\nThe updater installs the package with lifecycle scripts disabled, then directly configures Claude Desktop, Claude Code, Codex, Antigravity and the independent worker relay. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration, background relay health and loaded native app connections are verified separately.` };
182
+ if (options.help) return { help: `Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings in an interactive terminal with: ${platform === "win32" ? "npx.cmd" : "npx"} -y @minhspark/codex-mcp-bridge@latest\nThe updater installs the package with lifecycle scripts disabled, then directly configures Claude Desktop, Claude Code, Codex, Antigravity and the independent worker relay. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration, background relay health and loaded native app connections are verified separately.` };
183
183
  if (options.postinstall && !automaticSetupEnabled(env)) return { skipped: true, reason: "Automatic configuration runs only for a global npm install; use codex-bridge-setup for manual setup." };
184
184
  if (options.check) return checkSetup({ env, platform, root, run, resolve });
185
185
  const native = platform === "win32" || platform === "darwin";