From db17075b3988aa583b13da1bc102924a40e285d5 Mon Sep 17 00:00:00 2001
From: Alex Qiu <alexander@browserbase.com>
Date: Thu, 9 Jul 2026 11:51:54 -0700
Subject: [PATCH] Resolve CDP tailing docs conflicts

---
 skills/browser/REFERENCE.md | 55 +++++++++++++++++++++++++++++++++++++
 skills/browser/SKILL.md     | 14 ++++++++++
 2 files changed, 69 insertions(+)

diff --git a/skills/browser/REFERENCE.md b/skills/browser/REFERENCE.md
index 9c23a2a8..6aed2ba5 100644
--- a/skills/browser/REFERENCE.md
+++ b/skills/browser/REFERENCE.md
@@ -393,6 +393,61 @@ browse network clear
 
 ---
 
+### CDP Event Tailing
+
+#### `cdp <url|port>`
+
+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 <domains...>` | 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 <session-id>` to get the `wsUrl`, then pass it to `browse cdp`:
+
+```bash
+# Get the debug WebSocket URL
+bb sessions debug <session-id>
+# Copy the wsUrl field and pass it to browse cdp
+browse cdp wss://connect.browserbase.com/debug/<session-id>/devtools/browser/...
+```
+
+---
+
 ## Configuration
 
 ### Common Flags
diff --git a/skills/browser/SKILL.md b/skills/browser/SKILL.md
index 72f137e5..b2518216 100644
--- a/skills/browser/SKILL.md
+++ b/skills/browser/SKILL.md
@@ -94,6 +94,20 @@ browse is checked <selector>             # Check if element is checked
 browse wait <type> [arg]                 # Wait for: load, selector, timeout
 ```
 
+### CDP event tailing
+```bash
+browse cdp <url|port>                    # 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 <url> --domain Network        # Only Network events
+browse cdp <url> --domain Network --domain Console  # Multiple domains
+browse cdp <url> --pretty                # Human-readable output
+browse cdp <url> > events.jsonl          # Pipe to file
+browse cdp <url> | 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