@minhspark/codex-mcp-bridge 1.24.0 → 1.25.0

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,7 +1,7 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.24.0",
-  "description": "MCP bridges for Claude, Codex, and Antigravity Desktop and CLI conversations.",
+  "version": "1.25.0",
+  "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",
     "codex",
@@ -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.0",
+  "version": "1.25.0",
   "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;

package/scripts/install-claude-code.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { randomUUID } from "node:crypto";
-import { claudeDesktopConfigPath } from "../src/platform.mjs";
-import { checkCodeRegistration, planCodeRegistration } from "../src/claude-code-registration.mjs";
+import { fileURLToPath } from "node:url";
+import { claudeDesktopConfigPath, homeDir } from "../src/platform.mjs";
+import { checkCodeRegistration, planCodeRegistration, planInitialCodeRegistration } from "../src/claude-code-registration.mjs";
 import { readProjectPolicy, readRegularConfigFile, backupRegularConfigFile } from "../src/project-policy.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
 const args = process.argv.slice(2);
 const option = (key, fallback) => { const index = args.indexOf(key); return index < 0 ? fallback : args[index + 1]; };
-const codeFile = option("--code-config", path.join(os.homedir(), ".claude.json"));
+const codeFile = option("--code-config", path.join(process.env.CLAUDE_CONFIG_DIR || homeDir(), ".claude.json"));
 const desktopFile = option("--desktop-config", claudeDesktopConfigPath());
 const policyFile = option("--policy", process.env.CODEX_BRIDGE_PROJECT_POLICY);
 const maxConfigBytes = 8 * 1024 * 1024;
@@ -21,7 +22,58 @@ try {
   const files = [codeFile, desktopFile];
   const originals = files.map(read);
   const [code, desktop] = originals.map((raw) => raw === null ? {} : JSON.parse(raw.replace(/^\uFEFF/, "")));
-  if (args.includes("--check")) {
+  const apply = (plan) => {
+    const contents = [plan.code, plan.desktop].map((value) => JSON.stringify(value, null, 2) + "\n");
+    const suffix = randomUUID();
+    const written = [];
+    try {
+      for (let index = 0; index < files.length; index++) {
+        const file = files[index];
+        const now = read(file);
+        if (now !== originals[index]) throw new Error(`Configuration changed concurrently: ${file}`);
+        if (now === null && index === 1 && !Object.keys(plan.desktop.mcpServers ?? {}).length) continue;
+        if (now !== null && JSON.stringify(JSON.parse(now.replace(/^\uFEFF/, ""))) === JSON.stringify([plan.code, plan.desktop][index])) continue;
+        if (now !== null) backupRegularConfigFile(file, `${file}.backup-${suffix}`, now, maxConfigBytes);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const temporary = `${file}.pending-${suffix}`;
+        try {
+          fs.writeFileSync(temporary, contents[index], { flag: "wx", mode: 0o600 });
+          if (read(file) !== now) throw new Error(`Configuration changed concurrently: ${file}`);
+          fs.renameSync(temporary, file);
+        } finally { fs.rmSync(temporary, { force: true }); }
+        written.push(index);
+        if (read(file) !== contents[index]) throw new Error(`Configuration readback failed: ${file}`);
+      }
+    } catch (error) {
+      const remaining = [];
+      for (const index of written.reverse()) {
+        const file = files[index];
+        const temporary = `${file}.rollback-${suffix}`;
+        try {
+          if (read(file) !== contents[index]) { remaining.push(file); continue; }
+          if (originals[index] === null) fs.unlinkSync(file);
+          else {
+            fs.writeFileSync(temporary, originals[index], { flag: "wx", mode: 0o600 });
+            if (read(file) !== contents[index]) { remaining.push(file); continue; }
+            fs.renameSync(temporary, file);
+          }
+        } catch { remaining.push(file); }
+        finally { fs.rmSync(temporary, { force: true }); }
+      }
+      if (remaining.length) error.message += `; rollback requires review: ${remaining.join(", ")}`;
+      throw error;
+    }
+    return written.length;
+  };
+  if (args.includes("--install")) {
+    if (args.includes("--check") || args.includes("--apply")) throw new Error("Use --install separately from --check or --apply");
+    const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+    const plan = planInitialCodeRegistration({ code, desktop, root, node: stableNodeBin(), environment: process.env });
+    const dryRun = args.includes("--dry-run");
+    const writtenFiles = dryRun ? 0 : apply(plan);
+    console.log(JSON.stringify({ action: dryRun ? "plan" : "install", configured: !dryRun, liveVerified: false,
+      changes: plan.changes, notices: plan.notices, writtenFiles, restartRequired: writtenFiles > 0 }, null, 2));
+  } else if (args.includes("--check")) {
     const result = checkCodeRegistration({ code, desktop });
     if (result.policyFile) { try { readProjectPolicy(result.policyFile); } catch (error) { result.issues.push(error.message); result.ready = false; } }
     console.log(JSON.stringify(result, null, 2));
@@ -33,44 +85,7 @@ try {
     console.log(JSON.stringify({ action: args.includes("--apply") ? "apply" : "plan", changes: plan.changes, policyFile }, null, 2));
     if (args.includes("--apply")) {
       if (!args.includes("--clients-stopped")) throw new Error("Exit Claude and the configuration manager first, then pass --clients-stopped to avoid their overwriting the migration");
-      const contents = [plan.code, plan.desktop].map((value) => JSON.stringify(value, null, 2) + "\n");
-      const suffix = randomUUID();
-      const written = [];
-      try {
-        for (let index = 0; index < files.length; index++) {
-          const file = files[index];
-          const now = read(file);
-          if (now !== originals[index]) throw new Error(`Configuration changed concurrently: ${file}`);
-          if (now === null && index === 1 && !Object.keys(plan.desktop.mcpServers ?? {}).length) continue;
-          if (now !== null) backupRegularConfigFile(file, `${file}.backup-${suffix}`, now, maxConfigBytes);
-          fs.mkdirSync(path.dirname(file), { recursive: true });
-          const temporary = `${file}.pending-${suffix}`;
-          try {
-            fs.writeFileSync(temporary, contents[index], { flag: "wx", mode: 0o600 });
-            if (read(file) !== now) throw new Error(`Configuration changed concurrently: ${file}`);
-            fs.renameSync(temporary, file);
-          } finally { fs.rmSync(temporary, { force: true }); }
-          written.push(index);
-        }
-      } catch (error) {
-        const remaining = [];
-        for (const index of written.reverse()) {
-          const file = files[index];
-          const temporary = `${file}.rollback-${suffix}`;
-          try {
-            if (read(file) !== contents[index]) { remaining.push(file); continue; }
-            if (originals[index] === null) fs.unlinkSync(file);
-            else {
-              fs.writeFileSync(temporary, originals[index], { flag: "wx", mode: 0o600 });
-              if (read(file) !== contents[index]) { remaining.push(file); continue; }
-              fs.renameSync(temporary, file);
-            }
-          } catch { remaining.push(file); }
-          finally { fs.rmSync(temporary, { force: true }); }
-        }
-        if (remaining.length) error.message += `; rollback requires review: ${remaining.join(", ")}`;
-        throw error;
-      }
+      apply(plan);
       console.log("Reopen the original Code task and call codex_bridge_status with the intended project cwd. Update the configuration manager's matching entry to the same policy file. No new per-project MCP entry is needed.");
     }
   }