browser-debugger-cli (bdg)
browser-debugger-cli
The bdg CLI keeps Chrome open in the background and gives agents network, console, cookies and styles as short commands.
- 185 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Commands read cookies, including HttpOnly, and Authorization headers, and `bdg eval` runs JavaScript on the open page. In a session with a real login the agent sees tokens.
- Attaching to everyday Chrome exposes profile tabs. Start with a separate session on localhost.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/browser-debugger-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Commands read cookies, including HttpOnly, and Authorization headers, and `bdg eval` runs JavaScript on the open page. In a session with a real login the agent sees tokens.
- Attaching to everyday Chrome exposes profile tabs. Start with a separate session on localhost.
This is third-party code. Review the repository files before installing.
What it does
bdg starts Chrome in the background and takes commands one at a time: open a page, click, fill a field, then read network requests, console errors, cookies, styles and element layout. Output is compact and pipes into `jq`, so an agent spends few tokens. The agent needs no prewritten script: it takes a step, reads what the browser reports and picks the next one. For everything else `bdg cdp` sends any Chrome DevTools Protocol method. The `bdg install-skill` command installs a skill that describes the working loop for Claude Code, Codex and Gemini CLI.
Who it is for. Web developers who ask Claude Code or Codex to find why a localhost page misbehaves and want network and console answers.
Good fit when
- A cart button stays silent and the agent must see the 500 response and the console error.
- A form needs testing: fill fields, submit and read the confirmation.
- A page breaks on a narrow screen and the agent measures element layout under mobile viewport emulation.
- Text contrast is audited page-wide, with the weakest spots listed first.
- A login session is already open in the browser and its cookies must go to `curl` for an API check.
Not a fit when
- Long test suites with reports and CI fit Playwright or Puppeteer better.
- The workflow is built around MCP servers or needs Lighthouse audits out of the box: the README points to Chrome DevTools MCP.
- The page must run in Firefox or Safari, since bdg speaks only the Chrome DevTools Protocol.
Example request
Open localhost:3000 with bdg, click the add-to-cart button and show which request went out and what the console printed.Limitations
Requires Node.js 22.12 or newer and a Chromium-based browser: Chrome, Chromium or Edge. Runs on macOS, Linux and Windows via WSL, while native PowerShell and Git Bash are not supported yet. Firefox and Safari do not work. Attaching to your everyday Chrome requires enabling remote debugging at `chrome://inspect/#remote-debugging`, and Chrome asks permission for each connection. Local servers with a self-signed certificate need the `--chrome-flags="--ignore-certificate-errors"` flag. The README comparison with Chrome DevTools MCP rests on a single run from November 2025, and both tools have changed since.
How to disable. End the session with `bdg stop` and remove the package with `npm uninstall -g browser-debugger-cli`. The skill lives in `~/.claude/skills` and `~/.agents/skills`; delete its `bdg` folder by hand.
FAQ
How do I install bdg for Claude Code?
Run `npm install -g browser-debugger-cli`, then `bdg install-skill` (the `--claude` flag installs for Claude Code only). Start a new agent session afterwards: the skill loads when a task needs a browser, or on demand with `/bdg`.
Does bdg need an MCP server?
No. Each bdg command is a plain shell process that the agent calls through the shell. The agent reads the help for every command itself: `bdg --help --json`.
How do I see requests and console errors?
`bdg network list --preset errors` shows failed requests and `bdg console` prints console messages. Data stays available while the session is open.
Can bdg attach to a Chrome that is already open?
Yes. Enable remote debugging at `chrome://inspect/#remote-debugging` and run `bdg attach`. The command lists tabs and attaches to the chosen one without reloading it.
How does bdg differ from Chrome DevTools MCP?
bdg returns browser data through shell commands with no MCP server. The README recommends Chrome DevTools MCP when the workflow is built around MCP or Lighthouse audits, performance traces and heap analysis are needed.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill for Amp, Claude Code and Cursor: the agent drives your live Chrome with its open tabs and signed-in accounts through a single debugging toggle
A CLI, skill and MCP server for driving Chrome with short Puppeteer scripts, with tabs that keep state between calls
A CLI and skill for driving Chrome from an agent: page snapshots, clicks, console, network and audits in compact output
A Rust binary with no MCP server: an agent drives your open Chrome or Edge, and tabs are pinned with target labels.
An agent drives your real logged-in Chrome: a CLI, MCP and an extension with a separate tab group per session
A native Rust CLI for Chrome over CDP: 90-plus commands, a 50-tool MCP server and a persistent daemon with page snapshots.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| browser-debugger-cli (bdg) (this card) | no | 185 | ||
| Chrome DevTools MCP | yes | not required | 55,199 | a DevTools MCP server with Lighthouse audits and heap analysis; bdg exposes similar data through plain shell commands |
| agent-browser-cli | no | 649 | a general CLI for agent browser control; bdg focuses on debugging: network, console, CSS cascade and raw CDP |
README in short
The author positions bdg as a companion for debugging a live page step by step. The README gives debugging and automation examples, a table of areas (page, interaction, inspection, telemetry, profiling, sessions) and a section on when Playwright or Chrome DevTools MCP fits better.