bdg Browser Debugger
Drive Chrome step by step from the terminal and inspect the DOM, network, console, and page state.
- Source repo
- szymdzum/browser-debugger-cli
- Stars
- ★ 177
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A frontend developer investigating an unresponsive button can click it and inspect the resulting request, HTTP error, and console messages.
- Not a fit if
- Teams that need Firefox or Safari support
- Users who need native PowerShell or Git Bash
- Teams building long scripted test suites
- Source review
- 68/100 · Some gaps 1 safety controls not found
What does this agent do, and when should you use it?
bdg is a Node.js CLI that keeps a Chromium browser session open in the background and lets users interact through separate shell commands. It provides commands for navigation, clicks, form filling, waiting for elements, inspecting DOM and styles, and reading network requests, cookies, and console messages. For DevTools features without a dedicated command, bdg cdp calls the Chrome DevTools Protocol directly. Output is compact, with --json available for machine processing or filtering through jq. It is built for coding agents such as Claude Code, Codex, and Gemini CLI, and can also be used directly from a developer's terminal; it requires Node.js 22.12+ and Chrome, Chromium, or Microsoft Edge.
After installing browser-debugger-cli, run bdg <URL> to start a browser session, then use bdg dom commands to navigate, click, fill, wait, and inspect elements. Use bdg network to view requests, headers, cookies, and HAR; bdg console to read page messages; and bdg eval to execute JavaScript. bdg cdp searches, describes, or invokes CDP methods, while the CLI also provides machine-readable help, JSON output, and actionable error suggestions. Sessions can run side by side under different names or attach to a browser with remote debugging enabled.
- A frontend developer investigating an unresponsive button can click it and inspect the resulting request, HTTP error, and console messages.
- A coding agent can fill a form and read the page response step by step without a Playwright script written in advance.
- A developer can inspect CSS rules, element layout, the accessibility tree, or page contrast issues.
- A tester can examine failed requests, HAR, cookies, or authorization headers to investigate login and API problems.
- A performance engineer can use CDP to read metrics, enable CPU throttling, or run heap and CPU profiling.
How do you install or deploy this agent?
Requires Node.js 22.12+ and Chrome, Chromium, or Microsoft Edge. Install globally with npm:
npm install -g browser-debugger-cliTo install its skill for agents such as Claude Code, Codex, and Gemini CLI:
bdg install-skillFor Claude Code only:
bdg install-skill --claudeStart a new agent session after installing the skill. The documentation does not require an API key.
How do you use this agent?
Start a page and leave the browser session running:
bdg localhost:3000Then interact and inspect results step by step:
bdg dom fill 'input[name="q"]' "shoes"
bdg dom click 'button:has-text("Search")'
bdg dom wait "#result" --visible
bdg network list --preset errors
bdg console
bdg stopUse bdg cdp <method-name> to call a CDP method, for example bdg cdp Network.getCookies. Add --json for JSON output.
What are this agent's strengths and limitations?
- Commands drive a persistent browser session one step at a time, so an agent can adapt to each returned page result.
bdg cdpcan call the Chrome DevTools Protocol for DevTools capabilities beyond the built-in commands.- Includes inspection for network, console, cookies, HAR, DOM, CSS, accessibility, and performance.
- Help, command descriptions, method search, and error suggestions are designed for machine-driven agent use.
- Requires Node.js 22.12+ and a Chromium-based browser; Firefox and Safari are unsupported.
- Native PowerShell and Git Bash are not supported; Windows users need WSL.
- Playwright or Puppeteer is a better fit for long scripted test suites.
- The README's benchmark is a single five-task run from November 2025, and it notes that both tools have changed since.
How does this agent compare with similar options?
Compared with Playwright and Puppeteer, bdg is aimed at step-by-step interaction with and debugging of live pages; the README points to those tools for long scripted test suites. Compared with Chrome DevTools MCP, bdg runs as CLI commands and does not require MCP; the README cites existing MCP setups and Lighthouse audits, performance trace insights, and heap snapshot analysis as reasons to choose MCP. The reported benchmark was one five-task run in November 2025, not a general current performance claim.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| bdg Browser Debugger This agent | 68 · Some gaps | CLIFree | ★ 177 | today | TypeScript | Codex · Claude Code |
| Chrome DevTools MCP | 79 · Some gaps | MCP serverFree | ★ 54k | today | TypeScript | Codex · Claude Code |
| JS Reverse MCP | 82 · Good | MCP serverFree | ★ 3k | 1mo ago | TypeScript | Codex · Claude Code |
| browser-control | 72 · Some gaps | CLIFree | ★ 3.2k | 1mo ago | Rust | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The CLI exposes page interaction, arbitrary JavaScript eval, and raw CDP, and can read Authorization headers, HttpOnly cookies, and local storage tokens. The materials show examples extracting and forwarding this sensitive data but do not describe redaction, access controls, or safeguards, so sensitive data handling scores 0 and least privilege and external effects score 1. The materials do not describe confirmation before high impact actions, so user confirmation scores 1. A session can be ended with stop and isolated session directories can be used, but page actions have limited rollback, so rollback scores 1. Concrete examples describe command output, JSON, and data use, supporting a 2 for data flow transparency. The workflow includes npm audit, but the audit does not block merging or publishing, so dependency security scores 2. package.json names an author and repository, but the supplied materials do not verify publisher identity, so source attribution scores 1.
The README says screenshots are not needed, while its feature table lists screenshots, which is an inconsistency; self consistency scores 1. Node.js 22.12+ and Chromium requirements, installation steps, and supported environments are clear; locked dependency installation and a build flow are also described, so dependency availability scores 2. The README gives concrete errors for a typo and an invalid CDP method, with suggestions and an exit code, so failure messages score 3.
The documentation explicitly targets coding agents and terminal developers and covers debugging, interaction, telemetry, accessibility, and performance scenarios, scoring 3. It documents Firefox, Safari, native PowerShell, and Git Bash limitations, and when Playwright or MCP may be preferable; however, it does not fully explain the boundaries and risks of raw CDP and eval, so capability boundaries score 2. Skill installation and command help guide agent use, but the description of when the skill loads is brief, so trigger precision scores 2. Node, browser, platform, existing browser connection, and multiple session setup are described concretely, scoring 3 for environment fit.
The README is organized by scenario, quick start, features, installation, limitations, and contribution, with links to command reference and topic guides, scoring 3 for information architecture. Installation steps, requirements, browser configuration, and unsupported platforms are specific, scoring 3. The relationship between bdg and browser-debugger-cli is clear, though the materials use several terms such as Agent skill, CLI, and MCP, so naming stability scores 2. Command examples, help invocation, error handling, and common use cases are extensive, and FAQ style limitations are concrete, scoring 3 for examples and FAQ and 3 for known limitations. The repository contains the full MIT license, scoring 3. package.json gives version 0.18.0, and the release workflow requires a matching tag and a changelog update before release, but no changelog content is included in the supplied materials, so versioning and changelog score 2. Contribution channels and a release process exist, but maintenance responsibility is represented mainly by author metadata and an invitation to contribute, without a clear maintenance commitment or support period, scoring 2.
Short commands, compact output, JSON, jq pipelines, and agent oriented help and error suggestions are supported by concrete examples, scoring 3 for output usability. Stepwise browser control without a prewritten script and access to DevTools capabilities through CDP show a clear benefit for agent workflows, scoring 3 for marginal value. The installation and usage path is clear, but the project requires a recent Node version and Chromium, and advanced capabilities require careful handling of sensitive data, so cost benefit scores 2.
Commands, flags, installation requirements, and some error behavior have traceable documentation, including a CLI reference; some performance and benchmark claims are self reported, so claim traceability scores 2. package.json, CI, and release workflows separately describe version, build, quality checks, and audit procedures, corroborating that these processes exist, but the supplied materials cannot establish that they passed on this revision, so cross source corroboration scores 2. The documentation qualifies benchmark timing and scope and notes changes in MCP capabilities, and distinguishes supported platforms from limitations; some effectiveness claims remain project assertions, so fact and inference separation scores 2.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- The tool can access browser tokens, cookies, and authorization headers, and supports arbitrary eval and raw CDP. Confirm that the target browser session and its sensitive data are appropriate before use.
- The README is inconsistent about screenshot support. The benchmark covers one comparison of five tasks, and the documentation says the tools have since changed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
v0.20.0: the last 0.x release The last 0.x release. bdg 1.0 renames a set of commands and flags (#465). In 0.20.0 every old spelling still works, prints one Warning: line on stderr (in --json: an entry in the envelope's warnings array) and is hidden from help; in 1.0 each one stops working and exits 81 naming its replacement. Switch scripts and notes now; the warnings name the new spelling. | Old | Use instead | |---|---| | bdg tail | bdg peek --follow | | bdg details network <id> / bdg details console <n> | bdg network details <id> / bdg console details <n> | …View on GitHub ↗ -
Release notes excerpt
bdg 0.19.0 makes interrupting a slow start reliable and fixes HAR body sizes. Action results get better at telling what *you* changed from what the page changes on its own. Behaviour changes (no breaking changes) - A start you interrupt now force-kills its Chrome after 500 ms (#804, #801). This applies to Ctrl-C, SIGTERM or bdg stop while bdg <url> is still starting. bdg sends Browser.close, waits up to 500 ms, then kills Chrome's process group (SIGKILL). The command returns in well under a second (exit 130 or 143) and leaves no session. …View on GitHub ↗ -
Release notes excerpt
bdg v0.18.0 bdg can now attach to the Chrome you already have open (bdg attach), without reloading your tab. Action results are more honest about what happened (form submits, silent DOM changes, blocked submits, tracker noise removed), Ctrl-C now ends every command with a clear envelope or line, and the release workflow is hardened so no project code runs where the npm token exists. Highlights …View on GitHub ↗
FAQ
Do I need a paid model or API key to use it?
Which browsers can it drive?
Can I use an already logged-in browser session?
bdg attach can list and attach to tabs in a browser with remote debugging enabled without reloading the page; Chrome asks you to allow each connection.