codex-control-chrome-mcp 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-03
+
+### 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
+
+- Native host failed to start on 1.2.0. The install launcher runs the host with `--browser <name>` before the extension origin that Chrome appends, so the origin was no longer `args[0]`. The CLI dispatcher only recognized native-host mode when the origin was `args[0]`, so the launcher's argv fell through to `Unknown command: --browser` and the host exited on every connect. The visible symptoms were the Codex extension connection flapping between connected/disconnected and `status` never listing a bridge socket (`sockets: []`). The dispatcher now detects the origin by shape anywhere in the args, and a regression test covers the launcher argv.
+
 ## [1.2.0] - 2026-06-29
 
 ### Added

package/README.md

@@ -15,17 +15,6 @@ This is an independent community project. It is not affiliated with OpenAI, Code
 - Chrome Extension: [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)
 - Skill: [`skills/codex-control-chrome-mcp/SKILL.md`](./skills/codex-control-chrome-mcp/SKILL.md)
 
-## Status
-
-The current implementation provides:
-
-- official `@modelcontextprotocol/sdk` stdio server
-- Chrome and Microsoft Edge Native Messaging host mode
-- install/uninstall commands with manifest backup
-- JSON-RPC bridge socket under `/tmp/codex-browser-use`
-- Chrome tab, navigation, screenshot, CDP, and event MCP tools
-- bundled skill documentation for Agent tool ordering
-
 ## Platform Support
 
 | Platform | Status | Notes |
@@ -51,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
 
@@ -161,16 +152,12 @@ node ./bin/codex-control-chrome-mcp.js --native-host
 
 ## Troubleshooting
 
-`status` reports, per browser (under `install.chrome` / `install.edge`), a `registered` flag and a `classification` of the live manifest. When `registered` is `false` and `classification.kind` is `official-openai`, a Codex update has reclaimed that browser's manifest (see below). `classification` identifies OpenAI's genuine host by stable signals — the `com.openai.codexextension` name, the official extension origin, the bundle path, the binary format, and (on macOS) the OpenAI code signature — not by filename.
-
 ### A Codex update stopped the bridge
 
 Codex App/extension updates re-register their own `com.openai.codexextension` native-messaging manifest, which overwrites this project's proxy registration (the bundled host binary has even been renamed across releases). The symptom is `status` showing `sockets: []`, `registered: false`, and a manifest `path` back inside the Codex bundle.
 
 The MCP stdio server now **self-heals**: on startup it re-asserts the manifest when it detects it was reverted, so you usually do not need to re-run `install-native-host`. Because Chrome only reads the manifest when the extension reconnects, **reload the Codex Chrome Extension (or restart Chrome) once** after a Codex update to bring the bridge back. Set `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1` to disable the auto re-register.
 
-If `status` shows no bridge sockets, reload Chrome or the Codex Chrome Extension after installing the native host.
-
 If Codex App integration stops working, uninstall this native host to restore the backed-up manifest:
 
 ```bash
@@ -179,6 +166,8 @@ npx -y codex-control-chrome-mcp@latest uninstall-native-host
 
 If tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.
 
+See [Install And Uninstall](./docs/install.md#troubleshooting) for the full per-browser checklist (the `registered` flag and host `classification`).
+
 ## License
 
 MIT

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,34 +189,35 @@ 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"]
 }
 ```
 
-Chrome Native Messaging manifests cannot store command arguments. Therefore `install-native-host` creates a stable launcher script:
-
-```sh
-npx -y codex-control-chrome-mcp@latest install-native-host
-```
+Chrome Native Messaging manifests cannot store command arguments. Therefore `install-native-host` writes a stable launcher script at:
 
 ```text
 ~/.codex-control-chrome-mcp/native-host-launcher
 ```
 
-That launcher runs:
+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@1.0.0 --native-host "$@"
+#!/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

@@ -8,13 +8,6 @@ Package:
 
 ## Development Status
 
-The current implementation provides:
-
-- MCP stdio mode: `npx -y codex-control-chrome-mcp@latest --stdio`
-- manifest install: `npx -y codex-control-chrome-mcp@latest install-native-host`
-- manifest uninstall: `npx -y codex-control-chrome-mcp@latest uninstall-native-host`
-- bridge/socket status: `npx -y codex-control-chrome-mcp@latest status`
-
 Do not run install on a machine where Codex Chrome integration is important unless you are ready to test proxy mode or restore from backup.
 
 This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.
@@ -40,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.
@@ -53,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.
@@ -98,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.0",
+  "version": "1.3.0",
   "description": "MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -13,21 +13,19 @@ import { probeLengthPrefixedSocket } from "./probe.js";
 
 export async function runCli(argv) {
   const args = argv.slice(2);
-  const command = args[0];
+  const invocation = classifyInvocation(args);
 
-  if (args.includes("--stdio") || command === "stdio") {
+  if (invocation.mode === "mcp") {
     await runMcpServer();
     return;
   }
 
-  if (args.includes("--native-host") || looksLikeChromeOrigin(command)) {
-    // Chrome/Edge append the extension origin as a positional arg, so find it
-    // by shape rather than position (the `--browser` flag shifts the indices).
-    const origin = args.find(looksLikeChromeOrigin) ?? argv[3];
-    await runNativeHost({ origin, browser: normalizeBrowser(readOption(args, "--browser")) });
+  if (invocation.mode === "native-host") {
+    await runNativeHost({ origin: invocation.origin ?? argv[3], browser: invocation.browser });
     return;
   }
 
+  const command = invocation.command;
   switch (command) {
     case "install-native-host": {
       const binPath = readOption(args, "--bin");
@@ -78,6 +76,31 @@ export async function runCli(argv) {
   }
 }
 
+/**
+ * Decide how an invocation should be handled, purely from the CLI args.
+ *
+ * Chrome/Edge launch the native host by appending the extension origin as a
+ * positional arg, and the install launcher prepends `--browser <name>`. That
+ * prefix shifts the origin out of `args[0]`, so both the mode check and the
+ * origin lookup must scan by shape rather than position. (A 1.2.0 regression
+ * only checked `args[0]` here, so the launcher's `--browser`-prefixed argv fell
+ * through to `Unknown command: --browser` and the native host exited on every
+ * connect.)
+ */
+export function classifyInvocation(args) {
+  if (args.includes("--stdio") || args[0] === "stdio") {
+    return { mode: "mcp" };
+  }
+  if (args.includes("--native-host") || args.some(looksLikeChromeOrigin)) {
+    return {
+      mode: "native-host",
+      origin: args.find(looksLikeChromeOrigin),
+      browser: normalizeBrowser(readOption(args, "--browser")),
+    };
+  }
+  return { mode: "command", command: args[0] };
+}
+
 function looksLikeChromeOrigin(value) {
   return typeof value === "string" && value.startsWith("chrome-extension://");
 }

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("'", "'\\''")}'`;
 }