@minhspark/codex-mcp-bridge 1.24.1 → 1.25.1

package/docs/new-macos-setup.md

@@ -4,47 +4,95 @@ 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.
 
-## Local installation: required steps
+## One-command local installation
 
 The [ChatGPT plugin setup](../README.md#chatgpt-plugin) uses a hosted Sites
-connector. For a local Desktop installation, use the following path instead:
-
-1. Install and sign in to Codex Desktop and Claude Desktop under the same macOS
-   user. Have Node.js 22+, npm, the Codex CLI, and the Claude Code CLI available.
-   Save the intended local project in Codex Desktop and open it in Claude's
-   Code tab.
-2. Follow [macOS installation](../README.md#macos-terminal) to install the bridge
-   and register the native relay and reverse bridge. Keep bootstrap enabled on
-   the first relay install. Do not use the ChatGPT plugin pairing instructions,
-   run `codex-sites-connector`, or configure a hosted endpoint.
-3. Follow [Claude Code registration](../README.md#register-claude-code) for the
-   forward bridge. Use the intended project directories for
-   `CODEX_BRIDGE_ALLOWED_ROOTS`, rather than the example's entire home directory;
-   macOS separates multiple roots with `:`. Preserve an existing entry's
-   custom settings.
-4. Check that the relay entry has
-   [native relay pipe forwarding](../README.md#native-relay-pipe-forwarding).
-   The installer adds `CODEX_APP_TOOLS_PIPE_PATH` by name, never its temporary
-   value. The relay needs the trusted app-bundled Node runtime selected by the
-   installer; do not substitute an arbitrary Homebrew/nvm Node.
-5. Reconnect the affected MCP servers in the actual Desktop Code conversations,
-   or restart the affected app after active work finishes. Complete
-   [installation verification](../README.md#verify-the-installation), including
-   a message and reply in each direction.
-
-There are three registrations: `codex-bridge` in Claude Code, and
-`claude-bridge` plus `codex-native-relay` in Codex Desktop. The relay is transport
-plumbing, not a third agent. Ordinary Claude chat has a separate MCP registry;
-adding a server there does not register it in the Code tab.
+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:
+
+```bash
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+```
+
+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.
+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`.
+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.
+
+| Client | Entry | Route |
+| --- | --- | --- |
+| Claude Code | `codex-bridge` | Native Codex Desktop handoffs |
+| Claude Desktop shared connectors | `codex-bridge-desktop` | Local Codex app-server sessions from ordinary chat |
+| Codex | `claude-bridge` | Claude Code messages and replies |
+| 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 |
+
+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.
+
+## Checks, recovery, and manual alternatives
+
+```bash
+codex-bridge-setup --check
+codex-bridge-setup --dry-run
+codex-bridge-setup
+```
+
+`--check` inspects registrations; `--dry-run` previews components and paths
+without downloads or writes; the plain command applies setup again. Add
+`--json` for structured output or `--no-download` to require an existing Codex
+CLI. `codex-mcp-bridge setup` runs the same setup. An incomplete result identifies
+the component to correct before rerunning. Explicit setup and `--check` return
+a nonzero exit status while configuration is incomplete.
+
+Local `npm install` and `npm ci` do not change app settings. Set
+`CODEX_BRIDGE_SKIP_SETUP=1` or use `--ignore-scripts` to skip setup during a
+global install. For Homebrew, run `codex-bridge-setup` after installing the
+formula. A pinned source checkout can use `node scripts/setup.mjs`.
+
+The [manual macOS commands](../README.md#macos-terminal) and
+[Claude Code registration commands](../README.md#register-claude-code) remain
+available for selective configuration. `codex-bridge-code-install --install`
+can create a missing user-level Code entry; its existing policy migration mode
+is described in [project onboarding](project-onboarding.md). Use intended
+project paths when setting explicit `CODEX_BRIDGE_ALLOWED_ROOTS`; macOS
+separates them with `:`.
 
 ## Restricted local configuration
 
-Local transport does not require Full Access. Keep the intended sandbox,
-approval reviewer, and project restrictions. Before running installers, check
-for `$CODEX_HOME/bridge-full-access.enabled` (normally
-`~/.codex/bridge-full-access.enabled`): a saved opt-in makes them enable Full
-Access even without `--full-access`. Resolve that existing opt-in deliberately
-before installing; `CODEX_BRIDGE_ENFORCE_FULL_ACCESS=0` does not disable it.
+Local transport does not require Full Access. Automatic setup preserves the
+intended sandbox, approval reviewer, project restrictions, and custom modes. It
+does not grant workspace trust or tool approval, sign in, or enable permission
+bypass. The older individual installers, when run manually without setup mode,
+can still honor `$CODEX_HOME/bridge-full-access.enabled` (normally
+`~/.codex/bridge-full-access.enabled`); review that saved preference before using
+those advanced commands. `CODEX_BRIDGE_ENFORCE_FULL_ACCESS=0` does not delete the
+saved preference.
 
 For a restricted Codex setup, these are top-level configuration settings,
 before any `[table]`:
@@ -57,7 +105,7 @@ sandbox_mode = "workspace-write"
 
 Verify the active Desktop task uses the intended restrictions; defaults alone
 are not evidence of its effective permissions. To suppress optional reporting,
-set `CODEX_BRIDGE_TELEMETRY=0` in all three MCP registrations' environments;
+set `CODEX_BRIDGE_TELEMETRY=0` in the bridge MCP registrations' environments;
 see [telemetry controls](../README.md#optional-active-install-statistics).
 
 For workspace trust, shared project grants, and optional messaging automation,

package/docs/new-windows-setup.md

@@ -1,70 +1,129 @@
-# New Windows setup and initial permissions
+# Windows setup and initial permissions
 
-This is a Windows local Desktop source-install guide, not evidence of testing
-on a second machine. Use a pinned source revision containing these scripts;
-published npm versions may not yet include this branch. The optional card
-extension is distributed separately. Keep the source in a stable directory.
+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/sign in to Codex Desktop and Claude Desktop; install Node 22+ and Git,
-and make the Codex CLI available. Record the source revision and optional MCPB
-version/hash. Do not copy login caches, old session identities, unfinished
-receipts or directory-identity grants from another machine.
+```powershell
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+```
+
+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
+npm reports `1 package had install scripts blocked`, run the recommended command
+again or run `codex-bridge-setup.cmd` explicitly.
 
-## Three messaging entries
+The global installation configures the bridges and verifies their saved
+registrations. It reuses an available native Codex CLI, or installs a pinned
+official package in the current user's `.config\GptClaudeBridge\tools`
+directory. It also configures native pipe forwarding and bootstraps the relay
+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.
+
+## Installed entries
 
 | Client | Entry | Purpose |
 | --- | --- | --- |
 | Codex | `claude-bridge` | Send to Claude and observe replies |
 | Codex | `codex-native-relay` | Deliver Claude requests through the Desktop host |
 | Claude Code, user scope | `codex-bridge` | Send to Codex and continue reply observation |
+| 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 |
+
+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.
 
-Begin with one dedicated test directory and explicitly grant it:
+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
+`agent_bridge_status` in Antigravity. Configuration verification is separate
+from a completed live exchange.
+
+## Checks and recovery
 
 ```powershell
-node scripts/bridge-projects.mjs allow-project 'C:\Projects\BridgeTest'
+codex-bridge-setup.cmd --check
+codex-bridge-setup.cmd --dry-run
+codex-bridge-setup.cmd
 ```
 
-Merge a user-level Claude Code entry, replacing placeholder paths with actual
-absolute paths and preserving unrelated settings:
-
-```json
-{
-  "mcpServers": {
-    "codex-bridge": {
-      "command": "C:/Tools/nodejs/node.exe",
-      "args": ["C:/Tools/GptClaudeBridge/src/mcp-supervisor.mjs", "index.mjs"],
-      "env": {
-        "CODEX_BIN": "C:/Tools/Codex/codex.exe",
-        "CODEX_BRIDGE_DESKTOP_TASKS": "1",
-        "CODEX_BRIDGE_AUTOSTART": "0",
-        "CODEX_BRIDGE_PROJECT_POLICY": "C:/Users/<user>/.config/GptClaudeBridge/projects.json",
-        "CODEX_BRIDGE_ALLOWED_ROOTS": "C:/Projects/BridgeTest",
-        "CODEX_BRIDGE_THREAD_POLICY": "roots",
-        "CODEX_BRIDGE_APPROVAL_POLICY": "on-request",
-        "CODEX_BRIDGE_SANDBOX": "workspace-write"
-      }
-    }
-  }
-}
+The first command inspects configuration; the second previews components and
+paths without writes or downloads; the third applies setup again. Add `--json`
+for structured output or `--no-download` to require an existing Codex CLI.
+Explicit setup and `--check` return a nonzero exit status if configuration is
+incomplete.
+`codex-mcp-bridge.cmd setup` is an equivalent setup entry point. If Claude Code
+has no bridge tools, inspect and reconnect `codex-bridge` using `/mcp` before
+attempting delivery.
+
+Local `npm install` and `npm ci` do not configure apps. To opt out during a
+global install, set `CODEX_BRIDGE_SKIP_SETUP=1` or use `--ignore-scripts`.
+The optional card extension, hosted ChatGPT pairing, and VS Code preview have
+separate installation steps.
+
+## If startup still fails
+
+Check the version reported by `codex_bridge_status` in the actual Claude Code
+session against the installed package:
+
+```powershell
+npm.cmd list -g @minhspark/codex-mcp-bridge --depth=0
 ```
 
-Then run `node scripts/install-claude-code.mjs --check`. That helper migrates or
-checks an existing supervised entry; it does not create a first entry from
-nothing. See [project onboarding](project-onboarding.md) for migration.
+Also inspect the session's MCP command and script path. A source checkout can
+keep an older version running even after npm updates the global package. If
+the tool is unavailable, the startup log and configured path identify which
+installation Claude tried to load. Rerun setup and reconnect the affected
+client after active work finishes before comparing another result.
+
+Setup prepares runtime snapshots in advance. However, a startup message such
+as `prepared ... (reused)` means only that the runtime directory already
+existed; missing or invalid integrity metadata can still require verification
+work. If a 30-second connection timeout persists after the intended global
+installation is loaded, collect the runtime version, startup log and exact
+timeout. Configuration repair and a reused directory do not prove that the
+reported startup delay has been resolved.
 
-Configure the same policy for Codex using the repository installers:
+Claude may label ordinary startup diagnostics as `Server stderr`, including
+`preparing`, `prepared`, and `ready` lines. Check the real connection status and
+error rather than treating that label alone as failure. Keep diagnostics off
+stdout: MCP uses stdout for protocol messages.
+
+## Optional source installation and project policy
+
+For a pinned source checkout in a stable directory, `node scripts/setup.mjs`
+runs the same setup. The individual installers remain available for deliberate
+manual configuration. For example, with an available Codex CLI and an explicitly
+selected test project:
 
 ```powershell
+node scripts/bridge-projects.mjs allow-project 'C:\Projects\BridgeTest'
+$env:CODEX_BIN = (Get-Command codex.exe).Source
+$env:CODEX_EXE = $env:CODEX_BIN
 $env:CODEX_BRIDGE_PROJECT_POLICY = Join-Path $env:USERPROFILE '.config\GptClaudeBridge\projects.json'
 $env:CODEX_BRIDGE_DESKTOP_TASKS = '1'
+$env:CODEX_BRIDGE_AUTOSTART = '0'
+node scripts/install-claude-code.mjs --install
 node scripts/install-native-relay.mjs
 node scripts/install-codex-mcp.mjs
 ```
 
-If discovery fails, set `CODEX_EXE` to the real CLI executable. Relay setup may
-create an initial relay task. Do not add a permission-bypass mode. If CC Switch
-manages the entries, save the same configuration there. Reload affected clients
-and inspect the tools inside the actual Code/dispatch conversations.
+`--install` creates a missing Code entry or updates a recognized one;
+`--install --dry-run` previews it. For an existing entry with a different scope,
+use the explicit policy migration in [project onboarding](project-onboarding.md).
+`--check` on that helper checks the optional shared policy arrangement; it is
+not the general setup check. Keep CC Switch or another configuration manager
+consistent with the saved entries so it does not restore an obsolete copy.
+
+Do not copy login caches, session identities, unfinished receipts or
+directory-identity grants from another machine. This guide is not evidence
+that a particular second machine or client build has passed live verification.
 
 ## Permissions are separate
 

package/docs/project-onboarding.md

@@ -1,5 +1,38 @@
 # Project onboarding and shared authorization
 
+The recommended global installation registers the bridges automatically:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+```
+
+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
+`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).
+
+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.
+
+`codex-bridge-setup --check` inspects all saved registrations. Use
+`codex-bridge-setup --dry-run` to preview or rerun `codex-bridge-setup` to apply
+setup after correcting an incomplete component. Add `.cmd` on Windows and
+`--json` for structured output. Local package installs do not run setup;
+`CODEX_BRIDGE_SKIP_SETUP=1` and npm `--ignore-scripts` opt out of global setup.
+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
+
 Both bridge directions 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
@@ -48,20 +81,42 @@ node scripts/bridge-projects.mjs prepare /absolute/projects/example
 
 Changes are backed up and verified. Concurrent changes abort; failed rollback
 returns `partial_needs_review` and remaining files. `configured` does not mean
-live communication passed. Setup does not approve tools, change session modes,
-create conversations or restart clients. Workspace trust follows Claude's
+live communication passed. Project preparation does not approve tools, change
+session modes, create conversations or restart clients. The package installer
+separately initializes an internal relay executor when needed. Workspace trust
+follows Claude's
 [documented project settings](https://code.claude.com/docs/en/permissions#project-allow-rules-and-workspace-trust).
 
 ## Correct Code registration
 
 Claude's user-level `codex-bridge` must run under the actual Code session. A
-generic shared Desktop process cannot establish that caller's ancestry. The
-Code migration helper previews changes by default; it is not a first-install
-wizard. With both clients stopped, `--apply --clients-stopped` backs up and
-migrates an existing supervised entry. `--check` diagnoses shared/duplicate
-entries and policy errors. Customized entries are left for review. Keep an
-external configuration manager, such as CC Switch, consistent with the selected
-entry so it does not restore an obsolete copy later.
+generic shared Desktop process cannot establish that caller's ancestry.
+Automatic setup creates or updates the supervised Code entry and safely
+renames a recognized shared entry to `codex-bridge-desktop`. Conflicting or
+unrecognized entries are reported without overwriting them; custom project
+overrides are preserved and reported.
+
+For selective installation, `codex-bridge-code-install --install` creates a
+missing Code entry or updates a recognized one. `--install --dry-run` previews
+the change. The complete `codex-bridge-setup` command also handles the other
+registrations and prerequisites. Neither path copies permissions or login
+credentials from another client.
+
+The helper's existing policy migration remains an explicit operation and
+previews changes by default. After initializing the desired policy and stopping
+Claude and any configuration manager, run:
+
+```sh
+codex-bridge-code-install --policy /absolute/path/projects.json
+codex-bridge-code-install --policy /absolute/path/projects.json --apply --clients-stopped
+codex-bridge-code-install --check
+```
+
+Migration backs up and updates an existing supervised entry. This helper's
+`--check` diagnoses the optional shared-policy arrangement, including shared or
+duplicate entries; use `codex-bridge-setup --check` for the general installation
+check. Keep CC Switch or another external configuration manager consistent
+with the selected entry so it does not restore an obsolete copy later.
 
 Reload the affected client after changing MCP registration. Merely refreshing
 the conversation did not reload the Code process in the measured Windows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.24.1",
+  "version": "1.25.1",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",
@@ -29,6 +29,7 @@
     "antigravity-mcp-bridge-install": "scripts/install-antigravity-bridge.mjs",
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "codex-bridge-code-install": "scripts/install-claude-code.mjs",
+    "codex-bridge-setup": "scripts/setup.mjs",
     "bridge-projects": "scripts/bridge-projects.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
     "codex-native-relay": "src/native-relay-launcher.mjs",
@@ -61,6 +62,8 @@
     "access": "public"
   },
   "scripts": {
+    "postinstall": "node scripts/setup.mjs --postinstall",
+    "setup": "node scripts/setup.mjs",
     "analytics": "node scripts/collect-repo-analytics.mjs",
     "analytics:publish": "node scripts/publish-repo-analytics.mjs",
     "start": "node src/codex-bridge-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.24.1",
+  "version": "1.25.1",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-antigravity-bridge.mjs

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { isMainModule, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
-import { resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import { homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 
 const NAME = "antigravity-bridge";
@@ -54,12 +53,24 @@ export function validateCodexExecutable(executable, { platform = process.platfor
   return resolved;
 }
 
-function ownEntry(entry, expected, label) {
+function ownEntry(entry, expected, label, retarget = false) {
   if (entry === undefined || entry === null) return;
   object(entry, label);
-  if (!Array.isArray(entry.args) || entry.args.length !== 1 || typeof entry.args[0] !== "string" || path.resolve(entry.args[0]) !== path.resolve(expected)) {
+  const script = entry.args?.[0];
+  if (!Array.isArray(entry.args) || entry.args.length !== 1 || typeof script !== "string") {
     throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
   }
+  if (path.resolve(script) === path.resolve(expected)) return;
+  const source = path.dirname(script);
+  if (!retarget || !path.isAbsolute(script) || script.includes("\0") || path.basename(script) !== path.basename(expected)
+    || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge") {
+    throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
+  }
+  const command = entry.command;
+  if (typeof command !== "string" || command.includes("\0") || !/^(?:node|node\.exe)$/i.test(path.basename(command))
+    || !path.isAbsolute(command) && command !== path.basename(command)) {
+    throw new Error(`${label} is already configured with a different launcher; it was not changed`);
+  }
 }
 
 function changed(original, value) {
@@ -68,28 +79,29 @@ function changed(original, value) {
   return { ...original, next: text };
 }
 
-export function planAntigravityInstallation({ home = os.homedir(), root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, codexExisting = null } = {}) {
-  if (!path.isAbsolute(home) || !path.isAbsolute(root) || !path.isAbsolute(node)) throw new Error("Installer paths must be absolute");
+export function planAntigravityInstallation({ home = homeDir(), codeConfigDir = process.env.CLAUDE_CONFIG_DIR || home, root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, setup = false, codexExisting = null } = {}) {
+  if (!path.isAbsolute(home) || !path.isAbsolute(codeConfigDir) || !path.isAbsolute(root) || !path.isAbsolute(node)) throw new Error("Installer paths must be absolute");
   if (!targets.length || targets.some((target) => !["codex", "claude", "desktop"].includes(target))) throw new Error("Unknown installation target");
   const entry = path.join(root, "src", "antigravity-bridge.mjs");
   const sidecarEntry = path.join(root, "src", "antigravity-sidecar.mjs");
   const outboundEntry = path.join(root, "src", "antigravity-outbound-bridge.mjs");
   const edits = [];
   const notices = [];
+  const retarget = setup && !remove;
   let codex = null;
   if (targets.includes("codex")) {
     if (codexExisting && codexExisting.transport?.type !== "stdio") throw new Error("The existing Antigravity MCP transport is not stdio");
-    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge");
+    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget);
     const existingCaller = codexExisting?.transport?.env?.ANTIGRAVITY_BRIDGE_CALLER;
     if (existingCaller !== undefined && existingCaller !== "codex") throw new Error("The existing Codex bridge has a conflicting caller identity");
     codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry, envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
   }
   if (targets.includes("claude")) {
-    const original = snapshot(path.join(home, ".claude.json"));
+    const original = snapshot(path.join(codeConfigDir, ".claude.json"));
     const value = structuredClone(original.value);
     if (value.mcpServers !== undefined) object(value.mcpServers, "Claude mcpServers");
     const existing = value.mcpServers?.[NAME];
-    ownEntry(existing, entry, "Claude Antigravity bridge");
+    ownEntry(existing, entry, "Claude Antigravity bridge", retarget);
     if (existing?.type !== undefined && existing.type !== "stdio") throw new Error("The existing Claude bridge transport is not stdio");
     if (existing?.env !== undefined) object(existing.env, "Claude bridge environment");
     if (existing?.env?.ANTIGRAVITY_BRIDGE_CALLER !== undefined && existing.env.ANTIGRAVITY_BRIDGE_CALLER !== "claude") throw new Error("The existing Claude bridge has a conflicting caller identity");
@@ -107,7 +119,7 @@ export function planAntigravityInstallation({ home = os.homedir(), root = path.r
     const mcp = structuredClone(originalMcp.value);
     if (mcp.mcpServers !== undefined) object(mcp.mcpServers, "Antigravity mcpServers");
     const outbound = mcp.mcpServers?.[OUTBOUND];
-    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge");
+    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget);
     if (outbound?.type !== undefined && outbound.type !== "stdio" || outbound?.url !== undefined || outbound?.serverUrl !== undefined || outbound?.httpUrl !== undefined) throw new Error("The existing Antigravity outbound bridge transport is not stdio");
     if (outbound?.env !== undefined) object(outbound.env, "Antigravity outbound bridge environment");
     if (Object.keys(outbound?.env ?? {}).some((name) => /^(?:CLAUDE|CODEX_|ANTIGRAVITY_BRIDGE_CALLER$)/i.test(name))) throw new Error("The existing Antigravity outbound bridge contains a foreign caller environment; review it before installation");
@@ -122,7 +134,7 @@ export function planAntigravityInstallation({ home = os.homedir(), root = path.r
     const mcpEdit = changed(originalMcp, mcp);
     if (mcpEdit) edits.push(mcpEdit);
     const originalSidecar = snapshot(path.join(configRoot, "sidecars", SIDECAR, "sidecar.json"));
-    if (originalSidecar.text !== null) ownEntry(originalSidecar.value, sidecarEntry, "Antigravity sidecar");
+    if (originalSidecar.text !== null) ownEntry(originalSidecar.value, sidecarEntry, "Antigravity sidecar", retarget);
     const originalConfig = snapshot(path.join(configRoot, "config.json"));
     const config = structuredClone(originalConfig.value);
     if (config.sidecars !== undefined) object(config.sidecars, "Antigravity sidecars");
@@ -131,10 +143,12 @@ export function planAntigravityInstallation({ home = os.homedir(), root = path.r
     let definition = null;
     if (remove) { if (config.sidecars) delete config.sidecars[SIDECAR]; }
     else {
-      definition = { ...originalSidecar.value, command: node, args: [sidecarEntry], restart_policy: originalSidecar.value.restart_policy ?? "on-failure", display_name: "Codex / Claude Antigravity Bridge" };
+      definition = { ...originalSidecar.value, command: node, args: [sidecarEntry], restart_policy: originalSidecar.value.restart_policy ?? "on-failure", display_name: setup ? originalSidecar.value.display_name ?? "Codex / Claude Antigravity Bridge" : "Codex / Claude Antigravity Bridge" };
       if (definition.builtin !== undefined) throw new Error("A builtin Antigravity sidecar cannot be replaced");
       config.sidecars ??= {};
-      config.sidecars[SIDECAR] = { ...config.sidecars[SIDECAR], enabled: true };
+      const enabled = setup ? config.sidecars[SIDECAR]?.enabled ?? true : true;
+      config.sidecars[SIDECAR] = { ...config.sidecars[SIDECAR], enabled };
+      if (enabled === false) notices.push("The existing Antigravity bridge sidecar is disabled; automatic setup preserved that choice.");
     }
     const sidecarEdit = changed(originalSidecar, definition);
     const configEdit = changed(originalConfig, config);
@@ -179,19 +193,19 @@ export function applyJsonEdits(edits) {
 }
 
 export function installerArguments(args) {
-  const allowed = new Set(["--codex", "--claude", "--desktop", "--all", "--remove", "--dry-run", "--help"]);
+  const allowed = new Set(["--codex", "--claude", "--desktop", "--all", "--remove", "--dry-run", "--setup", "--help"]);
   if (args.some((arg) => !allowed.has(arg))) throw new Error("Unknown option; use --help");
   const selected = ["codex", "claude", "desktop"].filter((target) => args.includes(`--${target}`));
-  return { targets: args.includes("--all") || !selected.length ? ["codex", "claude", "desktop"] : selected, remove: args.includes("--remove"), dryRun: args.includes("--dry-run"), help: args.includes("--help") };
+  return { targets: args.includes("--all") || !selected.length ? ["codex", "claude", "desktop"] : selected, remove: args.includes("--remove"), dryRun: args.includes("--dry-run"), setup: args.includes("--setup"), help: args.includes("--help") };
 }
 
 export function runAntigravityInstaller(args = process.argv.slice(2)) {
   const options = installerArguments(args);
   if (options.help) {
-    console.log("Usage: antigravity-mcp-bridge-install [--all|--codex|--claude|--desktop] [--remove] [--dry-run]");
+    console.log("Usage: antigravity-mcp-bridge-install [--all|--codex|--claude|--desktop] [--remove] [--dry-run] [--setup]");
     return;
   }
-  const home = os.homedir();
+  const home = homeDir();
   const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
   const node = stableNodeBin();
   let run;