Skip to content
Back to search

browser-debugger-cli

Let Claude Code and other coding agents drive and debug Chrome from the shell. DOM, network, console and raw CDP as short commands, no screenshots and no MCP needed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/szymdzum/browser-debugger-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/szymdzum/browser-debugger-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/szymdzum--browser-debugger-cli/badge.svg)](/listings/szymdzum--browser-debugger-cli)

HTML

<a href="/listings/szymdzum--browser-debugger-cli"><img src="/api/listings/szymdzum--browser-debugger-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

bdg example.com                              # Start a session (the browser stays open)
bdg dom fill 'input[name="q"]' "shoes"       # Interact
bdg dom click 'button:has-text("Search")'
bdg dom wait "#result" --visible             # Wait for an element instead of sleeping
bdg network list --preset errors             # Failed requests
bdg console                                  # Console messages
bdg dom layout "#save"                       # Where is it? Visible? Covered?
bdg dom inspect "#save" --why color          # Which CSS rule sets the color
bdg dom audit contrast                       # Page-wide: text below WCAG AA, weakest first
bdg css search -- --brand                    # Where a token is set, in every stylesheet
bdg dom listeners "#save"                    # Which event listeners run
bdg page emulate --viewport 900x700          # Responsive check mid-session (--mobile for a phone)
bdg eval "document.title"                    # Run JavaScript (--frame for iframes)
bdg cdp Network.getCookies                   # Any CDP method
bdg stop                                     # End the session

Local dev servers with self-signed certificates: `bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"`. Need parallel sessions? `bdg example.com --session agent2`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 199 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # bdg - Browser Debugger CLI
  2. [![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
  3. [![CI](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml)
  4. [![Security](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml)
  5. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
  6. **Give your AI agent a real browser. And the DevTools to go with it.**
  7. 📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)**: [Getting Started](https://github.com/szymdzum/browser-debugger-cli/wiki/Getting-Started) · [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands) · [For AI Agents](https://github.com/szymdzum/browser-debugger-cli/wiki/For-AI-Agents) · [Recipes](https://github.com/szymdzum/browser-debugger-cli/wiki/Recipes) · [Quick Reference](https://github.com/szymdzum/browser-debugger-cli/wiki/Quick-Reference) · [Troubleshooting](https://github.com/szymdzum/browser-debugger-cli/wiki/Troubleshooting) · [CLI reference](docs/CLI_REFERENCE.md)
  8. bdg keeps a browser session open in the background and lets you drive it one shell command at a time. Click, fill, navigate, then read what actually happened: requests, console errors, layout and styles. It is built for coding agents like Claude Code, Codex and Gemini CLI, and it's just as handy in your own terminal. Every command is a plain process with compact output, so it pipes into `jq` and costs an agent few tokens.
  9. ```bash
  10. npm install -g browser-debugger-cli
  11. bdg localhost:3000
  12. ```
  13. ## Two ways to use it
  14. ### Debug a page: browser telemetry on demand
  15. ![The cart button does nothing; bdg shows the 500 response, the console error and the missing cookie](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-debug.gif)
  16. The cart button does nothing, and the page doesn't say why. Three commands later the agent knows: the click fired a POST that returned 500, the console says the `cart_id` cookie is missing, and the cookie jar confirms it. Network, console, cookies and the DOM are there whenever the agent asks, without a debugger UI.
  17. ### Automate without writing a script
  18. ![An agent fills a form, clicks Subscribe, reads the confirmation and inspects the button](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-automate.gif)
  19. No Playwright script written up front. The agent runs one command, reads what the browser reports back, and picks the next step from that: the click says which text appeared, `dom inspect` says what the button looks like. When the page does something unexpected, the agent adapts on the spot instead of failing at line 40 of a test.
  20. ## More examples
  21. ### Reuse the browser's login from the shell
  22. ```console
  23. $ bdg network cookies
  24. 1 Cookie:
  25. [0] tp_lax
  26. Value: cookie-marker-493
  27. Domain: localhost
  28. Path: /
  29. Expires: Session
  30. HttpOnly: No
  31. Secure: No
  32. SameSite: Lax
  33. $ bdg network headers 89565.2 --header authorization
  34. Request Headers:
  35. Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
  36. $ bdg eval "localStorage.getItem('access_token')"
  37. eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
  38. ```
  39. `HttpOnly` cookies are included, even though the page's own JavaScript can't read them. Log in once in the browser, then reuse the session from the shell:
  40. ```bash
  41. COOKIES=$(bdg network cookies --json | jq -r '[.data[] | "\(.name)=\(.value)"] | join("; ")')
  42. curl -H "Cookie: $COOKIES" localhost:3000/api/me
  43. ```
  44. ### The rest of DevTools
  45. ```console
  46. $ bdg dom a11y tree
  47. [RootWebArea] "My App" (focused)
  48. [Heading] "My App"
  49. [Button] "Sign in" (focusable)
  50. [Image] ← no accessible name
  51. $ bdg cdp Performance.enable
  52. $ bdg cdp Performance.getMetrics --json | jq '.data.result.metrics | from_entries'
  53. { "Nodes": 51, "LayoutDuration": 0.000115, "ScriptDuration": 0.000775, "JSHeapUsedSize": 772124, ... }
  54. $ bdg cdp Emulation.setCPUThrottlingRate --params '{"rate":4}' # Slow CPU
  55. $ bdg cdp Network.emulateNetworkConditions --params '{"offline":false,"latency":400,"downloadThroughput":50000,"uploadThroughput":20000}'
  56. ```
  57. Accessibility, performance metrics, CPU profiling, heap snapshots, code coverage, throttling, storage, service workers: everything Chrome DevTools can do, bdg can do too, through raw CDP. Can't find the method you need? `bdg cdp --search heap`.
  58. ## Agents learn it on their own
  59. No docs to paste into the prompt. The agent asks bdg:
  60. ```bash
  61. bdg --help --json # Every command, flag and exit code, plus "task → command" mappings
  62. bdg dom query --help --json # One command in full: option behaviors, defaults, examples
  63. bdg cdp --search cookie # 13 matching methods across all CDP domains, one line each
  64. bdg cdp Network.getCookies --describe # Parameters, return types, an example call
  65. ```
  66. And when it gets something wrong, bdg tells it what it meant:
  67. ```console
  68. $ bdg dom clik "a"
  69. Error: unknown command 'clik'
  70. Did you mean: click?
  71. $ bdg cdp Network.getCookie
  72. Error: Method 'Network.getCookie' not found
  73. Use: bdg cdp --search <keyword> (to search for methods)
  74. Did you mean:
  75. - Network.getCookies
  76. - Network.setCookie
  77. - Network.setCookies
  78. To send it as typed (a method newer than bdg's protocol): bdg cdp Network.getCookie --send-anyway
  79. ```
  80. With `--json` the same hint is a `suggestion` field. Each mistake exits with code 81 (invalid arguments), so the agent knows to fix the call rather than retry it. CDP method names are case-insensitive, and raw CDP calls point to the friendlier command when one exists. More in the [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md) principles bdg follows.
  81. ## Benchmark: CLI vs MCP
  82. The one measurement bdg has is from bdg 0.6.x (November 2025): five debugging tasks done by an AI agent with bdg and with the official [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) server, written up in [the full analysis](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md). Both tools have changed since, and [#428](https://github.com/szymdzum/browser-debugger-cli/issues/428) tracks the re-run.
  83. ## Use it with your agent
  84. bdg ships an agent skill that teaches the workflow: start once, act, read what changed, inspect without screenshots, check network and console.
  85. ```bash
  86. bdg install-skill # Claude Code (~/.claude/skills) + Codex, Gemini CLI, ... (~/.agents/skills)
  87. bdg install-skill --claude # Claude Code only
  88. ```
  89. Start a new agent session afterwards. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`. Re-run `bdg install-skill` after upgrading bdg.
  90. ## Quick start
  91. ```bash
  92. bdg example.com # Start a session (the browser stays open)
  93. bdg dom fill 'input[name="q"]' "shoes" # Interact
  94. bdg dom click 'button:has-text("Search")'
  95. bdg dom wait "#result" --visible # Wait for an element instead of sleeping
  96. bdg network list --preset errors # Failed requests
  97. bdg console # Console messages
  98. bdg dom layout "#save" # Where is it? Visible? Covered?
  99. bdg dom inspect "#save" --why color # Which CSS rule sets the color
  100. bdg dom audit contrast # Page-wide: text below WCAG AA, weakest first
  101. bdg css search -- --brand # Where a token is set, in every stylesheet
  102. bdg dom listeners "#save" # Which event listeners run
  103. bdg page emulate --viewport 900x700 # Responsive check mid-session (--mobile for a phone)
  104. bdg eval "document.title" # Run JavaScript (--frame for iframes)
  105. bdg cdp Network.getCookies # Any CDP method
  106. bdg stop # End the session
  107. ```
  108. Local dev servers with self-signed certificates: `bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"`. Need parallel sessions? `bdg example.com --session agent2`.
  109. ## What it covers
  110. | Area | Commands |
  111. |---|---|
  112. | **Page** | navigate, reload, back/forward, viewport, phone (`--mobile`) and color-scheme emulation |
  113. | **Interaction** | click (double, right), fill (React-compatible, file inputs), hover, keys, forms, scroll, wait; shadow DOM and iframes included |
  114. | **Inspection** | element styles with the CSS cascade, layout and visibility, page-wide audits (contrast, overflow, layers, animations, accessibility rules), stylesheet search, accessibility tree, event listeners, screenshots |
  115. | **Telemetry** | network requests and headers (incl. `Authorization`), HAR export, cookies (incl. `HttpOnly`), console messages, live `peek --follow` |
  116. | **Accessibility** | accessibility tree, semantic queries (`role:button name:Submit`), contrast checks |
  117. | **Performance** | metrics, CPU and heap profiling, tracing, CPU and network throttling (raw CDP) |
  118. | **Sessions** | several named sessions side by side, or attach to a browser you already have open (`bdg attach` lists its tabs and attaches to one without reloading it; `--chrome-ws-url` for a Chrome started with a debugging port) |
  119. | **Everything else** | raw CDP: `bdg cdp --list`, `--search`, `--describe` |
  120. The [CLI reference](docs/CLI_REFERENCE.md) documents every command. `bdg --help --json` gives agents the machine-readable version.
  121. ## Install
  122. **Requirements:** Node.js 22.12+ and a Chromium-based browser: Chrome, Chromium or Microsoft Edge.
  123. **Platforms:** macOS, Linux and Windows via WSL. Native PowerShell and Git Bash are not supported yet.
  124. **Browsers:** bdg launches Chrome by default. To use Edge, point `CHROME_PATH` at its binary, or attach to an Edge you started with `--remote-debugging-port`:
  125. ```bash
  126. CHROME_PATH="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" bdg example.com # macOS
  127. CHROME_PATH=/usr/bin/microsoft-edge bdg example.com # Linux
  128. bdg example.com --chrome-ws-url 9222 # Open a URL in a running browser
  129. ```
  130. Your everyday Chrome: enable remote debugging at `chrome://inspect/#remote-debugging`, then `bdg attach` lists its tabs and `bdg attach checkout` starts a session on one as it is (no reload; Chrome asks you to allow each connection). `--user-data-dir <dir>` picks another profile (Canary, Edge, Brave).
  131. Firefox and Safari are not supported: bdg speaks the Chrome DevTools Protocol, which they do not implement.
  132. ## When to use something else
  133. - **Playwright / Puppeteer**: long scripted test suites and a mature testing ecosystem.
  134. - **Chrome DevTools MCP**: if your setup is built around MCP servers, or you want its Lighthouse audits, performance trace insights and heap snapshot analysis tools.
  135. bdg is for when an agent or a developer needs to poke at a live page, step by step, and understand what is going on.
  136. ## Contributing
  137. [Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome. What counts as a breaking change, and which names, exit codes, `--json` fields and environment variables stay stable, is in the [stability policy](docs/CLI_REFERENCE.md#stability-policy); coming from 0.x, see [Migrating from 0.x to 1.0](docs/CLI_REFERENCE.md#migrating-from-0x-to-10). See the [Architecture](https://github.com/szymdzum/browser-debugger-cli/wiki/Architecture) page and `docs/` for contributor guides.
  138. ## License
  139. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.