Snowflake-Labs/browser-debugger-cli

Snowflake-Labs/browser-debugger-cli

Description: CLI tool for agents to quickly access browser telemetry (DOM, network, console) via Chrome DevTools Protocol.

Language: TypeScript

License: MIT

Stars: 1

Forks: 0

Open issues: 0

Created: 2025-12-08T14:41:56Z

Pushed: 2026-02-27T07:47:16Z

Default branch: main

Fork: yes

Parent repository: szymdzum/browser-debugger-cli

Archived: no

README:

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 →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)

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](https://github.com/szymdzum/browser-debugger-cli/wiki) - Guides, command reference, recipes

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

Design Principles

This tool implements [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md):

• 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