Skip to content

browserbase/ModCDP

BranchesTags

Repository files navigation

ModCDP

CDP is powerful but it's been stretched to many use-cases beyond its initial audience. It is difficult for agents and humans to use without a harness library, because:

  • lacks the ability to use it statelessly without maintaining mappings of sessionIds, targetIds, frameIds, execution context IDs, backendNodeId ownership, and event listeners

  • lacks the ability to register custom CDP commands, abstractions, and events

  • lacks the ability to easily call chrome.* extension APIs for things like chrome.tabs.query({ active: true })

  • lacks the ability to reference pages and elements with stable references across browser runs, such as XPath, URL, and frame index, instead of unstable identifiers like sessionId, targetId, frameId, backendNodeId (unrealistic dream? maybe not)

While I had high hopes for WebDriver BiDi, unfortunately it solves almost none of these issues.

ModCDP does not aim to solve all of these issues directly either. Instead it solves a simpler problem: allowing us to customize and extend CDP with new commands. Then we use those basic primitives to fix the shortcomings in CDP by implementing our own custom events (all sent over a normal CDP websocket to a stock Chromium browser).

Primitive What it does
Mod.evaluate Run an expression in the ModCDP extension service worker, with chrome.* and a cdp bridge in scope
Mod.addCustomCommand Register a Custom.* method handler that lives in the SW
Mod.addCustomEvent Register a Custom.* event your SW handlers can emit()
Mod.addMiddleware Intercept service-worker-routed requests, responses, or events by name or *

Instead of inventing yet another browser driver library, ModCDP fixes the issue at the root.

It's perfectly compatible with playwright, puppeteer, etc. with no modifications. You can do things like patchright does, but generically at the CDP layer instead of having to patch libraries.

You can send Mod.*, Custom.*, etc. through standard Playwright/Puppeteer/other-driver-managed CDP sessions; js/examples/demo.ts, python/examples/demo.py, and go/examples/demo/main.go demonstrate the flow in each language.

Use it

import { ModCDPClient } from "modcdp";
import { z } from "zod";

const upstream_cdp_url = "http://127.0.0.1:9222"; // host:port, http(s), and ws(s) URLs work
const cdp = new ModCDPClient({
  launcher: { launcher_mode: "remote" },
  upstream: { upstream_mode: "ws", upstream_cdp_url },
  injector: { injector_mode: "auto" },
  client: { client_routes: { "Target.getTargets": "service_worker" } },
  server: { server_loopback_cdp_url: upstream_cdp_url, server_routes: { "*.*": "loopback_cdp" } },
});
await cdp.connect();

// use it like a normal CDP connection, send normal CDP, register for normal CDP events
console.log(await cdp.Browser.getVersion());
cdp.on(cdp.Target.targetInfoChanged, console.log);

// run extension code with chrome.* in scope
const tab = await cdp.Mod.evaluate({
  expression: "(await chrome.tabs.query({ active: true }))[0]",
});

// ✨ register and use custom CDP commands
await cdp.Mod.addCustomCommand({
  name: "Custom.tabIdFromTargetId",
  params_schema: { targetId: cdp.types.zod.Target.TargetID },
  result_schema: { tabId: z.number().nullable() },
  expression: `async ({ targetId }) => ({
    tabId: (await chrome.debugger.getTargets()).find(t => t.id === targetId)?.tabId ?? null
  })`,
});
const { targetInfos } = await cdp.Target.getTargets();
const pageTarget = targetInfos.find((targetInfo) => targetInfo.type === "page");
console.log(await cdp.send("Custom.tabIdFromTargetId", { targetId: pageTarget.targetId })); // -> { tabId: 22352432 }

// ✨ set up new custom CDP events to fire + receive them just like normal CDP
// this example sets up a truly accurate "foreground focus" tracking event,
// which CDP doesn't have natively https://issues.chromium.org/issues/497896141
const PageForegroundPageChanged = z
  .object({
    targetId: cdp.types.zod.Target.TargetID.nullable(),
    tabId: z.number(),
  })
  .passthrough()
  .meta({ id: "Page.foregroundPageChanged" });

await cdp.Mod.addCustomEvent(PageForegroundPageChanged);
await cdp.Mod.evaluate({
  expression: `chrome.tabs.onActivated.addListener(async ({ tabId }) =>
    cdp.emit("Page.foregroundPageChanged", {
      tabId,
      targetId: (await chrome.debugger.getTargets()).find(t => t.tabId === tabId)?.id ?? null
    })
  )`,
});
cdp.on(PageForegroundPageChanged, console.log);

// ✨ Intercept, modify, and extend existing CDP commands/results/events on the wire
await cdp.Mod.addMiddleware({
  name: cdp.Target.getTargets,
  phase: cdp.RESPONSE,
  // attach .tabId next to every .targetId in events browser emits
  expression: `async (payload, next) => {
    for (const targetInfo of payload.targetInfos) {
      const { tabId } = await cdp.send("Custom.tabIdFromTargetId", {
        targetId: targetInfo.targetId,
      });
      targetInfo.tabId = tabId;
    }
    return next(payload);
  }`,
});
console.log(await cdp.Target.getTargets()); // TargetInfo entries now include tabId

// typed + zod-enforced imperative aliases are generated for standard CDP too
const created = await cdp.Target.createTarget({ url: "https://example.com" });
await cdp.Target.activateTarget({ targetId: created.targetId }); // triggers Page.foregroundPageChanged
console.log(created);

Run the demos

Each demo launches Chrome with the fixed ModCDP extension artifact loaded, headful on macOS and --headless=new on Linux, then exercises raw CDP, Mod.evaluate, Custom.* commands, custom events, middleware, and latency reporting in the chosen mode. When stdin is a TTY, the demo leaves you in the same mini REPL/TUI across JS, Python, and Go.

pnpm run demo:js                    # defaults to --loopback --upstream=ws
pnpm run demo:js -- --debugger --upstream=pipe
pnpm run demo:js -- --loopback --upstream=reversews
pnpm run demo:js -- --loopback --upstream=nativemessaging
pnpm run demo:python
pnpm run demo:go

The Python package is managed with uv; pnpm run demo:python runs the built demo through uv and does not require a separate pip install. Set CHROME_PATH=/path/to/chromium to force a specific browser binary.

Transparent Proxy

Upgrade any vanilla CDP client like Stagehand, Playwright, or Puppeteer transparently with support for Mod.* / Custom.* commands and events.

pnpm run proxy -- --upstream-mode=ws --upstream-cdp-url=http://127.0.0.1:9222 --port 9223
pnpm run proxy -- --launcher-mode=local --upstream-mode=pipe --port 9223
pnpm run proxy -- --launcher-mode=local --upstream-mode=nativemessaging --port 9223
pnpm run proxy -- --launcher-mode=local --upstream-mode=nats --upstream-nats-url=ws://127.0.0.1:4223 --port 9223
# const browser = await playwright.chromium.connectOverCDP("http://127.0.0.1:9223")
# const session = await browser.contexts()[0].newCDPSession(page)
# await session.send("Mod.evaluate", { expression: "1 + 1" }) // -> 2
# ✨ All ModCDP commands now work through playwright! you can modify/extend playwright behavior to your heart's content

The proxy uses the same --launcher-*, --injector-*, --upstream-*, --client='{"client_routes": {...}}', and --server='{"server_routes": {...}}' option groups as ModCDPClient. --launcher-options='{...}' passes launcher-owned options such as headless and sandbox; --client-routes='{...}' and --server-routes='{...}' are route-only shorthands. ws keeps a transparent websocket-to-websocket fast path; pipe, nativemessaging, nats, and launched reversews proxy downstream CDP-shaped messages through the selected ModCDPClient upstream transport.

Native messaging mode creates the local native host wrapper and browser manifest on each run. The fixed extension auto-dials the default com.modcdp.bridge host, so the 1:1 automatic path does not require preinstalling a host binary at a fixed path. --upstream-nativemessaging-manifest, --upstream-nativemessaging-manifests, and --upstream-nativemessaging-host-name are for custom browser profiles, externally configured extensions, or isolated transport-level tests; the default auto-injected extension expects com.modcdp.bridge.

Reverse proxy mode

Use reverse mode when the browser does not expose a public CDP websocket to the final client, but the ModCDP extension can open a websocket back to a local proxy. The proxy still serves a normal-looking CDP endpoint to Playwright, Puppeteer, Stagehand, or any other CDP client:

pnpm run proxy -- --upstream-mode=reversews --upstream-reversews-bind=127.0.0.1:29292 --listen 127.0.0.1:9223
pnpm run proxy -- --launcher-mode=local --upstream-mode=reversews --upstream-reversews-bind=127.0.0.1:29292 --port 9223
# const browser = await playwright.chromium.connectOverCDP("http://127.0.0.1:9223")

Reverse mode is opt-in. The shipped extension has no generated runtime config; it always tries the fixed local reverse connector at ws://127.0.0.1:29292. With --launcher-mode=local, use that default bind and the normal ModCDPClient launcher, injector, and ReverseWebSocketUpstreamTransport path will wake the service worker and accept its connection. With --launcher-mode=none or a non-default bind, an already-running extension or test must explicitly call globalThis.ModCDP.startReverseBridge("ws://host:port", { reconnect_interval_ms: 2000 }) with the chosen endpoint because there is no side channel before the reverse connection exists. --upstream-reversews-wait-timeout-ms controls how long the proxy/client waits for that extension connection. Once it connects, it self-identifies as a ModCDP extension service worker and the proxy uses that reverse websocket as its upstream. Mod.*, expression-backed Custom.* commands, custom event fanout, middleware, and normal CDP commands all stay routed through globalThis.ModCDP.handleCommand(...) in the service worker.

Reverse mode is intentionally scoped to one local browser and one reverse extension connection per proxy process. The browser may still have other extensions installed; ModCDP does not require --disable-extensions-except.

Routing modes

Mod.* and Custom.* always go through the extension service worker. Routing only changes how standard CDP methods (Browser.*, Page.*, DOM.*, …) are serviced:

Demo CLI Flag Standard CDP path Use when
--loopback client → SW → SW dials its own WS back to localhost:9222 → CDP Default. You need the SW to intercept/inspect/rewrite normal traffic.
--debugger client → SW → chrome.debugger.sendCommand against the active tab The browser exposes no remote CDP port and you only have extension permissions.
--direct client → sends non-ModCDP commands to browser CDP directly You already have a CDP endpoint and don't need extension interception.

Pass via client: { client_routes: { "*.*": "direct_cdp" | "service_worker" } } and server: { server_routes: { "*.*": "loopback_cdp" | "chrome_debugger" } }. The demos default to --loopback (the most powerful mode).

Repository layout

extension/                MV3 extension shell and static pages
  manifest.json
  src/
  pages/
js/                       TypeScript client/server/proxy package
  src/
    client/
    server/
    launcher/
    injector/
    transport/
    router/
    translate/
    proxy/
    types/
  examples/
  test/
python/                   Python package, examples, and tests
  modcdp/
    client/
    launcher/
    injector/
    transport/
    router/
    translate/
    types/
go/                       Go module, examples, and tests
  modcdp/
    client/
    launcher/
    injector/
    transport/
    router/
    translate/
    types/
dist/                     Built JS output used by the extension and Node CLI scripts

Requirements

  • Stock Google Chrome can be used without relaunch flags: visit chrome://inspect/#remote-debugging to expose the current browser at http://127.0.0.1:9222, and load/install the ModCDP extension in that profile. Pass that endpoint as upstream: { upstream_mode: "ws", upstream_cdp_url: "http://127.0.0.1:9222" }.
  • Automated/test browsers can still preload the extension with --load-extension=<path>. Extensions.loadUnpacked is used as a fallback when the connected browser exposes it over CDP.
  • Node ≥ 22, Python ≥ 3.11 with websocket-client, Go ≥ 1.25 with gobwas/ws.
Architecture & lifecycle

Connect

  1. Select a launcher class and an upstream transport. launcher.launcher_mode="local" starts a local browser, launcher.launcher_mode="remote" uses the supplied upstream.upstream_cdp_url, and launcher.launcher_mode="none" leaves browser lifecycle outside ModCDP.
  2. The configured extension injector classes try discovery, launch-arg injection, Browserbase upload, Extensions.loadUnpacked, or borrowing in the configured order.
  3. Attach a session to that SW target and Runtime.enable on it.
  4. Call globalThis.ModCDP.configure(...) to push the resolved loopback websocket and any explicit server route overrides into the SW. The clients do this automatically by default.

Reverse proxy mode flips the bootstrap direction: js/src/proxy/proxy.ts --upstream-mode=reversews --upstream-reversews-bind=127.0.0.1:29292 listens for the extension, while still serving downstream clients from --listen. The extension artifact is fixed, so automatic launch/injection uses the default 127.0.0.1:29292 connector; non-default reverse binds need an external bootstrap call to globalThis.ModCDP.startReverseBridge(...) with the same URL. The service worker sends a modcdp.reverse.hello message and then accepts CDP-shaped command messages from the proxy. The proxy maps downstream request IDs to reverse request IDs and forwards reverse events back to the downstream CDP client.

Send

  • Mod.evaluate({ expression, params, cdpSessionId }) → Runtime.evaluate on the ext session, wrapping the expression with an IIFE that exposes params and cdp = ModCDP.attachToSession(...).
  • Mod.addCustomCommand({ name, expression, ... }) → Runtime.evaluate calling globalThis.ModCDP.addCustomCommand({ ... }) with the user expression embedded as the handler.
  • Mod.addCustomEvent(EventSchema.meta({ id })) → Runtime.evaluate registering the event in globalThis.ModCDP; all custom events are delivered through the single __ModCDP_custom_event__ binding installed at connect time.
  • Mod.addMiddleware({ name, phase, expression }) → Runtime.evaluate registering a service-worker middleware for phase: "request" | "response" | "event". Use name: "*" to match every method/event in that phase, or pass generated names like cdp.Target.targetInfoChanged.
  • Custom.X(params) → Runtime.evaluate calling globalThis.ModCDP.handleCommand("Custom.X", params, cdpSessionId).

In reverse mode, expression-backed commands cannot use new Function directly because MV3 extension CSP blocks unsafe eval. The service worker evaluates user expressions by attaching chrome.debugger to its own service-worker target and issuing Runtime.evaluate, preserving the normal ModCDP expression surface without weakening extension CSP.

Receive

When SW handlers cdp.emit('Custom.X', payload), the SW invokes globalThis.__ModCDP_custom_event__(JSON.stringify({ event, data, cdpSessionId })). CDP delivers Runtime.bindingCalled on the ext session; the client (or proxy) decodes the payload and re-dispatches it as a normal cdp.on('Custom.X', ...) event.

In reverse mode, the same publishEvent(...) path also sends CDP-shaped event messages over the reverse websocket, so custom events and mirrored upstream events fan out through the standalone proxy to the downstream client.

Why this works

Runtime.addBinding is the only out-of-page → in-page → out-of-page channel CDP exposes. Combined with one extension service worker (which gets chrome.* access as a side effect of being in an extension), you get:

  • A guaranteed JS execution context that's not a page, with the right permissions
  • A way to push named events back through the same CDP socket your client already speaks
  • The same command/event surface whether the bytes arrive by websocket, pipe, native messaging, reverse websocket, or NATS.
Routing details 
type CDPUpstream = "service_worker" | "direct_cdp" | "auto" | "loopback_cdp" | "chrome_debugger";

// client-side defaults
const client_routes = { "Mod.*": "service_worker", "Custom.*": "service_worker", "*.*": "service_worker" } as const;

// server-side defaults (inside the SW)
const server_routes = { "Mod.*": "service_worker", "Custom.*": "service_worker", "*.*": "auto" } as const;
  • service_worker — handle in the extension SW.
  • direct_cdp (client only) — send straight to the browser CDP websocket.
  • auto (server only) — try loopback_cdp first, fall back to chrome_debugger.
  • loopback_cdp (server only) — SW dials a CDP websocket reachable from the browser. You may pass http://host:port as shorthand, but it is resolved to the concrete ws://.../devtools/... URL at configuration time. Useful for Browser.* commands that chrome.debugger doesn't support.
  • chrome_debugger (server only) — chrome.debugger.sendCommand against params.debuggee || { tabId, targetId, extensionId }, defaulting to the active last-focused tab.

Route resolution is deterministic across all three language clients: exact-method match → longest-prefix wildcard → *.* fallback. This avoids map-iteration nondeterminism (Go) and key-insertion-order shadowing (JS/Python).

When server-side auto routing tries loopback CDP discovery, the SW only trusts 127.0.0.1:9222 after verifying a per-connection server.server_browser_token against its own service-worker target. It will not accidentally route loopback commands through a different browser that happens to have the same extension installed.

Wire diagrams

1. Normal CDP Call / Response

flowchart LR
  subgraph Node["Node client"]
    direction LR
    SDK["SDK"]
    WS["WS client"]
    SDK -->|"1. cdp.send('Browser.getVersion')"| WS
  end

  subgraph Browser["Browser"]
    direction LR
    CDP["CDP router<br/>localhost:9222"]
    SW["Extension service worker<br/>CDP target / JS context"]
    Page["Page target"]
    CDP -. "can dispatch to target" .-> Page
  end

  Socket["CDP socket"]

  WS <-->|"2. CDP Browser.getVersion<br/>5. response"| Socket
  Socket <-->|"3. Standard CDP request<br/>4. Standard CDP response"| CDP

  classDef idle fill:#f7f7f7,stroke:#bbb,color:#777;
  class SW,Page idle;
Loading

2. Normal CDP Event Listener / Event

flowchart LR
  subgraph Node["Node client"]
    direction LR
    SDK["SDK"]
    WS["WS client"]
    SDK -->|"1. cdp.on('Target.targetCreated', ...)"| WS
    SDK -->|"2. cdp.Target.createTarget({url})"| WS
  end

  subgraph Browser["Browser"]
    direction LR
    CDP["CDP router<br/>localhost:9222"]
    SW["Extension service worker<br/>CDP target / JS context"]
    Page["Page target<br/>chrome://newtab/"]
    CDP -->|"5. dispatch to page target"| Page
  end

  Socket["CDP socket"]

  WS -->|"3. CDP Target.createTarget"| Socket
  Socket -->|"4. Standard CDP"| CDP
  CDP -->|"6. create page target"| Page
  Page -->|"7. Target.targetCreated<br/>{targetInfo}"| CDP
  CDP -->|"8. Target.targetCreated<br/>{targetInfo}"| Socket
  Socket -->|"9. Target.targetCreated<br/>{targetInfo}"| WS
  WS -->|"10. emit('Target.targetCreated', {targetInfo})"| SDK

  classDef idle fill:#f7f7f7,stroke:#bbb,color:#777;
  class SW idle;
Loading

3. ModCDP Custom Call / Response

flowchart LR
  subgraph Node["Node client"]
    direction LR
    SDK["SDK"]
    WS["WS client"]
    SDK -->|"1. cdp.send('Mod.evaluate', ...)"| WS
  end

  subgraph Browser["Browser"]
    direction LR
    ClientCDP["CDP Session for client<br/>localhost:9222"]
    LoopbackCDP["CDP Session for loopback<br/>localhost:9222"]
    SW["Extension service worker<br/>CDP target / JS context<br/>globalThis.ModCDP"]
    Page["Page target"]
    ClientCDP -->|"4. dispatch Runtime.evaluate(Mod.evaluate)"| SW
    LoopbackCDP -->|"7. Input.dispatchMouseEvent"| Page
    Page -->|"8. Input.dispatchMouseEvent result"| LoopbackCDP
    SW -. "<s>chrome.debugger</s><br/>not used" .-> Page
  end

  ClientSocket["client CDP socket.<br/>carries Mod.evaluate ..."]
  LoopbackSocket["loopback CDP socket.<br/>carries standard CDP only"]

  ClientSocket ~~~ LoopbackSocket
  WS -->|"2. Runtime.evaluate(Mod.evaluate)"| ClientSocket
  ClientSocket -->|"3. Runtime.evaluate(Mod.evaluate)"| ClientCDP
  SW -->|"5. WebSocket CDP loopback<br/>out of Browser<br/>Input.dispatchMouseEvent"| LoopbackSocket
  LoopbackSocket -->|"6. Input.dispatchMouseEvent"| LoopbackCDP
  LoopbackCDP -->|"9. Input.dispatchMouseEvent result"| LoopbackSocket
  LoopbackSocket -->|"10. Input.dispatchMouseEvent result<br/>back into Browser"| SW
  SW -->|"11. Runtime.evaluate(Mod.evaluate) result"| ClientCDP
  ClientCDP -->|"12. Runtime.evaluate(Mod.evaluate) result"| ClientSocket
  ClientSocket -->|"13. => {ok, action, target}"| WS
Loading

The same transport shape applies to Mod.addCustomCommand: the client installs a named command handler in the service worker, and later cdp.send('Custom.someCommand', params) is routed back through globalThis.ModCDP.handleCommand(...).

4. ModCDP Custom Event Listener / Event

flowchart LR
  subgraph Node["Node client"]
    direction LR
    SDK["SDK"]
    WS["WS client"]
    SDK -->|"1. cdp.on('Custom.demo', ...)"| WS
    SDK -->|"6. cdp.send('Mod.evaluate', ...)"| WS
  end

  subgraph Browser["Browser"]
    direction LR
    ClientCDP["CDP Session for client<br/>localhost:9222"]
    LoopbackCDP["CDP Session for loopback<br/>localhost:9222"]
    SW["Extension service worker<br/>CDP target / JS context<br/>ModCDP + bindings"]
    Page["Page target"]
    ClientCDP -->|"5. dispatch Runtime.evaluate(Mod.addCustomEvent)<br/>9. dispatch Runtime.evaluate(Mod.evaluate)"| SW
    LoopbackCDP -->|"12. Input.dispatchMouseEvent"| Page
    Page -->|"13. Input.dispatchMouseEvent result"| LoopbackCDP
    SW -. "<s>chrome.debugger</s><br/>not used" .-> Page
  end

  ClientSocket["client CDP socket.<br/>carries ModCDP ..."]
  LoopbackSocket["loopback CDP socket.<br/>carries standard CDP only"]

  ClientSocket ~~~ LoopbackSocket
  WS -->|"2. CDP Runtime.addBinding"| ClientSocket
  WS -->|"3. Mod.addCustomEvent<br/>7. Mod.evaluate(cdp.emit(...))"| ClientSocket
  ClientSocket <-->|"4. Runtime.evaluate(Mod.addCustomEvent)<br/>8. Runtime.evaluate(Mod.evaluate)"| ClientCDP
  SW -->|"10. WebSocket CDP loopback<br/>out of Browser<br/>Input.dispatchMouseEvent"| LoopbackSocket
  LoopbackSocket -->|"11. Input.dispatchMouseEvent"| LoopbackCDP
  LoopbackCDP -->|"14. Input.dispatchMouseEvent result"| LoopbackSocket
  LoopbackSocket -->|"15. Input.dispatchMouseEvent result<br/>service worker emits custom event"| SW
  SW -->|"16. Runtime.bindingCalled<br/>{name:'__ModCDP_custom_event__', payload:'{event:Custom.demo,data:test}'}"| ClientCDP
  ClientCDP -->|"17. Standard CDP event<br/>Runtime.bindingCalled {name:'__ModCDP_custom_event__', payload:'{event:Custom.demo,data:test}'}"| ClientSocket
  ClientSocket -->|"18. Standard CDP event<br/>Runtime.bindingCalled {name:'__ModCDP_custom_event__', payload:'{event:Custom.demo,data:test}'}"| WS
  WS -->|"19. emit('Custom.demo', 'test')"| SDK
Loading
Constraints & alternatives explored

Constraints

  • This does not add real CDP methods to Chrome — the wire methods stay Runtime.evaluate + Runtime.bindingCalled. The Mod.* / Custom.* namespace is a client + SW convention.
  • Page JS does not see custom commands or event bindings.
  • Stock Google Chrome's chrome://inspect/#remote-debugging toggle can expose the current browser at localhost:9222 without relaunching with --remote-debugging-port, --enable-unsafe-extension-debugging, or --remote-allow-origins=*.
  • If Extensions.loadUnpacked is unavailable in the connected browser, load/install the ModCDP extension in that Chrome profile once and reconnect; the injector will use the discovery path.

Alternatives considered

  • chrome.debugger — used as the server-side fallback, but doesn't expose other connected CDP clients or the raw protocol stream.
  • Extension WebSocket → pass the actual ws://.../devtools/browser/... CDP endpoint directly; HTTP /json/* discovery is only a compatibility fallback for http://host:port shorthand.
  • Listening to another CDP client's traffic — separate clients don't see each other's messages.
  • WebMCP — page-visible/tool-oriented, unsuitable when page JS must not detect the control plane.
  • Extensions.* storage mailbox — slower and more brittle than the SW target.
  • A separate local CDP proxy process — clean, but unnecessary for the default flow; the proxy here is opt-in (only used when "upgrading" a vanilla CDP client).
Latency (local PoC, headless Chromium 141) 
launchToFirstBrowserGetVersion:      1262.6 ms
normalBrowserGetVersionRoundTrip:       0.7 ms
smuggledCustomPingRoundTrip:            9.3 ms
normalOnSubscribeTriggerEvent:          1.8 ms
smuggledCustomOnSubscribeTriggerEvent: 29.6 ms

Custom roundtrip overhead is dominated by Runtime.evaluate + the SW's loopback CDP dial, not by wrap/unwrap. Avoid auto discovery in latency-sensitive paths if you can pre-configure loopback_cdp_url directly.

macOS Chrome compatibility matrix (tested 2026-05-01)

Tested browsers:

  • /Applications/Google Chrome.app — Google Chrome 148.0.7778.96 beta
  • /Applications/Google Chrome Canary.app — Google Chrome 149.0.7819.0 canary
  • Playwright Chrome for Testing — 147.0.7727.15

Latency columns:

  • direct — ModCDP client to browser raw CDP Page.getFrameTree against an attached chrome://newtab/ page target.
  • pong — ModCDP client to browser to extension service worker Mod.pong round trip.
  • loopback — ModCDP client to browser to extension service worker to loopback CDP to browser Page.getFrameTree.
  • debugger — ModCDP client to browser to extension service worker to chrome.debugger.sendCommand Page.getFrameTree.

The launched-browser rows used an isolated temporary user data dir. The live/default-profile row is separate because it depends on the user enabling Chrome's chrome://inspect/#remote-debugging flow and accepting Chrome's connection prompt.

Browser UI Mode Works chrome.tabs.query chrome.debugger Browser.getVersion Target.getTargets Default profile direct ms pong ms loopback ms debugger ms
Chrome Beta 148 --headless=new --direct yes yes no yes yes no 4.8 3 - -
Chrome Beta 148 --headless=new --loopback yes yes no yes yes no 2.3 2 13.5 -
Chrome Beta 148 --headless=new --debugger no yes no no no no 5.3 5 - -
Chrome Beta 148 headful --direct yes yes no yes yes no 5.1 1 - -
Chrome Beta 148 headful --loopback yes yes no yes yes no 2.4 1 13.5 -
Chrome Beta 148 headful --debugger no yes no no no no 2.2 2 - -
Chrome Canary 149 --headless=new --direct yes yes yes yes yes no 2.2 1 - -
Chrome Canary 149 --headless=new --loopback yes yes yes yes yes no 2.6 1 14.4 -
Chrome Canary 149 --headless=new --debugger yes yes yes no no no 2.1 1 - 1.4
Chrome Canary 149 headful --direct yes yes yes yes yes no 2.4 1 - -
Chrome Canary 149 headful --loopback yes yes yes yes yes no 2.2 1 13.5 -
Chrome Canary 149 headful --debugger yes yes yes no no no 2.3 0 - 1.2
Playwright Chrome for Testing 147 --headless=new --direct yes yes yes* yes yes no 2.3 3 - -
Playwright Chrome for Testing 147 --headless=new --loopback yes yes yes* yes yes no 1.9 1 13.0 -
Playwright Chrome for Testing 147 --headless=new --debugger yes yes yes* no no no 2.6 1 - 0.7
Playwright Chrome for Testing 147 headful --direct yes yes yes* yes yes no 2.0 1 - -
Playwright Chrome for Testing 147 headful --loopback yes yes yes* yes yes no 2.4 1 12.5 -
Playwright Chrome for Testing 147 headful --debugger yes yes yes* no no no 2.1 1 - 1.2

* Playwright Chrome for Testing exposes chrome.debugger when the ModCDP extension is launched with --load-extension. With auto-injection only, --direct and --loopback still work, but chrome.debugger is not available in the borrowed/injected service worker.

Live/default-profile status:

Browser UI Mode Result
Chrome Beta 148 --headless=new --live not applicable
Chrome Beta 148 headful --live current advertised DevToolsActivePort was stale; websocket failed with ECONNREFUSED 127.0.0.1:9222
Chrome Canary 149 --headless=new --live not applicable
Chrome Canary 149 headful --live no active live endpoint found
Playwright Chrome for Testing 147 --headless=new --live not applicable
Playwright Chrome for Testing 147 headful --live no active live endpoint found

Minimum viable macOS CLI args:

Mode Browsers Args
--direct headful all three --remote-debugging-port=<port> --user-data-dir=<temp-profile> chrome://newtab/
--direct headless all three --headless=new --remote-debugging-port=<port> --user-data-dir=<temp-profile> chrome://newtab/
--loopback headful all three --remote-debugging-port=<port> --user-data-dir=<temp-profile> --remote-allow-origins=* chrome://newtab/
--loopback headless all three --headless=new --remote-debugging-port=<port> --user-data-dir=<temp-profile> --remote-allow-origins=* chrome://newtab/
--debugger Chrome Beta 148 no working set found; chrome.debugger is unavailable in the extension service worker
--debugger headful Chrome Canary 149 --remote-debugging-port=<port> --user-data-dir=<temp-profile> chrome://newtab/
--debugger headless Chrome Canary 149 --headless=new --remote-debugging-port=<port> --user-data-dir=<temp-profile> chrome://newtab/
--debugger headful Playwright Chrome for Testing 147 --remote-debugging-port=<port> --user-data-dir=<temp-profile> --load-extension=<repo>/dist/extension chrome://newtab/
--debugger headless Playwright Chrome for Testing 147 --headless=new --remote-debugging-port=<port> --user-data-dir=<temp-profile> --load-extension=<repo>/dist/extension chrome://newtab/

Recommended full macOS launch args:

--remote-debugging-port=<port>
--user-data-dir=<temp-profile>
--remote-allow-origins=*
--enable-unsafe-extension-debugging
--load-extension=<repo>/dist/extension
--no-first-run
--no-default-browser-check
--disable-default-apps
--disable-background-networking
--disable-backgrounding-occluded-windows
--disable-renderer-backgrounding
--disable-background-timer-throttling
--disable-sync
--password-store=basic
--use-mock-keychain
chrome://newtab/

Add --headless=new for headless launches. Do not pass --no-sandbox, --disable-gpu, or --remote-debugging-address on macOS. On Linux only, pass --no-sandbox when there is no usable sandbox/display environment.

About

Extend the Chrome Debug Protocol (CDP) with custom commands, events, and middlewares. Tap into and modify browser behavior, access chrome.* extension APIs, and change how drivers like stagehand/playwright/puppeteer work.

Topics

chrome-extension cdp browser-automation chrome-devtools-protocol

Resources

Readme
Activity
Custom properties

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

12 tags

Packages

 
 
 

Contributors

Languages