codex-control-chrome-mcp 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [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 |
@@ -161,16 +150,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 +164,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

@@ -203,20 +203,16 @@ Agent-side MCP config should use:
 }
 ```
 
-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:
+That launcher runs (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 "$@"
+npx -y codex-control-chrome-mcp@latest --native-host --browser chrome "$@"
 ```
 
 The native host manifest points to the launcher, not directly to `npx`.

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-control-chrome-mcp",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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://");
 }