bdg-browser-debug

name	bdg-browser-debug
description	Browser debugging and telemetry via Chrome DevTools Protocol. Use when testing the Astro dev server, inspecting network requests, debugging console errors, capturing screenshots, or interacting with DOM elements on localhost:4321.
allowed-tools	Bash, Read

bdg - Browser Debug Gateway

Browser telemetry via Chrome DevTools Protocol for testing the Astro dev server.

Quick Start

# Start session on Astro dev server
bdg http://localhost:4321/

# Check status
bdg status

# Preview collected data
bdg peek

# Stop and save session
bdg stop

Session Management

Command	Description
bdg http://localhost:4321/	Start session on dev server
bdg status	Show session status
bdg stop	Stop and save to ~/.bdg/session.json
bdg stop --kill-chrome	Stop and close Chrome
bdg cleanup	Clean stale sessions
bdg cleanup --aggressive	Force kill all Chrome instances

Data Inspection

Peek (non-destructive preview)

bdg peek                    # Summary of all data
bdg peek -n                 # Network requests only
bdg peek -c                 # Console messages only
bdg peek -d                 # DOM/A11y tree
bdg peek -f                 # Follow mode (like tail -f)
bdg peek --last 20          # Last 20 items
bdg peek -j                 # JSON output

Network

bdg network list            # List all requests
bdg network list --failed   # Failed requests only
bdg network list --type XHR # Filter by type
bdg network headers         # Main document headers
bdg network headers <id>    # Specific request headers
bdg network getCookies      # List cookies
bdg network har             # Export as HAR file

Console

bdg console -l              # List all messages
bdg console --level error   # Errors only
bdg console --level warning # Warnings only
bdg console -f              # Follow in real-time
bdg console --last 50       # Last 50 messages

Details

bdg details request <id>    # Full request details
bdg details console <id>    # Full console message

DOM Interaction

Inspection

bdg dom a11y                # Accessibility tree
bdg dom a11y "button"       # Search a11y tree
bdg dom query "nav a"       # CSS selector query
bdg dom get "header"        # Get element structure
bdg dom get "article" --raw # Get raw HTML

Actions

bdg dom click "button.submit"           # Click element
bdg dom fill "input[name=email]" "test" # Fill input
bdg dom submit "form"                   # Submit form
bdg dom pressKey "input" "Enter"        # Press key
bdg dom eval "document.title"           # Evaluate JS

Screenshots

bdg dom screenshot ./shot.png           # Full page
bdg dom screenshot ./el.png -s "header" # Element only

CDP Protocol Access

bdg cdp --list              # List 53 domains
bdg cdp --search cookie     # Search methods
bdg cdp --describe Network.getCookies  # Method details
bdg cdp Network.getCookies  # Execute CDP method

Common Workflows

Test page load performance

bdg http://localhost:4321/
# Browse the site...
bdg peek -n                 # Check network requests
bdg network list --failed   # Any failed requests?
bdg stop

Debug console errors

bdg http://localhost:4321/
bdg console --level error   # Check for errors
bdg console -f              # Monitor in real-time

Inspect accessibility

bdg http://localhost:4321/
bdg dom a11y                # Full a11y tree
bdg dom a11y "navigation"   # Find nav elements

Capture visual state

bdg http://localhost:4321/
bdg dom screenshot ./screenshots/home.png
bdg dom screenshot ./screenshots/header.png -s "header"

Options Reference

Flag	Description
-q, --quiet	Minimal output for AI agents
-j, --json	JSON output (most commands)
--headless	No visible browser window
-t, --timeout <s>	Auto-stop after N seconds
-p, --port <n>	Chrome debug port (default: 9222)
--debug	Verbose logging

Output Files

• Session data: ~/.bdg/session.json
• Chrome profile: ~/.bdg/chrome-profile/