Skip to main content
The browser-trace skill records what happens during a browser run so your agent can diagnose failed requests, JavaScript errors, or unexpected navigation. It adds a separate Chrome DevTools Protocol (CDP) client alongside your automation and organizes events by page. The tracer observes the browser. Your Browse CLI, Stagehand, or Playwright automation still drives it.

​
Install

You need Node.js 18+ for the trace scripts and the Browse CLI with browse cdp support. Remote captures also need BROWSERBASE_API_KEY in your environment.
The trace scripts use Node.js built-in modules and don’t need a separate dependency install.

​
Capture a run

Give your agent a URL and the steps that reproduce the issue:
Your agent uses bb-capture.mjs --new to create a keep-alive session and start the tracer. After the run, it stops capture, runs bisect-cdp.mjs to group the events, and uses bb-finalize.mjs --release to collect platform artifacts and release the session. You can also ask it to attach to an existing session by ID. For a session that another process owns, finalize without --release so that automation can continue. Always stop the capture, including after a failed run.

​
Read the results

The skill writes artifacts under .o11y/<run-id>/: Ask your agent to start with the summary, then narrow its investigation to the failing page and timestamp. Empty platform logs don’t mean the run had no activity; inspect the CDP events.

​
Capture limits

An idle browser produces few events. If the trace looks empty, confirm that your automation attached to the same session and performed the expected actions. If the remote session ended, start a new capture and check its timeout. The CDP event stream doesn’t include response bodies. For API discovery, pair the trace with browse network on and follow the Browser to API guide.

​
Further reading

Browser to API

Turn captured traffic into an OpenAPI document.

Skill source

View capture commands, query helpers, and debugging examples.