@minhspark/codex-mcp-bridge 1.22.6 → 1.22.7

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,28 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.7] - 2026-10-20
+
+### Added
+
+- Install with Homebrew: `brew install buidangminh23/tap/codex-mcp-bridge`. The formula in [buidangminh23/homebrew-tap](https://github.com/buidangminh23/homebrew-tap) follows each npm release.
+
+### Fixed
+
+- Record Homebrew's stable `opt` paths instead of a versioned Cellar keg when the Claude Desktop, Codex and native relay installers and `bridge-projects register-manager` write a client configuration, for both the bridge and Homebrew's Node.js. A keg path broke every registration as soon as `brew upgrade` removed the old keg. Paths outside a Homebrew keg are written exactly as before.
+- Start the supervisor when its path reaches the installation through a symbolic link, such as Homebrew's `opt` alias. The direct-execution check compared the unresolved command-line path with the resolved module path, so the process exited at once without serving MCP.
+- Follow a Homebrew upgrade in a running supervisor: it watches the `opt` alias, reloads the new keg like any other installed update, and forks workers with the stable Node.js path, instead of reporting "Installation is not ready" after the old keg is removed.
+
+### Verification
+
+- 9 new regression tests: Cellar to `opt` mapping, a custom `HOMEBREW_PREFIX`, the main-module check through a symlink and a respelled path, a running supervisor following a bridge keg switch, and one following a Node.js keg replacement. The supervisor tests fail on v1.22.6 and pass here.
+- End to end on macOS with a local tap: two packed versions installed with brew, the three installers run against an isolated home, and every recorded path was `opt/codex-mcp-bridge` and `opt/node` (the relay keeps Codex Desktop's Node). A bridge launched from the recorded Claude Desktop entry kept its supervisor through `brew upgrade` and `brew cleanup` and reloaded the new keg; fresh launches from the recorded paths answered `initialize`.
+- An independent adversarial review confirmed two defects in the first draft, a main-module regression for respelled paths and a worker Node path resolved too late, and both were fixed before merge.
+
+### Limitations
+
+- Registrations written from a Homebrew keg by an earlier version still name that keg; run the installers once after upgrading. `codex-native-relay-install` still refuses to rewrite an entry that has `env_vars`, so edit that entry's path by hand.
+
 ## [1.22.6] - 2026-10-20
 
 ### Fixed

package/README.md

@@ -27,6 +27,14 @@ npm install -g @minhspark/codex-mcp-bridge@latest
 
 Requires **Node.js 22+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
 
+On macOS or Linux you can install with [Homebrew](https://github.com/buidangminh23/homebrew-tap) instead, which brings its own Node.js:
+
+```bash
+brew install buidangminh23/tap/codex-mcp-bridge
+```
+
+Update with `brew upgrade codex-mcp-bridge`. The installers record Homebrew's stable `opt` paths, so registrations keep working after an upgrade and running bridges reload the new version. Keep one install channel: whichever of npm or Homebrew comes first on `PATH` provides the commands.
+
 [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [ChatGPT plugin](#chatgpt-plugin)
 
 ### Windows (PowerShell)
@@ -93,6 +101,15 @@ claude mcp add --scope user codex-bridge \
   -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
 ```
 
+For a Homebrew install, use the stable paths instead of `npm root -g` and `command -v node`:
+
+```bash
+bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
+node_bin="$(brew --prefix)/opt/node/bin/node"
+```
+
+and end the command with `-- "$node_bin" "$bridge_root/src/mcp-supervisor.mjs" index.mjs`.
+
 </details>
 
 Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
@@ -178,7 +195,7 @@ Dispatch expires after two minutes; operation history remains stored. Disconnect
 
 ## Troubleshooting
 
-- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory on PATH.
+- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory (or Homebrew's `bin`) on PATH.
 - **PowerShell blocks scripts:** use `npm.cmd`, installer `.cmd` launchers, and `codex.exe`.
 - **No sessions or wrong project:** open the intended Claude **Code** session and use the exact project directory saved in Codex Desktop.
 - **Relay unavailable:** check [pipe forwarding](#native-relay-pipe-forwarding), reconnect, and run `native_relay_status` in the task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.6",
+  "version": "1.22.7",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",

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.22.6",
+  "version": "1.22.7",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-claude-desktop.mjs

@@ -9,10 +9,11 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
 const reset = process.argv.includes("--reset");
 const forceDesktopTasks = process.argv.includes("--desktop-tasks");
@@ -29,7 +30,7 @@ if (fullAccess) enableCodexFullAccess();
  */
 const defaultRoots = "*";
 
-const nodeBin = process.env.NODE_EXE ?? process.execPath;
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 
 if (!fs.existsSync(nodeBin)) throw new Error(`node executable not found: ${nodeBin}`);

package/scripts/install-codex-mcp.mjs

@@ -10,10 +10,12 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 const serverName = process.env.CLAUDE_BRIDGE_NAME ?? "claude-bridge";
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
@@ -39,13 +41,13 @@ const servers = JSON.parse(run(["mcp", "list", "--json"]));
 if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
 const existing = servers.some((server) => server.name === serverName)
   ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
-const registration = codexMcpRegistration({ name: serverName, existing, node: process.execPath, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
+const registration = codexMcpRegistration({ name: serverName, existing, node: nodeBin, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
 run(registration.args);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`registered MCP server "${serverName}" with Codex:`);
-console.log(`command: ${process.execPath} ${entry} ${entryArgs.join(" ")}`);
+console.log(`command: ${nodeBin} ${entry} ${entryArgs.join(" ")}`);
 console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
 console.log("\nReconnect claude-bridge once in the existing Codex Desktop task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle. Do not create a replacement task.");
 console.log("Verify claude_bridge_status from that task: autoReload must be enabled, runtime state must be current, and the session policy must match this installation. A separate diagnostic process does not verify the app's loaded MCP process.");

package/scripts/install-native-relay.mjs

@@ -20,11 +20,12 @@ import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = "1.22.7";
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.7";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.7";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/install-paths.mjs

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KEG_PATH = /^(\/.*?)\/Cellar\/([^/]+)\/[^/]+(\/.*)?$/;
+
+function resolved(target) {
+  try { return fs.realpathSync.native(target); } catch { return null; }
+}
+
+/**
+ * Homebrew installs every version of a formula into its own Cellar keg and
+ * deletes the old keg on upgrade, while <prefix>/opt/<formula> is retargeted to
+ * the current one. A path that outlives this process - written into a client
+ * configuration, or watched for an upgrade - therefore has to name the opt
+ * alias. A keg path is rewritten only when the alias resolves to the same file
+ * right now; every other path is returned unchanged.
+ */
+export function stableInstallPath(target, env = process.env) {
+  if (process.platform === "win32" || typeof target !== "string") return target;
+  const match = KEG_PATH.exec(target);
+  if (!match) return target;
+  const real = resolved(target);
+  if (!real) return target;
+  const [, base, formula, rest = ""] = match;
+  const prefixes = [...new Set([env.HOMEBREW_PREFIX, base].filter((prefix) => prefix && path.isAbsolute(prefix)))];
+  for (const prefix of prefixes) {
+    const alias = path.join(prefix, "opt", formula) + rest;
+    if (resolved(alias) === real) return alias;
+  }
+  return target;
+}
+
+/** The node binary to record for later launches. */
+export function stableNodeBin(env = process.env) {
+  return stableInstallPath(process.execPath, env);
+}
+
+/**
+ * True when `entry` names the running main module, however it was reached.
+ * Node resolves the main module with the JavaScript realpath, which follows
+ * symlinks but keeps the spelling of the path as typed (case, 8.3 names,
+ * substituted drives), so that is the form compared first.
+ */
+export function isMainModule(entry, moduleUrl) {
+  if (!entry) return false;
+  const file = path.resolve(entry);
+  const module = fileURLToPath(moduleUrl);
+  let typed;
+  try { typed = fs.realpathSync(file); } catch { typed = file; }
+  if (typed === module) return true;
+  const canonical = resolved(file);
+  return canonical !== null && canonical === resolved(module);
+}

package/src/mcp-supervisor.mjs

@@ -5,7 +5,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createReleaseSnapshot, sourceRevision } from "./release-snapshot.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
+import { isMainModule, stableInstallPath } from "./install-paths.mjs";
 
+const WORKER_NODE = stableInstallPath(process.execPath);
 const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUE = 256;
@@ -40,7 +42,7 @@ class Worker {
     this.retiring = false;
     this.closed = false;
     this.process = fork(path.join(release.directory, "src", entry), [], {
-      execPath: process.execPath, execArgv: [], cwd: process.cwd(), windowsHide: true,
+      execPath: WORKER_NODE, execArgv: [], cwd: process.cwd(), windowsHide: true,
       env: { ...env, CODEX_BRIDGE_WORKER: "1", CODEX_BRIDGE_STAGED: "1" },
       stdio: ["pipe", "pipe", "pipe", "ipc"], serialization: "json",
     });
@@ -133,14 +135,16 @@ class Worker {
 
 export async function runSupervisor(entry, options = {}) {
   if (!ENTRIES.has(entry)) throw new Error("Expected index.mjs, claude-bridge.mjs, or native-relay-companion.mjs");
-  const root = fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const installRoot = stableInstallPath(fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")));
+  const currentRoot = () => fs.realpathSync.native(installRoot);
+  const root = currentRoot();
   if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version}\n`);
     return;
   }
   const log = (message) => process.stderr.write(`[bridge-supervisor] ${message}\n`);
   const output = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
-  const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: root };
+  const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: installRoot };
   const routingConfiguration = () => entry === "native-relay-companion.mjs" ? null : desktopTasksConfigured(env);
   if (entry === "native-relay-companion.mjs" && !env.CODEX_APP_TOOLS_PIPE_PATH) {
     const { resolveNativeToolsPipePath } = await import("./native-relay.mjs");
@@ -226,9 +230,10 @@ export async function runSupervisor(entry, options = {}) {
   };
   const check = async () => {
     if (switching || !ready || stopping || failure) return;
+    let source;
     let revision;
     let routing;
-    try { revision = sourceRevision(root); routing = routingConfiguration(); }
+    try { source = currentRoot(); revision = sourceRevision(source); routing = routingConfiguration(); }
     catch (error) { reason = `Installation is not ready: ${error.message}`; return; }
     if (observed !== revision || observedRouting !== routing) { observed = revision; observedRouting = routing; observedAt = Date.now(); retryAt = 0; }
     if (revision === active.release.revision && routing === active.routingConfiguration) { reason = null; return; }
@@ -241,7 +246,7 @@ export async function runSupervisor(entry, options = {}) {
     try {
       const state = await previous.control("inspect");
       if (!state.reloadable) { reason = state.reason ?? "Pending deliveries prevent a safe reload"; return; }
-      const release = createReleaseSnapshot(root, { expectedRevision: revision });
+      const release = createReleaseSnapshot(source, { expectedRevision: revision });
       candidate = spawn(release, routing);
       const initialized = await candidate.rpc("initialize", initializeParams);
       if (initialized.protocolVersion !== initializeResult.protocolVersion || JSON.stringify(initialized.capabilities) !== JSON.stringify(initializeResult.capabilities)) {
@@ -251,7 +256,7 @@ export async function runSupervisor(entry, options = {}) {
       const catalog = await candidate.rpc("tools/list", {});
       if (!Array.isArray(catalog.tools) || !catalog.tools.length || catalog.nextCursor) throw new Error("The candidate tool catalog is incomplete");
       const oldCatalog = await previous.rpc("tools/list", {});
-      if (sourceRevision(root) !== revision) throw new Error("The installation changed before activation");
+      if (sourceRevision(currentRoot()) !== revision) throw new Error("The installation changed before activation");
       if (routingConfiguration() !== routing) throw new Error("The routing configuration changed before activation");
       quiesced = true;
       const exported = await previous.control("quiesce");
@@ -339,6 +344,6 @@ export async function runSupervisor(entry, options = {}) {
   log(`supervising ${entry}; installed updates activate after pending work completes`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(process.argv[1], import.meta.url)) {
   await runSupervisor(process.argv[2]);
 }

package/src/native-relay-companion.mjs

@@ -38,7 +38,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.7";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/platform.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
+import { stableNodeBin } from "./install-paths.mjs";
+
 const execFileAsync = promisify(execFile);
 
 export const IS_MACOS = process.platform === "darwin";
@@ -230,7 +232,7 @@ export function resolveCodexDesktopNodeBin(
   ]) {
     if (candidate && isRunnable(candidate)) return { path: candidate, source };
   }
-  return { path: process.execPath, source: "process.execPath" };
+  return { path: stableNodeBin(env), source: "process.execPath" };
 }
 
 /**
@@ -393,7 +395,7 @@ export function spawnEnv(extra = {}) {
   const systemDirs = IS_WINDOWS
     ? []
     : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
-  const merged = [path.dirname(process.execPath), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
+  const merged = [path.dirname(stableNodeBin()), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
     .filter(Boolean)
     .filter((dir, index, all) => all.indexOf(dir) === index)
     .join(separator);

package/src/project-manager-registration.mjs

@@ -4,15 +4,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { readRegularConfigFile, backupRegularConfigFile } from "./project-policy.mjs";
+import { stableInstallPath, stableNodeBin } from "./install-paths.mjs";
 
 // Optional UI adapter discovery. Neither bridge startup nor policy evaluation reads
 // this file. Removing the card extension or this descriptor cannot stop messaging.
-export function registerProjectManager({ policyFile, env = process.env, executable = process.execPath } = {}) {
+export function registerProjectManager({ policyFile, env = process.env, executable = stableNodeBin(env) } = {}) {
   if (!path.isAbsolute(policyFile ?? "")) throw new Error("Manager policy path must be absolute");
   const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
   const file = path.join(home, ".config", "GptClaudeBridge", "management.json");
   const value = { version: 1, node: executable,
-    script: fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)),
+    script: stableInstallPath(fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)), env),
     policyFile, configFile: env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, ".claude.json") : path.join(home, ".claude.json") };
   if (!Object.values(value).filter(v => typeof v === "string").every(v => path.isAbsolute(v))) throw new Error("Manager paths must be absolute");
   fs.mkdirSync(path.dirname(file), { recursive: true });