diff --git a/skills/browser/REFERENCE.md b/skills/browser/REFERENCE.md index 71827a4..9af7936 100644 --- a/skills/browser/REFERENCE.md +++ b/skills/browser/REFERENCE.md @@ -381,6 +381,61 @@ browse network clear --- +### CDP Event Tailing + +#### `cdp ` + +Attach to any Chrome DevTools Protocol target and stream events as NDJSON (one JSON object per line). This command bypasses the daemon entirely — it opens a direct WebSocket connection and runs until interrupted. + +```bash +browse cdp 9222 # bare port — auto-discovers via /json/version +browse cdp ws://127.0.0.1:9222/devtools/browser/... # full WebSocket URL +browse cdp wss://connect.browserbase.com/debug/... # remote Browserbase debug URL +``` + +**Options:** + +| Flag | Description | +|------|-------------| +| `--domain ` | CDP domains to enable (repeatable). Default: Network, Console, Runtime, Log, Page | +| `--pretty` | Human-readable output instead of JSON. Auto-enabled for TTY | + +**Default domains:** Network, Console, Runtime, Log, Page. To capture only specific domains: + +```bash +browse cdp 9222 --domain Network # network events only +browse cdp 9222 --domain Network --domain Console # network + console +``` + +**Piping and filtering:** + +```bash +browse cdp 9222 > events.jsonl # save to file +browse cdp 9222 | jq '.method' # extract method names +browse cdp 9222 | jq 'select(.method == "Network.requestWillBeSent") | .params.request.url' +``` + +**Pretty output** shows compact one-line summaries: + +``` +[Target.attachedToTarget] [page] https://example.com +[Network.requestWillBeSent] GET https://example.com/api/data +[Network.responseReceived] 200 https://example.com/api/data +[Runtime.consoleAPICalled] [log] Hello world +[Page.frameNavigated] https://example.com/about +``` + +**With Browserbase sessions:** Use `bb sessions debug ` to get the `wsUrl`, then pass it to `browse cdp`: + +```bash +# Get the debug WebSocket URL +bb sessions debug +# Copy the wsUrl field and pass it to browse cdp +browse cdp wss://connect.browserbase.com/debug//devtools/browser/... +``` + +--- + ## Configuration ### Global Flags diff --git a/skills/browser/SKILL.md b/skills/browser/SKILL.md index 3c4e652..1f2a94b 100644 --- a/skills/browser/SKILL.md +++ b/skills/browser/SKILL.md @@ -89,6 +89,20 @@ browse is checked # Check if element is checked browse wait [arg] # Wait for: load, selector, timeout ``` +### CDP event tailing +```bash +browse cdp # Stream CDP events as NDJSON from any target +browse cdp 9222 # Attach to local Chrome on port 9222 +browse cdp ws://localhost:9222/devtools/browser/... # Full WebSocket URL +browse cdp --domain Network # Only Network events +browse cdp --domain Network --domain Console # Multiple domains +browse cdp --pretty # Human-readable output +browse cdp > events.jsonl # Pipe to file +browse cdp | jq '.method' # Filter with jq +``` + +The `cdp` command connects directly to any Chrome DevTools Protocol target and streams events. It does **not** use the daemon — it's a standalone, long-running process. Press Ctrl+C to stop. Default domains: Network, Console, Runtime, Log, Page. + ### Session management ```bash browse stop # Stop the browser daemon diff --git a/skills/browserbase-cli/REFERENCE.md b/skills/browserbase-cli/REFERENCE.md index d17393e..a1059ea 100644 --- a/skills/browserbase-cli/REFERENCE.md +++ b/skills/browserbase-cli/REFERENCE.md @@ -170,6 +170,41 @@ Returns structured results with titles, URLs, and optional metadata (author, pub Prefer the `fetch` skill to retrieve page content after finding URLs via search. Prefer the `browser` skill when you need to interact with pages. +## Debugging sessions + +### Get debug URLs + +```bash +bb sessions debug +``` + +Returns `wsUrl`, `debuggerUrl`, `debuggerFullscreenUrl`, and a list of open pages with their debugger URLs. The session must be running. + +### Tail CDP events + +Use the `wsUrl` from `bb sessions debug` with `browse cdp` to stream live Chrome DevTools Protocol events: + +```bash +# Get the wsUrl +bb sessions debug + +# Stream all events as NDJSON +browse cdp + +# Human-readable output +browse cdp --pretty + +# Filter to specific domains +browse cdp --domain Network +browse cdp --domain Network --domain Console + +# Pipe to file or jq +browse cdp > session-events.jsonl +browse cdp | jq 'select(.method | startswith("Network"))' +``` + +Requires `@browserbasehq/browse-cli` (`npm install -g @browserbasehq/browse-cli`). + ## Browse passthrough `bb browse ...` forwards arguments to the standalone `browse` binary (`@browserbasehq/browse-cli`). The examples below are `browse-cli` subcommands — they are not native `bb` commands: diff --git a/skills/browserbase-cli/SKILL.md b/skills/browserbase-cli/SKILL.md index cd476ad..e627746 100644 --- a/skills/browserbase-cli/SKILL.md +++ b/skills/browserbase-cli/SKILL.md @@ -56,6 +56,23 @@ Use this skill when the user wants to: - `bb browse ...` to forward to the standalone `browse` binary (requires `@browserbasehq/browse-cli`) - `bb skills install` to install Browserbase agent skills for Claude Code +## Debugging sessions with CDP + +Use `bb sessions debug` to get the debug WebSocket URL for a running session, then use `browse cdp` (from `@browserbasehq/browse-cli`) to stream live CDP events: + +```bash +# Get debug URLs for a running session +bb sessions debug + +# The output includes a wsUrl — pass it to browse cdp to tail CDP events +browse cdp +browse cdp --pretty # Human-readable output +browse cdp --domain Network # Only network events +browse cdp > events.jsonl # Save to file for analysis +``` + +This is useful for debugging automation scripts, inspecting network traffic, and monitoring console output from running sessions. + ## Common workflows ### Functions