Vibeleaderboard
← Back to Tools
Index / tool

ModCDP

https://github.com/browserbase/modcdp
Visit github.com
Category
Developer Tools
Rank
No. 1651Tools index
Pricing
Open Source
Type
TOOL
Builder
browserbase
GitHub
8 stars
Date

About

Extend the Chrome Debug Protocol with custom commands, events, and middlewares. Modify browser behavior and change how stagehand, playwright, and puppeteer drivers work.

What it does

ModCDP places a browser extension service worker behind an ordinary Chrome debugging connection. That worker can execute expressions with extension APIs available, while a client or proxy routes browser messages through it. Existing automation clients keep speaking the familiar protocol.

Why it's ranked here

This is compelling infrastructure for teams blocked by gaps in Chrome’s debugging interface. It preserves compatibility with existing automation clients while moving browser-specific logic into an extension service worker. Multiple routing and transport choices make it unusually flexible, though that flexibility brings setup cost.

What's good

Custom behavior remains accessible through standard debugging sessions, including those managed by Playwright and Puppeteer. Schemas validate custom command inputs and results. TypeScript, Python, and Go expose aligned public surfaces, while demos exercise real browser traffic, middleware, events, and latency reporting.

Tradeoffs

The architecture requires a browser extension plus careful launcher, injector, router, server, and transport configuration. Node users need version 22 or newer. Native messaging depends on Chrome launching a configured host. Reverse mode supports one local browser and one extension connection per proxy process.

How to use it well

Choose it when browser automation needs extension APIs, richer browser events, or protocol-level interception without replacing an established driver. Start with the loopback demo, then narrow routing as requirements become clear. It is not a general automation framework, nor does it independently provide stable page and element references.

Technical notes+

extension/src/service_worker.ts starts ModCDPServer inside the MV3 service worker. js/src/index.ts, python/modcdp/__init__.py, and go/modcdp/modcdp.go expose deliberately synchronized client, launcher, injector, router, transport, translation, and type surfaces. package.json publishes an ESM npm package, requires Node >=22, declares Zod as its runtime dependency, and exposes the proxy CLI as a module entry. js/scripts/build-extension-assets.mjs bundles for Chrome 116, creates a reproducible extension archive, and copies that archive into the Python and Go packages. vitest.config.ts discovers tests under js/test.

Observed

Primary language surface
TypeScript implements the Node client, server, proxy, extension, and build tooling.
Additional language interfaces
Python and Go packages mirror the public client, launcher, injector, transport, router, translation, and type surfaces.
Packaging
Published as an ESM npm package, with bundled extension archives also copied into Python and Go packages.
Interfaces
Provides language libraries and a transparent command-line CDP proxy.
Browser platform
Targets Chromium through an MV3 extension service worker and standard CDP connections.
Operating system demos
Repository demos launch Chrome headful on macOS and in new headless mode on Linux.
Tests
The repository contains JavaScript and Go test files, with Vitest configured for the JavaScript test tree.

Read from README.md, package.json, vitest.config.ts, js/src/index.ts, go/modcdp/modcdp.go, go/modcdp/modcdp_test.go, python/modcdp/__init__.py, extension/src/service_worker.ts, js/scripts/build-extension-assets.mjs, js/src/proxy/cli.ts, go/modcdp/client/CDPTypes.go, extension/src/pages/options.ts, python/modcdp/types/__init__.py, python/modcdp/client/__init__.py, python/modcdp/router/__init__.py.

What it can do

  • Add custom commands to Chrome Debug Protocol

    Custom command definitions → Extended CDP with new commands

  • Add custom events to Chrome Debug Protocol

    Custom event definitions → Extended CDP with new events

  • Install middleware for Chrome Debug Protocol

    Middleware functions → Modified CDP request/response pipeline

  • Modify browser behavior through CDP extensions

    Browser behavior modification rules → Altered browser runtime behavior

  • Change Playwright driver behavior

    Playwright driver modifications → Modified Playwright automation behavior

  • Change Puppeteer driver behavior

    Puppeteer driver modifications → Modified Puppeteer automation behavior

  • Change Stagehand driver behavior

    Stagehand driver modifications → Modified Stagehand automation behavior

Tags

cdpchromebrowser-automationplaywrightpuppeteer

Tech Stack

Node.jsTypeScript

Comments (0)

No comments yet

Editorially curated, with community endorsements as a secondary signal. Corrections welcome.