Provides direct CDP access for navigation, DOM queries, screenshots, and network control in browser sessions.

Install

mkdir -p .claude/skills/bdg && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/13173" && unzip -o skill.zip -d .claude/skills/bdg && rm skill.zip

Installs to .claude/skills/bdg

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Use bdg CLI for browser automation via Chrome DevTools Protocol. Provides direct CDP access (60+ domains, 300+ methods) for DOM queries, navigation, screenshots, network control, and JavaScript execution. Use this skill when you need to automate browsers, scrape dynamic content, or interact with web pages programmatically.
324 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Start and stop browser sessions
  • →Take full-page, viewport, or element screenshots
  • →Fill forms and interact with DOM elements
  • →Inspect DOM elements and execute JavaScript
  • →Access Chrome DevTools Protocol directly
  • →Manage session cleanup and troubleshooting

How it works

The skill uses the `bdg` CLI to automate browser interactions via the Chrome DevTools Protocol, allowing for session management, DOM manipulation, screenshots, and direct CDP command execution.

Inputs & outputs

You give it
URL, CSS selectors, CDP commands, form data
You get back
Browser session status, screenshots, filled forms, DOM inspection results, CDP command output

When to use bdg

  • →Scrape dynamic content
  • →Take full-page screenshots
  • →Automate browser interaction
  • →Network traffic inspection

About this skill

bdg - Browser Automation CLI

Requires the bdg binary: npm i -g browser-debugger-cli (bdg --version to check).

Quick Start

The loop: start, look, act, read the reported effect, check errors. Screenshots only for visual proof.

bdg https://example.com --headless      # Start a session (Chrome + daemon); stays up until bdg stop
bdg dom query "button"                  # Find elements: [0], [1], ... (0-based); class="px-2 +4" = first class + 4 more (all in --json classes, [] when none, or dom get <index> --json domContext.classes)
                                         # Human output escapes " \ and newlines in values and cuts them at 40 chars (--json/--raw keep them whole); same-origin links show as paths (/register/), others with their scheme; an icon-only button shows its name: [2] <button class="icon"> "Open menu"
bdg dom inspect "button.primary"        # Box, layout, font, colors + contrast, without a screenshot
bdg dom fill "input[name='email']" "[email protected]"
bdg dom click "button[type='submit']"   # Prints what changed: navigation, new text, or no effect
bdg console --level error               # Anything thrown?
bdg console --follow --ndjson           # Tail console output: one JSON record per line ({type:"page",navigationId,url} per page, {type:"message",level,text,…} per message; `type` is the record kind, `level` the console type (error, warning, info, log, debug, …) that `console --json` gives as `messages[].type`); `--follow --json` prints the same records
bdg network list --preset errors        # 4xx/5xx of the current page (--page all: earlier pages too)
bdg stop                                # Only when completely done

On macOS bdg opens a Chrome window by default; pass --headless when running unattended (it is the default over SSH, in CI and on Linux without a display).

Sessions

bdg status                    # Current session (bdg status --verbose for diagnostics)
bdg peek                      # Preview collected requests and console messages (starts with Page: <url> — <title>; status and peek add ⚠ The page is still loading … waiting on: … until the page has finished loading (readyState not complete), JSON loading)
bdg sessions                  # All sessions, default and named
bdg <url> --session mobile --mobile --headless   # A second, named session (own Chrome)
bdg --session mobile eval "innerWidth"           # Every command takes --session <name> (or BDG_SESSION)
bdg <url> --viewport 1280x800 --color-scheme dark
bdg -q dom query "a"          # -q: minimal output, no "Next:" hints

Sessions run until bdg stop (no timeout). With an HMR dev server, start once and keep it running: the page updates itself, then re-run dom inspect / console.

Attach to a Tab As It Is

bdg attach                                    # List the page tabs of your Chrome: [0] title — url (0-based), then exit
bdg attach checkout                           # Session on the only tab whose URL/title contains "checkout"
bdg attach 2                                  # ... or by index from the list (a number is always an index)
bdg attach --user-data-dir <dir>              # Another Chromium profile (Canary, Edge, Brave)
bdg attach checkout --stop-after 600             # End the session by itself after 600 s
bdg attach checkout --chrome-ws-url 9222      # A Chrome started with --remote-debugging-port=9222 --user-data-dir=<dir>

Test-only: with BDG_ATTACH_REQUIRE_WS_URL=1 in the environment, attach without --chrome-ws-url or --user-data-dir exits 81 and never reads your Chrome's profile.

Without --chrome-ws-url, bdg reads DevToolsActivePort from Chrome stable's profile (or --user-data-dir): the user enables remote debugging at chrome://inspect/#remote-debugging and clicks Allow in Chrome's prompt (one prompt per command). No file or a stale one exits 83 (ask the user to enable it), prompt declined 82, unanswered after 30 s 102. The tab is never navigated or reloaded: its state stays, console messages and errors it logged earlier are replayed, earlier network requests are not available. No match exits 83 (with the tab list), several 81 (use an index). One connection to the browser; downloads of that tab are listed (saved where your Chrome saves them); bdg stop only detaches (tab and Chrome stay); page switch exits 81 (stop and attach to the other tab).

Keep a Login Across Sessions

bdg stop drops session cookies (most dev-server logins) and sessionStorage. Save the auth state once logged in, then start with it:

bdg state save /tmp/login.json                  # Cookies (session + HttpOnly), localStorage, sessionStorage of the page's origins
bdg stop && bdg <url>/dashboard --state /tmp/login.json   # Restored before the first load: still logged in
bdg --session other state load /tmp/login.json  # Into a running session (reloads; --no-reload to skip)

A state file over 50 MiB is refused (exit 81). The file holds secrets (written 0600, also over an existing file; keep it out of the repo). Output shows counts only. Mid-session state load restores storage only for origins the page has frames of; --state at start restores all. A missing file exits 83, a bad one 81.

Navigate the Session Page

bdg page navigate https://example.com/next   # Load a URL and wait for it
bdg page back                                # Also: page forward
bdg page reload
bdg page info                                # Current URL (with fragment) and title, read live

Tabs and Popups

An action that opens a tab or window says Opened: popup <url> (bdg page switch 1) (JSON opened). Switch to it, act there; a popup that closes itself (OAuth/SSO) returns the session to its opener and the action says Tab closed: …; now on tab 0: … (JSON tabClosed, switchedTo). If it closed on its own (a timer), the next command says so, and the first action after it exits 90 without running: check where you are, then run it again.

bdg page tabs                                # * marks the session tab, (opened by N)
bdg page switch 1                            # By 0-based index or part of the URL (url:8080 for digits)
bdg page close 1                             # Default: the session tab (moves to its opener)

Network and console follow the session tab from the switch on (console also lists what a tab logged before the first switch to it; network list notes the switch).

Actions Report What Changed

dom click, fill, submit, press-key, hover and scroll wait for the requests the action starts, then say what happened. Read this before reaching for a screenshot:

✓ Element Clicked
Page: navigated to https://app.test/secure (200)    # navigation (or "URL changed ... (same document)")
New text: "Your password is invalid!" (div#flash)   # alert/status/aria-live messages that appeared (after a navigation, a flash-like class/id counts only in the first viewport)
Also changing: aside#t "tick 51" (changing before the action)  # a region the page kept updating on its own before the action (ticker, poll); not the action's text, not "still changing"
⚠ Element Clicked (nothing observed within about half a second ...)  # nothing seen yet - wrong element, broken handler, or a later result: look with dom query/peek
Form submitted (cancelled by the page): form#login  # the form fired submit; the page handled it in script (not "nothing happened")
Button changed: disabled, "Sending…"                # the pressed button's own change (a request in flight, or stuck)
Activated:     button#plain (the key clicked it)    # press-key Enter/Space clicked the button it was pressed on
Expanded: true                                      # the clicked element's (or its control's) aria-expanded flipped (JSON expanded)
Focus moved to: input#other "Other"                 # a fill's input handler moved focus off the field (JSON focusMoved)
DOM changed (200 nodes)                             # only when nothing else is reported: 3+ elements added/removed (JSON domChanges)
⚠ The mouse was released on button#next, not on ... # the page moved/replaced the clicked element mid-press (JSON releasedOn)
Shown:         span "Something went wrong"          # text added next to the clicked control, also in shadow roots, or un-hidden by an aria-expanded click (aria-controls / next sibling), or a pre-rendered <dialog> the click opened (showModal / open; not popovers, <details> or dialogs opened after an await/timer; one opened in the next animation frame usually is reported)
⚠ Submit blocked: email: Please include an '@' ...  # the form's validation stopped the submit (click or Enter): fix the named fields
Errors: Uncaught Error: handler exploded (app.js:3:142)  # console errors/exceptions the action caused
        (+2 from filtered trackers)                       # tracker-host errors hidden; start the session with bdg <url> --capture-all to list them
Errors:        none from the page (2 from filtered trackers hidden; bdg console --level error)  # trackers were the only source
Selector:      html > body > button:nth-of-type(2)  # after Element:, for an index into dom a11y query results (absent for a bare #id, or when no selector finds only that element: iframe, shadow root)
Download: report.txt → ~/.bdg/downloads/report.txt (completed, 15 B)  # files go to <session dir>/downloads
Opened: popup https://idp.test/authorize (bdg page switch 1)          # a tab or window it opened
  • In --json: navigation, messages, errors ([{ text, source, count }], max 3, then moreErrors), downloads, opened, effect: "none", submitBlocked ([{ field, message }]) and pending work (timers, spinners) are fields on data.
  • shown lists at most 3 elements; moreShown ((+N more)) counts the rest ((+N or more) and moreShownPartial when the page scan ran out of time; moreShownPartial without moreShown means the scan was cut short and more may be there).

Content truncated.

When not to use it

  • →When scraping static HTML content
  • →When making simple API calls
  • →When performing basic HTTP requests

Limitations

  • →Not suitable for static HTML scraping
  • →Not suitable for simple API calls
  • →Not suitable for basic HTTP requests

How it compares

This skill provides a command-line interface for direct, programmatic control over a Chrome browser using CDP, enabling automation of dynamic web content and interactions that are not possible with simple HTTP requests or static HTML parser

Compared to similar skills

bdg side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
bdg (this skill)08moReviewIntermediate
playwright-mcp3310moNo flagsIntermediate
dev-browser538moReviewIntermediate
chrome-devtools4110moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

playwright-mcp

sfc-gh-dflippo

Browser testing, web scraping, and UI validation using Playwright MCP. Use this skill when you need to test Streamlit apps, validate web interfaces, test responsive design, check accessibility, or automate browser interactions through MCP tools.

33197

dev-browser

SawyerHood

Browser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.

53176

chrome-devtools

mrgoonie

Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.

41157

agent-browser

vercel-labs

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.

3075

browser-tools

Whamp

Lightweight Chrome automation toolkit with shared configuration, JSON-first output, and six focused scripts for starting, navigating, inspecting, capturing, evaluating, and cleaning up browser sessions.

694

browser

cexll

This skill should be used for browser automation tasks using Chrome DevTools Protocol (CDP). Triggers when users need to launch Chrome with remote debugging, navigate pages, execute JavaScript in browser context, capture screenshots, or interactively select DOM elements. No MCP server required.

346

Search skills

Search the agent skills registry