What is Chrome DevTools Protocol (CDP)?
By Steven Van ·
Browser Use's explainer covers CDP messages, targets and sessions, when to use it over Playwright or Puppeteer, and a Node walkthrough.
Browser Use has published an explainer on Chrome DevTools Protocol (CDP), the low-level protocol for inspecting and controlling Chromium-based browsers. CDP exposes JavaScript execution, DOM inspection, network monitoring and page rendering through structured messages. Chrome DevTools uses it, and so do automation libraries such as Playwright and Puppeteer. Browser Use notes that the protocol has recently grown in popularity because AI browser agents adopted it. The article covers how it works and when to use it, and ends with a worked example.
How CDP works
CDP is bidirectional and follows a client-server model. The client sends commands and the browser returns responses. The browser also sends events, such as when a request starts or a page finishes its initial load. Messages usually travel over a WebSocket, though OS-level pipes are supported for local use. It works in both headful and headless mode.
Capabilities are grouped into domains. Page handles navigation, Runtime evaluates JavaScript, Network reports requests and responses, and Tracing records performance data.
Messages use an adapted form of JSON-RPC. A command has an id, a method and optional params. A response repeats the id and contains result or error. An event has a method and possibly params, but no request id. CDP messages normally omit the jsonrpc field, so the article says calling CDP fully compliant with JSON-RPC 2.0 is inaccurate.
The article also explains targets and sessions. A target is something that can be debugged or controlled, such as a tab, iframe or worker, and generally has a targetId. A session is the connection to one target, identified by a sessionId that Chrome returns when a client attaches.
Uses, limits and pitfalls
- Uses: testing and debugging (network traffic, console output, device emulation, performance traces), scraping and document generation (screenshots and PDFs), and giving AI browser agents control of a browser.
- Browser support: CDP is mainly for Chromium-based browsers. Cross-browser automation needs WebDriver or WebDriver BiDi. Playwright's connectOverCDP works only with Chromium and offers less than its normal connection.
- Versions: support varies, and newer or experimental commands may be missing from older Chrome. The protocol a running browser supports is listed at /json/protocol.
- State: navigation can destroy JavaScript execution contexts and invalidate old remote object IDs, and new tabs, frames and workers create targets that may need attaching to and cleaning up.
A short troubleshooting table covers three cases. A page command that fails on the browser connection needs the page target's session ID. A load event that never arrives usually means Page events should be enabled and listened for before navigating, with a timeout. A method that isn't found calls for a check of the domain, target type and protocol version.
When to use CDP directly
The article recommends starting with Playwright or Puppeteer for tests, scraping, forms and screenshots. A library's CDPSession is for Chromium commands or events the normal API doesn't expose. Direct WebSocket commands suit learning CDP or building protocol tooling, where you manage response IDs, timeouts, errors and target lifetimes. Chrome's Protocol Monitor can help inspect messages first.
Worked example
The walkthrough starts headless Chrome with --remote-debugging-port=9222 and a separate --user-data-dir. It then uses Node's interactive console to fetch the target list from /json/list, pick a page and open a WebSocket to its debugger URL. After that it enables Page events, navigates and reads the page title. It was tested on macOS with Chrome 153.0.8010.53 and Node.js 22.22.3. The article warns against exposing the debugging port to the public internet, since anyone who connects could control Chrome.