Browser Debugger CLI

Chrome DevTools Protocol in your terminal. Opens a persistent connection to Chrome where commands can be executed sequentially via Unix pipes. Designed for AI agents and developers who want direct browser control without framework overhead.

Why bdg?

• Raw CDP access - All 644 protocol methods available directly
• Token efficient - No overhead from MCP tool definitions; progressive discovery loads only what's needed
• Self-correcting - Errors clearly exposed with semantic exit codes and suggestions
• Composable - Unix philosophy: pipes, jq, shell scripts work naturally

When to use alternatives:

• Puppeteer/Playwright: Complex multi-step scripts, mature testing ecosystem
• Chrome DevTools MCP: Already invested in MCP infrastructure

Built for agents: Self-discovery (--list, --search), semantic exit codes, structured errors, case-insensitive commands, token-efficient output.

Benchmark: CLI vs MCP for AI Agents

We benchmarked bdg against Chrome DevTools MCP Server on real developer debugging tasks.

Full benchmark analysis →

Key findings: CLI provided 33% better token efficiency through selective queries vs full accessibility tree dumps, plus capabilities MCP doesn't expose (memory profiling, HAR export, batch JS execution).

Install

npm install -g browser-debugger-cli@alpha

Platform Support:

• ✅ macOS and Linux
• ✅ Windows via WSL
• ❌ PowerShell/Git Bash (not yet)

Quick Start

bdg example.com                    # Start session
bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"  # Self-signed certs
bdg https://localhost:5173 --chrome-flags="--disable-web-security"       # Disable CORS
bdg cdp --search cookie            # Discover commands
bdg cdp Network.getCookies         # Run any CDP method
bdg dom query "button"             # High-level helpers
bdg stop                           # End session

Current State

Raw CDP access is complete. All 644 protocol methods (53 domains) work now. High-level wrappers (bdg dom, bdg network) are being added for common operations. See Commands for full reference.

Agent Discovery Pattern

# Agent explores what's possible (no docs needed)
bdg cdp --list                              # 53 domains
bdg cdp Network --list                      # 39 methods
bdg cdp Network.getCookies --describe       # Full schema + examples
bdg cdp Network.getCookies                  # Execute

# Search across all domains
bdg cdp --search screenshot                 # Find relevant methods
bdg cdp --search cookie                     # 14 results

Documentation

📖 Wiki - Guides, command reference, recipes

• Getting Started
• Commands
• For AI Agents
• Recipes
• Quick Reference
• Architecture
• Troubleshooting

Design Principles

This tool implements Agent-Friendly Tools:

• Self-documenting - Tools teach themselves via --list, --describe
• Semantic exit codes - Machine-parseable error handling
• Structured output - JSON by default, human-readable optional
• Progressive disclosure - Simple commands, deep capabilities

Contributing

Issues for bugs, Discussions for ideas. PRs welcome.

See docs/ for architecture and contributor guides.

License

MIT