@minhspark/codex-mcp-bridge 1.25.3 → 1.26.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.25.3",
+  "version": "1.26.1",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,53 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.26.1] - 2026-11-01
+
+### Upgrade
+
+Update the package and reapply all managed client and background-service settings with the same command:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+```
+
+Use `npm.cmd` in Windows PowerShell. Setup does not open apps or chats.
+
+### Fixed
+
+- Read-only background-service checks validate the installed runtime environment. A normal terminal no longer reports a healthy service as unconfigured merely because npm added temporary entries to `PATH` during installation. Package, startup ownership and running-runtime identity checks remain in place.
+
+## [1.26.0] - 2026-11-01
+
+### Upgrade
+
+The same single command updates the package, reapplies managed client settings and configures the independent background service:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+```
+
+Use `npm.cmd` in Windows PowerShell. Setup applies the managed client registrations, background startup and scoped worker communication settings, including Antigravity's four relay tool grants. CLI authentication and explicit project grants remain separate from installing configuration; no Desktop credentials are copied and no existing denials are removed. Setup supplies a missing Codex CLI; Claude Code and `agy` must be installed separately when those workers are needed.
+
+### Added
+
+- An independent per-user relay and separate Codex, Claude and Antigravity CLI workers, supporting all six worker-to-worker directions. Background jobs and cross-worker messages can continue without a responsive Desktop host. Native conversations retain their existing native routing and are never silently replaced by worker sessions.
+- Durable job receipts, authenticated local transport, same-project delegation, bounded queues and delegation depth, and persistent diagnostic reports. Interrupted sends stay unknown; only proven queued work resumes after daemon restart.
+- Background worker status, discovery, send and receipt tools plus the `worker-relay` command. Service readiness, CLI authentication and model execution evidence are reported separately.
+- Managed background startup and recovery on Windows, macOS and Linux, with hidden Windows launches and idle adoption of updated service code. Setup preserves disabled services and reports pending activation honestly.
+
+### Fixed
+
+- Antigravity MCP registrations use managed supervisors so future package updates can replace idle workers without reconnecting the host. Live CLI sessions and unconfirmed deliveries defer reload; crashed operations are never replayed.
+- Worker CLI launches isolate their session identity from native Desktop chats. Claude worker launches suppress optional user/plugin startup hooks without changing authentication or permission policy.
+- Antigravity worker discovery accepts the CLI's native MCP dispatcher when initialization does not enumerate individual server tools. Dispatcher availability is reported separately from verified relay-tool discovery; missing relay tools and permission failures still produce typed diagnostics.
+
+### Validation and limits
+
+- Live Windows checks completed all six directions between Codex, Claude and Antigravity workers with Antigravity CLI 1.4.12. A saturated delegation returned `WORKER_DELEGATION_CAPACITY` with `not_sent` instead of queuing behind waiting workers.
+- Closed or frozen Desktop apps do not host these workers. A frozen UI cannot accept new user input or display results until it responds; a terminal's `worker-relay` command or another responsive MCP client can submit authorized background work and read receipts.
+- Execution still requires a running operating system and per-user service, installed and authenticated provider CLIs, an authorized project, network/provider availability, quota and effective tool permissions. Saved configuration is not a guarantee of readiness or a live verification result on another machine.
+
 ## [1.25.3] - 2026-11-01
 
 ### Upgrade

package/README.md

@@ -15,15 +15,15 @@
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge" height="20" alt="license" /></a>
 </p>
 
-Connect **Claude, Codex, and Antigravity** through MCP, keeping work in each agent's own app and preserving native identity and permission checks. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
+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.
 
-The optional **Antigravity bridge** sends work both ways between existing Desktop conversations in the same project. Codex and Claude can also start and continue bridge-owned Antigravity CLI streaming sessions. Antigravity App replies remain in the App; outbound calls from Antigravity CLI are not supported. [Setup and current limits](#antigravity-app-and-cli).
+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).
 
 https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
 
 ## Installation
 
-One global npm command installs the package and configures the local Claude, Codex, and Antigravity bridges. Install and sign in to the apps you intend to use first. Setup preserves existing project restrictions and custom settings; it does not sign in, grant workspace trust, change permission modes, or restart running apps.
+One global npm command installs the package, configures the local Claude, Codex and Antigravity bridges, and installs 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.
 
 ### Package — npm
 
@@ -39,7 +39,27 @@ npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/cod
 npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
-Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. **Every release uses this same single install/update command.** It updates the package, applies the managed bridge settings across Claude, Codex and Antigravity, and verifies the saved registrations. Comprehensive 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, permissions, project grants and unrelated custom registrations remain unchanged. 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.
+Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. **Every release uses this same single install/update command.** It updates the package, applies the managed bridge settings across Claude, Codex and Antigravity, configures the independent background worker relay, and verifies saved registrations and service activation separately. Comprehensive 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.
+
+### Independent background workers
+
+`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.
+
+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.
+
+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.
+
+`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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
 
 `--allow-scripts=@minhspark/codex-mcp-bridge` authorizes only this package's setup hook. npm versions that block install scripts by default need this flag; a plain install works only when the hook is allowed. `--foreground-scripts` displays configuration progress and failures that npm otherwise hides. If npm prints `1 package had install scripts blocked`, rerun the recommended command or run `codex-bridge-setup` explicitly.
 
@@ -51,6 +71,7 @@ Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows P
 | Codex Desktop, Windows/macOS | `codex-native-relay` | Native delivery, pipe forwarding, and relay executor bootstrap |
 | Codex and Claude Code | `antigravity-bridge` | Send to Antigravity App or bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound agent messages and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
 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.
 
@@ -99,18 +120,19 @@ Run `codex-bridge-setup` after installing through Homebrew. The installers recor
 | Codex → Claude Desktop Code | Automatic `claude-bridge` registration |
 | Codex / Claude Desktop Code → Antigravity App or CLI | Automatic Antigravity registrations |
 | Antigravity App → Codex / Claude Desktop Code | Automatic outbound registration and sidecar |
+| Codex ↔ Claude ↔ Antigravity CLI workers | Automatic independent relay setup; provider CLIs, authentication and project grants required |
 | Claude Code ↔ Codex inside VS Code | Separate Windows preview registrations below |
 | ChatGPT → paired Codex Desktop | Hosted plugin plus `codex-sites-connector --pair` |
 
 ### Antigravity App and CLI
 
-The global npm setup registers all Antigravity components. Install and sign in to the Antigravity App and/or `agy` CLI to use them. The following commands are optional for selective manual setup or repair:
+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:
 
 ```bash
 antigravity-mcp-bridge-install --all
 ```
 
-**Windows PowerShell — all components**
+**Windows PowerShell — all native bridge components**
 
 ```powershell
 antigravity-mcp-bridge-install.cmd --all
@@ -140,9 +162,9 @@ antigravity-mcp-bridge-install --desktop
 antigravity-mcp-bridge-install --all --dry-run
 ```
 
-Use `.cmd` for each command on Windows. `--all` includes all three components; the individual commands are alternatives when only some clients are needed. The installer preserves unrelated configuration and native permissions. Reload Codex/Claude to load the new MCP server. 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.
+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.
 
-The `agy` CLI must be installed and signed in separately. CLI sessions are started through the `start_antigravity_cli_session` MCP tool; 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.
+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.
 
 | Tool | Behavior |
 | --- | --- |
@@ -153,17 +175,17 @@ The `agy` CLI must be installed and signed in separately. CLI sessions are start
 | `read_antigravity_delivery` | Reads the original receipt without resending. |
 | `close_antigravity_cli_session` | Closes an idle CLI session owned by the sender. |
 
-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 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.
+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.
 
-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. Open the exact App conversation to read its response. 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.
+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.
 
-The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.gemini/config/mcp_config.json`. Reload the App after installation to discover it. From an Antigravity conversation, ask the agent to 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.
+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.
 
-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.
+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.
 
-If a caller says the bridge only supports one-way messaging, reload its `antigravity-bridge` MCP server after updating: older initialization instructions incorrectly denied the separate outbound route. An unavailable inbound sidecar does not prove that the App is closed or that outbound messaging is unsupported. If the App is already running, inspect its `codex-bridge` sidecar; check `agent_bridge_status` from Antigravity to verify outbound readiness independently.
+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.
 
-Outbound support targets existing local Codex tasks and live Claude Desktop Code sessions in the same project. Nested Antigravity callers, outbound CLI callers, App conversation creation, and automatic App reply forwarding are not implemented. Windows Desktop is the live verification platform; macOS ancestry has unit coverage and Linux outbound host verification fails closed. The existing Codex↔Claude bridge remains separate. Use `antigravity-mcp-bridge-install --all --remove` to remove only these registrations; delivery receipts are retained.
+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.
 
 ### Windows (PowerShell)
 
@@ -307,7 +329,7 @@ On Windows and macOS, `codex-native-relay-install` adds this to the relay's entr
 env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
 ```
 
-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. Restart Codex Desktop after active work finishes so it relaunches the relay.
+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.
 
 ### Linux / WSL (Bash)
 
@@ -455,6 +477,9 @@ Use the bridge tools already available in the actual clients. Configuration chec
 | Codex Desktop | `native_relay_status` |
 | Codex / Claude Desktop Code with Antigravity installed | `antigravity_bridge_status` |
 | Antigravity App | `agent_bridge_status` |
+| Any configured background relay client | `worker_status` |
+
+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.
 
 To check CLI registrations without sending work:
 
@@ -465,7 +490,7 @@ claude mcp list
 
 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.
 
-Send a short message and confirm its reply **in both directions**. Registration alone does not prove delivery.
+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.
 
 ## Use
 
@@ -520,10 +545,10 @@ Node.js 22.13+ is required. If a command is missing, open a new terminal and che
 If the package or registrations are missing, use the complete installation command:
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
-On npm 12, `1 package had install scripts blocked` means the setup hook did not run. The scoped `--allow-scripts` flag authorizes this package's hook; it does not enable every package's scripts globally. Add `--foreground-scripts` to see lifecycle progress. A local `npm install`/`npm ci`, `--ignore-scripts`, or `CODEX_BRIDGE_SKIP_SETUP=1` intentionally skips automatic setup.
+On npm 12, `1 package had install scripts blocked` means the setup hook did not run. The scoped `--allow-scripts` flag authorizes this package's hook; it does not enable every package's scripts globally. `--foreground-scripts` displays lifecycle progress. A local `npm install`/`npm ci`, `--ignore-scripts`, or `CODEX_BRIDGE_SKIP_SETUP=1` intentionally skips automatic setup.
 
 For an already-installed package, preview and apply setup explicitly:
 
@@ -624,7 +649,7 @@ codex-bridge-setup.cmd --check
 
 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.
 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.
-3. If the client cannot reload that connection, open a new Code session in the same saved project to verify the registration. Reopen the app only after active work is safe to stop. A window's **Reload** action may refresh its UI while retaining the old Code process and MCP failure state.
+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.
 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.
 
 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.
@@ -675,7 +700,7 @@ Closing an application window and quitting its native host have different effect
 
 **Symptoms:** `RELAY_UNAVAILABLE`, `connect ENOENT`, a missing native relay socket, or `thread ... already has an active writer`.
 
-Native Desktop handoffs require Codex Desktop to be installed, signed in and open on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. 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.
+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.
 
 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.
 

package/docs/new-macos-setup.md

@@ -1,35 +1,58 @@
 # New macOS setup
 
-Connect Claude Desktop's **Code tab** and Codex Desktop through local MCP
-processes and sockets. Both apps still authenticate with their providers and
-use hosted models; local bridge transport does not mean offline inference.
+Connect native Desktop conversations through local MCP processes and sockets,
+or use independent Claude, Codex and Antigravity CLI workers. Both routes use
+provider authentication and hosted models; local bridge transport does not mean
+offline inference.
 
 ## One-command local installation
 
 The [ChatGPT plugin setup](../README.md#chatgpt-plugin) uses a hosted Sites
-connector. For local Desktop use, install Node.js 22.13+ and sign in to the apps
-under the same macOS user. Save the intended local project in Codex Desktop and
-open it in Claude's Code tab, then run:
+connector. Install Node.js 22.13+ under the macOS account that will use the
+bridges. Native handoffs require signed-in apps and the same local project saved
+in Codex Desktop and Claude's Code tab. Independent background workers use
+separately authenticated provider CLIs and do not require open Desktop apps.
+Run:
 
 ```bash
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 The script allowance applies only to this package's setup hook. npm versions
 that block install scripts by default need it; a plain install is sufficient
-only when the hook is allowed. Append `--foreground-scripts` to see progress.
+only when the hook is allowed. `--foreground-scripts` displays setup progress.
 If npm reports `1 package had install scripts blocked`, rerun the command above
 or run `codex-bridge-setup` explicitly.
 
 Setup registers the local bridges, adds native pipe forwarding, and bootstraps
 the relay executor. It reuses an available Codex CLI or installs a pinned
 official package under `~/.config/GptClaudeBridge/tools` (or
-`XDG_CONFIG_HOME/GptClaudeBridge/tools`). No separate CLI install command is
-required. Run the install under the account that uses the apps, without `sudo`.
+`XDG_CONFIG_HOME/GptClaudeBridge/tools`). No separate Codex CLI install command
+is required. Run the install under the account that uses the apps, without `sudo`.
 The package remains installed if an app configuration step fails, preserving
 the setup command for repair. A successful npm exit does not verify that every
 component is configured.
 
+The command also installs an independent per-user LaunchAgent for separate
+Claude, Codex and Antigravity CLI workers and updates its managed settings on
+each release. It registers worker communication and adds only Antigravity's four
+relay tool grants, preserving existing denials, disabled choices and unrelated
+settings. Install Claude Code and `agy` separately when those workers are needed;
+CLI authentication is separate from Desktop sign-in.
+
+With authenticated CLIs and an authorized project, `send_to_worker` supports
+all six worker-to-worker directions independently of closed or frozen Desktop
+apps. The operating system and user service must be running; network/provider
+access, quota and tool permissions still apply. A frozen window cannot accept
+new user input or show results until it responds. Use `worker-relay` in a terminal
+or another responsive MCP client to submit authorized background work and read
+receipts. These workers do not resume native chats or launch Desktop windows.
+
+Use `worker-relay status` to inspect service and CLI readiness separately, and
+`read_worker_delivery` for durable results. Authorize a selected project with
+`bridge-projects allow-project <absolute-project-path>` before sending work if
+it has no existing grant.
+
 | Client | Entry | Route |
 | --- | --- | --- |
 | Claude Code | `codex-bridge` | Native Codex Desktop handoffs |
@@ -38,22 +61,25 @@ component is configured.
 | Codex | `codex-native-relay` | Native Desktop transport |
 | Codex and Claude Code | `antigravity-bridge` | Antigravity App and bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound messaging and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
 The shared `codex-bridge-desktop` connector cannot establish a native Code
 sender identity. The native route uses the actual Code session and the same
 saved local Codex project. Setup does not pair the hosted ChatGPT connector.
 
-The relay needs the trusted app-bundled Node runtime selected by setup; do not
-substitute an arbitrary Homebrew/nvm Node. Pipe forwarding saves only the
-`CODEX_APP_TOOLS_PIPE_PATH` variable name, never its temporary value.
-
-Open or reconnect the affected MCP servers in the actual Desktop conversations,
-or restart the app after active work finishes. Setup does not restart or kill
-apps. Check `codex_bridge_status` inside Claude Code, `claude_bridge_status` and
-`native_relay_status` in Codex, and `agent_bridge_status` in Antigravity. Complete
-[installation verification](../README.md#verify-the-installation), including
-a message and reply in each direction. Saved configuration is not a completed
-live exchange or a claim of verification on another Mac.
+The native Codex relay needs the trusted app-bundled Node runtime selected by
+setup; do not substitute an arbitrary Homebrew/nvm Node. Pipe forwarding saves
+only the `CODEX_APP_TOOLS_PIPE_PATH` variable name, never its temporary value.
+
+Managed MCP supervisors adopt compatible updates when idle. An old direct MCP
+process remains stale until its host reconnects normally; setup does not open
+or create chats, restart apps or interrupt active work to load a relay. When the
+tools are available, check `codex_bridge_status` inside Claude Code,
+`claude_bridge_status` and `native_relay_status` in Codex, and
+`agent_bridge_status` in Antigravity. Follow
+[installation verification](../README.md#verify-the-installation) for each
+selected native or background route. Saved configuration is not a completed live
+exchange or a claim of verification on another Mac.
 
 ## Checks, recovery, and manual alternatives
 

package/docs/new-windows-setup.md

@@ -1,16 +1,17 @@
 # Windows setup and initial permissions
 
-Install Node.js 22.13+ and sign in to the apps you intend to use. For native
-handoffs, save the local project in Codex Desktop and open the same directory
-in Claude Desktop's **Code tab**. Run one PowerShell command:
+Install Node.js 22.13+. Native handoffs use signed-in Desktop apps and the same
+local project saved in Codex Desktop and Claude Desktop's **Code tab**.
+Independent background work uses separately authenticated provider CLIs and
+does not require the Desktop apps to be open. Run one PowerShell command:
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 The `--allow-scripts` value permits only this package's setup hook. npm versions
 that block install scripts by default need it; a plain install runs setup only
-when scripts are allowed. Add `--foreground-scripts` to see setup progress. If
+when scripts are allowed. `--foreground-scripts` displays setup progress. If
 npm reports `1 package had install scripts blocked`, run the recommended command
 again or run `codex-bridge-setup.cmd` explicitly.
 
@@ -22,6 +23,27 @@ executor. A failed component is reported as incomplete rather than ready. The
 package stays installed when an app configuration step fails, so the setup
 command remains available for repair. npm success alone does not verify setup.
 
+The same command installs the independent worker relay as a hidden per-user
+scheduled task and applies its managed settings on every update. It registers
+worker communication and adds only the four Antigravity relay tool grants;
+existing disabled settings, permission denials and unrelated settings remain.
+Install Claude Code and `agy` separately when those workers are needed; setup
+supplies a missing Codex CLI. CLI authentication is separate from Desktop sign-in.
+
+Once the selected CLIs are authenticated and the project is authorized,
+`send_to_worker` supports all six directions between Claude, Codex and
+Antigravity workers, even while Desktop apps are closed or frozen. The operating
+system and user service must be running; network/provider access, quota and tool
+permissions still apply. A frozen window cannot accept new user input or show
+results until it responds. Use `worker-relay.cmd` in a terminal or another
+responsive MCP client to submit authorized work and read receipts. The relay
+does not open apps or resume native chats.
+
+Use `worker-relay.cmd status` to inspect service and CLI readiness separately,
+and `read_worker_delivery` for durable results and diagnostic reports. Authorize
+a selected project with `bridge-projects.cmd allow-project <absolute-project-path>`
+before sending work if it has no existing grant.
+
 ## Installed entries
 
 | Client | Entry | Purpose |
@@ -32,16 +54,19 @@ command remains available for repair. npm success alone does not verify setup.
 | Claude Desktop shared connectors | `codex-bridge-desktop` | Connect ordinary chat to local Codex app-server sessions |
 | Codex and Claude Code | `antigravity-bridge` | Send to Antigravity App or bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound agent messages and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
 The shared `codex-bridge-desktop` connector does not establish a native Code
 sender identity. Use the actual Code session for native Codex Desktop work.
 Existing project restrictions, permission modes, and custom settings are
 preserved. Setup does not sign in, grant workspace trust, or close applications.
 
-After active work finishes, open or reconnect the affected apps so they load
-the entries. A conversation refresh may leave the previous MCP process loaded.
-Check `codex_bridge_status` inside the sending Claude Code task,
-`claude_bridge_status` and `native_relay_status` in Codex, and
+Managed MCP supervisors adopt compatible updates when idle. An old direct MCP
+process remains stale until its host reconnects normally; setup does not open
+or create a chat to load it. A conversation refresh may leave the previous
+process loaded. When the tools are available, check `codex_bridge_status` inside
+the sending Claude Code task, `claude_bridge_status` and `native_relay_status`
+in Codex, and
 `agent_bridge_status` in Antigravity. Configuration verification is separate
 from a completed live exchange.
 

package/docs/project-onboarding.md

@@ -1,26 +1,33 @@
 # Project onboarding and shared authorization
 
-The recommended global installation registers the bridges automatically:
+The recommended global installation registers the bridges and configures the
+independent worker relay automatically:
 
 ```sh
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 In Windows PowerShell use `npm.cmd`. The script allowance authorizes only this
 package's setup hook; npm versions that block install scripts by default need
-it. A plain install runs setup only when the hook is allowed. Append
-`--foreground-scripts` to see progress. If npm prints
+it. A plain install runs setup only when the hook is allowed.
+`--foreground-scripts` displays progress. If npm prints
 `1 package had install scripts blocked`, rerun the recommended command or run
 `codex-bridge-setup` explicitly. The setup creates
 `codex-bridge` for Claude Code and the separate `codex-bridge-desktop` shared
 Claude connector, configures Codex and Antigravity, and initializes the native
-relay on Windows/macOS. See [installation](../README.md#installation).
+relay on Windows/macOS. It also installs the per-user background service and
+worker communication settings, including Antigravity's four scoped relay tool
+grants. See [installation](../README.md#installation).
 
 Setup preserves existing scope and permission choices. Registration does not
 grant workspace trust, authorize cross-project work, or establish a live
 connection. The shared Desktop connector uses local app-server sessions;
 native Codex Desktop handoffs require a verified Claude Code sender in the
-same saved project.
+same saved project. Independent CLI workers require their own provider
+authentication and project authorization; they can communicate while Desktop
+apps are closed or frozen. A frozen UI still cannot accept new user input or
+display results. Use a terminal or another responsive client, subject to the
+[background worker prerequisites](../README.md#independent-background-workers).
 
 `codex-bridge-setup --check` inspects all saved registrations. Use
 `codex-bridge-setup --dry-run` to preview or rerun `codex-bridge-setup` to apply
@@ -31,15 +38,21 @@ If app configuration is incomplete, npm retains the package for repair; its
 success exit alone does not verify setup. Explicit setup and `--check` return
 a nonzero status until the saved configuration passes verification.
 
-## Optional shared project policy
+## Shared project policy
 
-Both bridge directions can read the same optional policy file via
+Native Codex/Claude handoffs can read the same optional policy file via
 `CODEX_BRIDGE_PROJECT_POLICY`. `bridge-projects` defaults to
 `~/.config/GptClaudeBridge/projects.json`. A shared home-directory path avoids
 different AppData views in packaged Windows applications. The policy stores
 canonical directory identities; do not copy it to a new machine as proof of
 authorization there.
 
+Independent background dispatch always requires a matching explicit project
+or parent grant from the shared
+policy; setup preserves grants and revocations rather than authorizing a new
+project. Use `bridge-projects allow-project <absolute-project-path>` for a
+selected project (`bridge-projects.cmd` on Windows), or the source commands below.
+
 ```sh
 node scripts/bridge-projects.mjs allow-project /absolute/projects/example
 node scripts/bridge-projects.mjs allow-parent /absolute/projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.25.3",
+  "version": "1.26.1",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",
@@ -30,6 +30,7 @@
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "codex-bridge-code-install": "scripts/install-claude-code.mjs",
     "codex-bridge-setup": "scripts/setup.mjs",
+    "worker-relay": "scripts/worker-relay.mjs",
     "bridge-projects": "scripts/bridge-projects.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
     "codex-native-relay": "src/native-relay-launcher.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.25.3",
+  "version": "1.26.1",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/background-relay-hidden.vbs

@@ -0,0 +1,11 @@
+Option Explicit
+If WScript.Arguments.Count <> 3 Then WScript.Quit 2
+Dim relayShell, relayEnvironment, relayNode, relayService
+Set relayShell = CreateObject("WScript.Shell")
+Set relayEnvironment = relayShell.Environment("PROCESS")
+relayNode = WScript.Arguments(0)
+relayService = WScript.Arguments(1)
+If InStr(relayNode, Chr(34)) > 0 Or InStr(relayNode, "%") > 0 Then WScript.Quit 2
+If InStr(relayService, Chr(34)) > 0 Or InStr(relayService, "%") > 0 Then WScript.Quit 2
+relayEnvironment("AGENT_RELAY_DIRECTORY") = WScript.Arguments(2)
+WScript.Quit relayShell.Run(Chr(34) & relayNode & Chr(34) & " " & Chr(34) & relayService & Chr(34), 0, True)