Add browser-trace skill

[derekmeegan]

Summary

A new skill that captures a full DevTools-protocol trace alongside any browser automation, then bisects the stream into per-page searchable buckets. Drop in next to the existing browser skill — it is purely observational, never drives the page, and works with browse, Stagehand, Playwright, or anything else speaking CDP.

What's in the box

skills/browser-trace/:

• SKILL.md — when to use it, local + Browserbase quickstarts, filesystem layout, summary shape, drill-down via query.mjs
• REFERENCE.md — full bisect map, per-page drill-down recipes, Browserbase platform pairing, troubleshooting matrix
• EXAMPLES.md — five end-to-end debug scenarios (failing form submit, third-party network audit, page hang, prod JS-exception repro, attaching to an in-flight Browserbase session)
• scripts/ — Node ESM, no third-party deps (so no npm install step):
  • start-capture.mjs / stop-capture.mjs / snapshot-loop.mjs — lifecycle of a trace run
  • bisect-cdp.mjs — splits raw.ndjson into session-wide buckets + per-page subdirs and writes a structured summary.json
  • query.mjs — drill-down helper: list, page <pid> [bucket], errors, hosts, host <h>, timeline
  • bb-capture.mjs / bb-finalize.mjs — Browserbase wrappers that handle --keep-alive, connectUrl resolution, manifest stamping (session id, region, live debugger URL), and post-run artifact pulls (bb sessions get, bb sessions logs, bb sessions downloads get)
• lib.mjs — shared helpers (run dir, JSONL I/O, BUCKETS table, isTopNav)

Filesystem layout produced

.o11y/<run-id>/
  manifest.json                                browserbase block on remote runs
  index.jsonl                                  ts → screenshot/dom/url joins
  cdp/
    raw.ndjson                                 full firehose, NDJSON
    summary.json                               sessionId, duration, totalEvents, pages[]
    network/, console/, page/, runtime/, log/, target/, dom/
    pages/<pid>/                               per-page slices, indexed by top-level frameNavigated
      url.txt, summary.json, raw.jsonl
      network/, console/, page/, ...
  screenshots/<ts>.png
  dom/<ts>.html
  browserbase/                                 written by bb-finalize on remote runs
    session.json, logs.json, downloads.zip

summary.json is the entry point for any analysis:

{
  "sessionId": "45f28023-…",
  "duration": { "startMs": 1777312533000, "endMs": 1777312609000, "totalMs": 76000 },
  "totalEvents": 420,
  "pages": [
    {
      "pageId": 0,
      "url": "https://example.com/",
      "startMs": 1777312533000, "endMs": 1777312538886, "durationMs": 5886,
      "eventCount": 60,
      "domains": {
        "Network": { "count": 18, "errors": 1 },
        "Console": { "count": 2 },
        "Page":    { "count": 24 },
        "Runtime": { "count": 13 }
      },
      "network": { "requests": 4, "failed": 1, "byType": { "Document": 2, "Script": 1, "Other": 1 } }
    }
  ]
}

Drilling in

node scripts/query.mjs my-run list                    # one-line table of pages
node scripts/query.mjs my-run page 1                  # full summary for page 1
node scripts/query.mjs my-run page 1 network/failed   # cat that bucket
node scripts/query.mjs my-run errors                  # all errors across pages, attributed by pid
node scripts/query.mjs my-run hosts                   # top hosts by request count
node scripts/query.mjs my-run host api.example.com    # all requests/responses for one host

Why "trace" and not "observability"

browser-trace reads more cleanly as a slash command, accurately describes the artifact (a time-ordered recording of CDP events plus aligned screenshots/DOM), and pairs naturally with future research-loop skills (e.g. autobrowse) that can use the per-page summary as their structured "what just happened" data.

Compatibility note

The CDP firehose is sourced via browse cdp <target>, which currently ships under the alpha tag of @browserbasehq/browse-cli (@browserbasehq/browse-cli@alpha, since browserbase/stagehand#1905). Lifecycle events (Page.lifecycleEvent) specifically require browserbase/stagehand#2056. The skill's compatibility: field calls this out, and bisect/query degrade gracefully on older builds.

Marketplace + README

• marketplace.json registers a new browser-trace plugin pointing at ./skills/browser-trace (mirrors the browserbase-cli pattern — companion skill, own plugin, can be installed independently).
• README.md skills table gets a new row, placed in the observability cluster between site-debugger and bb-usage.

How it was built

Dogfooded end-to-end against:

• Local Chrome at localhost:9222
• A live Browserbase session via bb sessions create --keep-alive + bb-capture.mjs <session-id>

Each iteration ran the full pipeline (capture → automation → stop → bisect → query) and surfaced bugs (CDP timestamp clock-mixing, race on session.json after --release, partial DOM-dump cleanup) that were fixed before submission.

Test plan

• jq -e . .claude-plugin/marketplace.json — JSON validates
• npx skills add browserbase/skills lists the new plugin
• On Claude Code: /plugin install browser-trace@browserbase works
• Run the local quickstart in SKILL.md against any debuggable Chrome — capture, bisect, query.mjs list produces the page table
• Run the Browserbase quickstart with BROWSERBASE_API_KEY set — bb-capture.mjs --new stamps the manifest and prints the live debugger URL; bb-finalize.mjs --release writes session.json with status: COMPLETED

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new tracing skill that spawns/kills background processes, writes artifacts to disk, and can create/release Browserbase sessions via bb, so incorrect usage could leak processes or impact active sessions. Existing skills are unchanged aside from marketplace/README registration.

Overview
Introduces a new browser-trace skill that records a read-only CDP “firehose” alongside screenshots and DOM snapshots, then post-processes the run into searchable per-domain and per-page JSONL buckets plus a cdp/summary.json rollup.

Adds Node (ESM) helper scripts to start/stop captures, bisect raw.ndjson into the output tree, query runs (list, page, errors, hosts, timeline), and optionally integrate with Browserbase via bb to create/attach sessions, stamp manifests with session metadata, fetch artifacts, and optionally release sessions.

Registers the new plugin in .claude-plugin/marketplace.json and documents it in README.md, with full reference and example playbooks under skills/browser-trace/.

^{Reviewed by Cursor Bugbot for commit 53fe4fb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4f28fb7. Configure here.}