codex-control-chrome-mcp 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-07-04
+
+### Fixed
+
+- `chrome_evaluate`, `chrome_navigate`, and `chrome_screenshot` now self-heal a stale debugger attachment instead of dead-ending on `Debugger is not attached`. Each tool already attaches before sending CDP commands, but the extension tracks attachments in memory: when Chrome tears an attachment down out-of-band (a competing debugger client, DevTools, or a renderer/process swap), that flag can go stale, so a fresh `attach` short-circuits and reports success without actually re-attaching and the next command fails with `Debugger is not attached`. The tab then stayed wedged — `attach` kept reporting `ok` while every command failed — and only a new tab recovered. These tools now retry once on that specific error by issuing a `detach` (which clears the stale flag; it may itself report "not attached", which is expected and ignored) followed by a real `attach`, so a previously wedged tab recovers automatically. The self-heal wrapper is covered by regression tests. This addresses recovery in the bridge only; the underlying churn comes from multiple debugger clients contending for the same tab, so reducing competing browser-control stacks still helps.
+
+### Changed
+
+- The native host launcher no longer runs `npx` on every connection. When installed to a stable location (e.g. `npm install -g codex-control-chrome-mcp`), `install-native-host` writes a launcher that execs Node directly against the installed CLI, so the Codex extension connects immediately instead of waiting for npx to resolve/download the package on each Native Messaging connect. A cold or evicted npx cache could take seconds and exceed the extension's connect timeout, which showed up as the bridge "not connecting". The launcher prefers the Node.js used at install time and falls back to `node` on `PATH`, so a Node upgrade (which moves the versioned Homebrew/nvm path) does not strand it.
+- Recommended setup is now a global install followed by `codex-control-chrome-mcp install-native-host`, with the MCP stdio client pointed at the installed `codex-control-chrome-mcp` binary. Running `npx … install-native-host` still works: because that copy lives in npm's garbage-collectable `_npx` cache, the installer detects it and keeps the previous npx launcher as a fallback (install globally and re-run for the fast path).
+
+### Fixed
+
+- `package-lock.json` recorded a stale `1.1.0` project version; it now tracks the package version.
+
 ## [1.2.1] - 2026-07-03
 
 ### Fixed

package/README.md

@@ -40,40 +40,42 @@ Commands accept `--browser <chrome\|edge\|all>`. Without the flag, `install-nati
 
 Install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome or Edge profile you want to automate.
 
-Install the native host (auto-detects the browsers present):
+Install the package globally, then register the native host (auto-detects the browsers present):
 
 ```bash
-npx -y codex-control-chrome-mcp@latest install-native-host
+npm install -g codex-control-chrome-mcp
+codex-control-chrome-mcp install-native-host
 ```
 
-To target one browser explicitly:
+A global install gives the native host a stable path, so its launcher execs Node directly against the installed CLI with no per-connection `npx` cost. To target one browser explicitly:
 
 ```bash
-npx -y codex-control-chrome-mcp@latest install-native-host --browser edge
+codex-control-chrome-mcp install-native-host --browser edge
 ```
 
-Configure your Agent to use the MCP stdio server:
+Configure your Agent to use the MCP stdio server through the installed binary:
 
 ```json
 {
   "type": "stdio",
-  "command": "npx",
-  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"],
+  "command": "codex-control-chrome-mcp",
+  "args": ["--stdio"],
   "startup_timeout_sec": 30
 }
 ```
 
-Check status:
+If your MCP client does not inherit a shell `PATH` that includes npm's global bin directory (common for GUI apps), use the absolute path from `npm prefix -g` — for example `/opt/homebrew/bin/codex-control-chrome-mcp` — as `command`.
+
+Check status and uninstall:
 
 ```bash
-npx -y codex-control-chrome-mcp@latest status
+codex-control-chrome-mcp status
+codex-control-chrome-mcp uninstall-native-host   # restores the previous Codex native host manifest
 ```
 
-Uninstall and restore the previous Codex native host manifest:
+### Without a global install
 
-```bash
-npx -y codex-control-chrome-mcp@latest uninstall-native-host
-```
+`npx -y codex-control-chrome-mcp@latest <command>` still works for every command. Be aware that `npx … install-native-host` writes a launcher that re-runs `npx` on every extension connection; a cold or evicted npx cache can add seconds and may exceed the extension's connect timeout (the bridge then looks stuck "not connecting"). The installer detects the npx temp copy and keeps that launcher as a fallback — install globally and re-run `install-native-host` for the fast, stable path.
 
 ## Agent Skill
 

package/docs/architecture.md

@@ -107,7 +107,7 @@ If the MCP stdio server is stopped but the native host proxy is still running, C
 ```text
 Other Agent
   -> MCP stdio
-  -> npx -y codex-control-chrome-mcp@latest --stdio
+  -> codex-control-chrome-mcp --stdio
   -> /tmp/codex-browser-use/codex-control-chrome-mcp-*.sock
   -> codex-control-chrome-mcp --native-host
   -> Chrome native messaging stdio
@@ -189,17 +189,17 @@ This project can shim those APIs and point `nativePipe.createConnection()` at it
 
 The initial implementation exposes direct MCP tools first. Vendoring `browser-client.mjs` should be a later phase after the native host bridge is stable.
 
-## NPX Runtime Model
+## Runtime And Launch Model
 
-The intended distribution model is npm plus NPX, not a single packaged binary.
+The package is distributed on npm and run as its installed CLI. A global install (`npm install -g codex-control-chrome-mcp`) gives both entrypoints — the `--stdio` MCP server and the `--native-host` bridge — a stable path.
 
-Agent-side MCP config should use:
+Agent-side MCP config should use the installed binary:
 
 ```json
 {
   "type": "stdio",
-  "command": "npx",
-  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"]
+  "command": "codex-control-chrome-mcp",
+  "args": ["--stdio"]
 }
 ```
 
@@ -209,10 +209,15 @@ Chrome Native Messaging manifests cannot store command arguments. Therefore `ins
 ~/.codex-control-chrome-mcp/native-host-launcher
 ```
 
-That launcher runs (the `--browser` flag tells the host which browser's proxy config to read):
+The launcher execs Node directly against the installed CLI (no `npx` in the hot path, so the extension connects without waiting on a package resolve/download) and injects the mode and browser. The `--browser` flag tells the host which browser's proxy config to read:
 
 ```sh
-npx -y codex-control-chrome-mcp@latest --native-host --browser chrome "$@"
+#!/usr/bin/env sh
+node_bin='/path/to/node'
+[ -x "$node_bin" ] || node_bin=node
+exec "$node_bin" '/path/to/codex-control-chrome-mcp/bin/codex-control-chrome-mcp.js' --native-host --browser chrome "$@"
 ```
 
-The native host manifest points to the launcher, not directly to `npx`.
+It prefers the Node.js used at install time and falls back to `node` on `PATH` so a Node upgrade does not strand it. The native host manifest points to the launcher, not to the CLI directly (a manifest cannot pass `--browser`).
+
+When the CLI is instead run through `npx` — its copy lives in npm's garbage-collectable `_npx` cache — `install-native-host` detects that and falls back to a launcher that runs `npx -y codex-control-chrome-mcp@latest --native-host …`. That is stable but pays npx's startup cost on every connect; a global install avoids it.

package/docs/install.md

@@ -33,8 +33,11 @@ Commands accept `--browser <chrome|edge|all>`. Without it, `install-native-host`
 
 First install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome or Edge profile you want to automate.
 
+Install the package globally, then register the native host:
+
 ```bash
-npx -y codex-control-chrome-mcp@latest install-native-host
+npm install -g codex-control-chrome-mcp
+codex-control-chrome-mcp install-native-host
 ```
 
 Without `--browser`, this installs for every supported browser whose profile directory exists. Pass `--browser <chrome|edge|all>` to target one explicitly.
@@ -46,12 +49,17 @@ This writes a stable per-browser launcher (Edge uses the `-edge` suffix):
 ~/.codex-control-chrome-mcp/native-host-launcher-edge
 ```
 
-The launcher invokes (the `--browser` flag tells the host which browser's config to read for proxy mode):
+Chrome/Edge Native Messaging manifests cannot carry arguments, so the manifest points at this launcher rather than the CLI directly. The launcher execs Node against the installed CLI — no `npx` in the hot path, so the extension connects immediately — and injects `--native-host --browser <name>` (the `--browser` flag tells the host which browser's config to read for proxy mode). It prefers the Node.js used at install time and falls back to `node` on `PATH`, so a Node upgrade does not strand it:
 
-```bash
-npx -y codex-control-chrome-mcp@latest --native-host --browser chrome "$@"
+```sh
+#!/usr/bin/env sh
+node_bin='/path/to/node'
+[ -x "$node_bin" ] || node_bin=node
+exec "$node_bin" '/usr/local/lib/node_modules/codex-control-chrome-mcp/bin/codex-control-chrome-mcp.js' --native-host --browser chrome "$@"
 ```
 
+If you instead run `npx … install-native-host`, the package resolves inside npm's garbage-collectable `_npx` cache, so the installer falls back to a launcher that runs `npx -y codex-control-chrome-mcp@latest --native-host …` on every connect. That works but pays npx's startup cost each time (a cold cache can exceed the extension's connect timeout); install globally and re-run for the direct launcher.
+
 For each selected browser the installer:
 
 1. Reads the existing `com.openai.codexextension.json` in that browser's directory.
@@ -91,17 +99,19 @@ Example manifest paths on Linux:
 
 ## MCP Client Config
 
-Use stdio mode from other Agent tools:
+With the package installed globally, point the client at the installed binary:
 
 ```json
 {
   "type": "stdio",
-  "command": "npx",
-  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"],
+  "command": "codex-control-chrome-mcp",
+  "args": ["--stdio"],
   "startup_timeout_sec": 30
 }
 ```
 
+If the client does not inherit a `PATH` that includes npm's global bin directory (common for GUI apps), use the absolute path from `npm prefix -g` (e.g. `/opt/homebrew/bin/codex-control-chrome-mcp`) as `command`. Without a global install, `"command": "npx"` with `"args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"]` also works.
+
 If the Agent supports skills, install or reference the bundled skill folder from this package or repository:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-control-chrome-mcp",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.",
   "license": "MIT",
   "type": "module",

package/src/installer.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   APP_STATE_DIR,
   CODEX_EXTENSION_ID,
@@ -26,15 +27,19 @@ export async function installNativeHost({
   proxy = true,
   browser = DEFAULT_BROWSER,
   paths = defaultInstallPaths(browser),
+  selfBinPath = resolveSelfBinPath(),
 } = {}) {
   const { manifestPath, appStateDir, configPath, installStatePath } = paths;
   const browserId = paths.browser ?? browser;
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
   await fs.mkdir(appStateDir, { recursive: true });
 
-  const hostPath = binPath
-    ? await createLocalLauncher(path.resolve(binPath), appStateDir, browserId)
-    : await createNpxLauncher(appStateDir, browserId);
+  const { hostPath, launchMode } = await createLauncher({
+    binPath,
+    selfBinPath,
+    appStateDir,
+    browser: browserId,
+  });
   const existing = await readJsonIfExists(manifestPath);
   const previousState = await readJsonIfExists(installStatePath);
   const previousBackup = previousState?.backupPath
@@ -68,7 +73,7 @@ export async function installNativeHost({
     manifestPath,
     hostPath,
     binPath: binPath ? path.resolve(binPath) : null,
-    launchMode: binPath ? "direct-bin" : "npx-launcher",
+    launchMode,
     backupPath,
     officialHostPath,
     proxy,
@@ -252,6 +257,39 @@ async function backupManifest(manifestPath) {
   return backupPath;
 }
 
+/**
+ * Choose how the Native Messaging host is launched:
+ *   - `--bin <path>`: a caller-supplied CLI entry (local dev) -> direct launcher.
+ *   - installed to a stable location (e.g. `npm i -g`): our own resolved entry
+ *     -> direct launcher, so every connect skips npx's resolve/download cost.
+ *   - run from npx's temp cache (`npx … install-native-host`): that copy can be
+ *     garbage-collected, so a launcher must not point at it -> npx launcher
+ *     (stable, but pays npx startup on every connect). Install globally and
+ *     re-run for the fast path.
+ */
+async function createLauncher({ binPath, selfBinPath, appStateDir, browser }) {
+  if (binPath) {
+    const hostPath = await createDirectLauncher(
+      path.resolve(binPath),
+      appStateDir,
+      browser,
+      "native-host-local-launcher",
+    );
+    return { hostPath, launchMode: "direct-bin" };
+  }
+  if (isNpxCachePath(selfBinPath)) {
+    const hostPath = await createNpxLauncher(appStateDir, browser);
+    return { hostPath, launchMode: "npx-launcher" };
+  }
+  const hostPath = await createDirectLauncher(
+    selfBinPath,
+    appStateDir,
+    browser,
+    "native-host-launcher",
+  );
+  return { hostPath, launchMode: "global-bin" };
+}
+
 // Each browser gets its own launcher so the native host knows which browser's
 // config to read for proxy mode. Chrome keeps the original unsuffixed filename
 // so manifests written before multi-browser support still resolve.
@@ -259,35 +297,57 @@ function launcherFileName(base, browser) {
   return browser === DEFAULT_BROWSER ? base : `${base}-${browser}`;
 }
 
-async function createNpxLauncher(appStateDir, browser = DEFAULT_BROWSER) {
-  if (process.platform === "win32") {
-    throw new Error("NPX native host launcher installation is not implemented for Windows yet.");
+/**
+ * A tiny shell shim that execs the installed Node CLI directly (no npx), so the
+ * host starts in milliseconds instead of paying npx's resolve/download cost on
+ * every Native Messaging connect. It prefers the Node.js used at install time
+ * and falls back to `node` on PATH, so a Node upgrade (which moves the versioned
+ * Homebrew/nvm path in process.execPath) does not strand the launcher. Chrome/
+ * Edge Native Messaging manifests cannot carry arguments, so `--native-host` and
+ * `--browser` are injected here.
+ */
+async function createDirectLauncher(binPath, appStateDir, browser, launcherBase) {
+  if (process.platform === "win32" || !binPath.endsWith(".js")) {
+    return binPath;
   }
-  const launcherPath = path.join(appStateDir, launcherFileName("native-host-launcher", browser));
+  const launcherPath = path.join(appStateDir, launcherFileName(launcherBase, browser));
   const script = `#!/usr/bin/env sh
-exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host --browser ${browser} "$@"
+node_bin=${shellQuote(process.execPath)}
+[ -x "$node_bin" ] || node_bin=node
+exec "$node_bin" ${shellQuote(binPath)} --native-host --browser ${browser} "$@"
 `;
   await fs.writeFile(launcherPath, script, { encoding: "utf8", mode: 0o755 });
   await fs.chmod(launcherPath, 0o755);
   return launcherPath;
 }
 
-async function createLocalLauncher(binPath, appStateDir, browser = DEFAULT_BROWSER) {
+async function createNpxLauncher(appStateDir, browser = DEFAULT_BROWSER) {
   if (process.platform === "win32") {
-    return binPath;
-  }
-  if (!binPath.endsWith(".js")) {
-    return binPath;
+    throw new Error("NPX native host launcher installation is not implemented for Windows yet.");
   }
-  const launcherPath = path.join(appStateDir, launcherFileName("native-host-local-launcher", browser));
+  const launcherPath = path.join(appStateDir, launcherFileName("native-host-launcher", browser));
   const script = `#!/usr/bin/env sh
-exec ${shellQuote(process.execPath)} ${shellQuote(binPath)} --browser ${browser} "$@"
+exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host --browser ${browser} "$@"
 `;
   await fs.writeFile(launcherPath, script, { encoding: "utf8", mode: 0o755 });
   await fs.chmod(launcherPath, 0o755);
   return launcherPath;
 }
 
+/**
+ * Absolute path to this package's own CLI entry, resolved from the installed
+ * module location so a global (or otherwise stable) install yields a launcher
+ * target that survives package upgrades.
+ */
+function resolveSelfBinPath() {
+  return fileURLToPath(new URL("../bin/codex-control-chrome-mcp.js", import.meta.url));
+}
+
+/** True when a path lives inside npm's `_npx` temp cache (subject to GC). */
+function isNpxCachePath(filePath) {
+  return filePath.split(path.sep).includes("_npx");
+}
+
 function shellQuote(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }

package/src/mcp-server.js

@@ -229,15 +229,15 @@ function registerTools(server, runtime) {
         url: z.string().url(),
       },
     },
-    async ({ tabId, url }) => {
-      await runtime.request("attach", { tabId });
-      await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
-      return toolResult(await executeCdp(runtime, {
-        tabId,
-        method: "Page.navigate",
-        params: { url },
-      }));
-    },
+    async ({ tabId, url }) =>
+      toolResult(await withReattach(runtime, tabId, async () => {
+        await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
+        return await executeCdp(runtime, {
+          tabId,
+          method: "Page.navigate",
+          params: { url },
+        });
+      })),
   );
 
   server.registerTool(
@@ -250,19 +250,19 @@ function registerTools(server, runtime) {
         awaitPromise: z.boolean().default(true),
       },
     },
-    async ({ tabId, expression, awaitPromise }) => {
-      await runtime.request("attach", { tabId });
-      await executeCdp(runtime, { tabId, method: "Runtime.enable", params: {} });
-      return toolResult(await executeCdp(runtime, {
-        tabId,
-        method: "Runtime.evaluate",
-        params: {
-          expression,
-          awaitPromise,
-          returnByValue: true,
-        },
-      }));
-    },
+    async ({ tabId, expression, awaitPromise }) =>
+      toolResult(await withReattach(runtime, tabId, async () => {
+        await executeCdp(runtime, { tabId, method: "Runtime.enable", params: {} });
+        return await executeCdp(runtime, {
+          tabId,
+          method: "Runtime.evaluate",
+          params: {
+            expression,
+            awaitPromise,
+            returnByValue: true,
+          },
+        });
+      })),
   );
 
   server.registerTool(
@@ -274,16 +274,16 @@ function registerTools(server, runtime) {
         format: z.enum(["png", "jpeg", "webp"]).default("png"),
       },
     },
-    async ({ tabId, format }) => {
-      await runtime.request("attach", { tabId });
-      await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
-      return toolResult(await executeCdp(runtime, {
-        tabId,
-        method: "Page.captureScreenshot",
-        params: { format, captureBeyondViewport: true },
-        timeoutMs: 30_000,
-      }));
-    },
+    async ({ tabId, format }) =>
+      toolResult(await withReattach(runtime, tabId, async () => {
+        await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
+        return await executeCdp(runtime, {
+          tabId,
+          method: "Page.captureScreenshot",
+          params: { format, captureBeyondViewport: true },
+          timeoutMs: 30_000,
+        });
+      })),
   );
 
   server.registerTool(
@@ -319,6 +319,38 @@ function registerTools(server, runtime) {
   );
 }
 
+/**
+ * Attach the debugger, run a CDP sequence, and self-heal a stale-attach state.
+ *
+ * The Codex Chrome extension tracks debugger attachments in memory. When Chrome
+ * tears an attachment down out-of-band (a competing debugger client, DevTools, a
+ * renderer/process swap), that flag can go stale: a fresh `attach` short-circuits
+ * and reports success without actually re-attaching, so the next CDP command
+ * fails with "Debugger is not attached". A `detach` clears the stale flag (it may
+ * itself throw "not attached" — expected, and ignored), after which `attach`
+ * re-attaches for real. We retry the sequence once on that specific error.
+ */
+export async function withReattach(runtime, tabId, run) {
+  await runtime.request("attach", { tabId });
+  try {
+    return await run();
+  } catch (error) {
+    if (!isNotAttachedError(error)) throw error;
+    try {
+      await runtime.request("detach", { tabId });
+    } catch {
+      // Detach throws when the debugger is already gone; we only need its side
+      // effect of clearing the extension's stale attach flag.
+    }
+    await runtime.request("attach", { tabId });
+    return await run();
+  }
+}
+
+export function isNotAttachedError(error) {
+  return /not attached/i.test(error?.message ?? String(error ?? ""));
+}
+
 async function executeCdp(runtime, { tabId, method, params = {}, timeoutMs }) {
   return await runtime.request(
     "executeCdp",