bdg

bdg (Browser Debugger CLI) is a high-performance, token-efficient command-line interface that allows AI agents and developers to interact with web browsers via the Chrome DevTools Protocol (CDP). Unlike heavy frameworks like Puppeteer or Playwright, bdg maintains a persistent session, allowing for sequential, stateful automation tasks without the overhead of framework initialization. It is specifically optimized for agents requiring granular control, such as scraping dynamic SPA content, managing network traffic, or executing JavaScript in isolated contexts.

• Full Access to CDP: Connects to over 60 CDP domains and 600+ methods, including Page, Network, Runtime, DOM, and Emulation domains.

• Agent-Centric Design: Features self-discovery commands like --list, --search, and --describe to help agents navigate the protocol schema autonomously without needing external documentation.

• Persistent Sessions: Operates in a stateful mode where Chrome instances are kept alive, perfect for HMR-based development environments or long-running multi-step automation workflows.

• Token-Efficient Interaction: Uses selective DOM querying and semantic data extraction rather than dumping entire accessibility trees, minimizing context window usage for LLMs.

• Unix-Philosophy Composable: Designed to work seamlessly with shell pipelines, jq for JSON processing, and standard environment variables for custom Chrome flags.

• Robust Error Handling: Provides semantic exit codes and descriptive error messages to facilitate self-correction and automated recovery during agent-driven sessions.

• Use for: Web scraping of dynamic JavaScript-heavy sites, automating login flows, testing UI interactions, debugging network requests, and performing automated visual regression checks using targeted element screenshots.

• Inputs: Accepts URLs, CSS selectors, JS expressions, and standard CDP method parameters in JSON format.

• Outputs: Returns structured JSON data, command status indicators, and screen captures for verification.

• Operational Constraints: Requires Chrome or a Chromium-based browser. Designed for Linux/macOS/WSL environments. Sessions are persistent, so users must explicitly manage lifecycles using the stop command to prevent zombie processes.