browser-trace

Capture a full DevTools-protocol trace of any browser automation — CDP firehose, screenshots, and DOM dumps — then bisect the stream into per-page searchable buckets. Use when the user wants to debug a failed run, audit network/console/DOM activity, attach a trace to an in-progress session, or feed structured per-page summaries back into an agent loop so its next iteration learns from the last one.

3,541stars226forksUpdated 6/10/2026

Developer Tools #debugging #cdp #tracing #nodejs #browser-automation #javascript

Security Assessment

Low Risk(70/100)

Detected risks:

Secret Exposure([EXAMPLES.md] API_KEY=, [SKILL.md] API_KEY=)

Security Score70/100

About browser-trace

The `browser-trace` skill provides a robust mechanism to capture comprehensive traces from any browser automation session. It attaches a second, read-only Chrome DevTools Protocol (CDP) client to an existing browser session, allowing it to monitor the full DevTools event stream without interfering with the main automation. By collecting CDP events, periodic screenshots, and DOM snapshots, the skill generates a complete record of browser activity, which is then organized into searchable, per-page directories. This approach is particularly useful for diagnosing failures, auditing network or console behavior, and examining DOM changes over time, all without modifying the primary automation flow.

Key capabilities of `browser-trace` include streaming every CDP event to NDJSON files (the Firehose), sampling screenshots and HTML snapshots at configurable intervals (the Sampler), and bisecting the recorded events into per-method and per-page buckets for easy analysis (the Bisector). The skill operates entirely with Node.js (version 18 or higher) and leverages the `browse` CLI for CDP interactions. It supports both local Chrome instances and remote Browserbase sessions, enabling flexible deployment scenarios. The outputs are compatible with standard Bash tools and JSON querying utilities like `jq`, making it straightforward to analyze or feed the captured data back into automated workflows.

This skill is targeted at users who need detailed observability of browser automation, including QA engineers, developers debugging complex web interactions, and automation architects analyzing multi-step workflows. It is ideal when users need to attach tracing mid-run, investigate intermittent failures, or generate structured summaries of page interactions for downstream processing. It complements other browser-driving skills by focusing exclusively on observation rather than automation, making it a valuable addition to debugging and monitoring toolkits.

FAQ

Can I use `browser-trace` to control or interact with the browser?

No, `browser-trace` is strictly a read-only observer. It attaches a secondary CDP client to monitor events, take screenshots, and capture DOM snapshots without sending any commands to manipulate the page.

What are the system requirements for using this skill?

It requires Node.js 18 or higher, the `browse` CLI installed globally (`npm install -g browse`) with the `cdp` subcommand available, and optionally `jq` for querying bisected JSONL files. For Browserbase remote sessions, a valid `BROWSERBASE_API_KEY` is also required.

Can I attach the tracer to a running browser session?

Yes, the skill is designed to attach to an in-progress automation session without restarting it, allowing you to capture traces mid-flight.

How is the captured data organized?

The tracer stores raw CDP events in `raw.ndjson`, while the bisector processes these into per-CDP-method and per-page JSONL files, using `Page.frameNavigated` events to separate page boundaries.

Do I need to install any npm packages for the skill scripts themselves?

No, the skill scripts rely only on the Node standard library. No additional `npm install` is needed beyond installing the `browse` CLI if not already present.