browser-debug-agent

Give your AI coding agent real browser debugging powers. Open pages, inspect the DOM, check console/network, click elements, and run deterministic verifications — all from chat.

Works with Kiro, Claude Code, Codex, Cursor, OpenCode, and Gemini CLI.

Quick start (2 commands)

# 1. Install globally
npm install -g browser-debug-agent

# 2. Set up your project (picks your AI host automatically or specify it)
cd your-project
bda setup kiro          # or: claude-code, codex, cursor, opencode, gemini-cli

That's it. Restart your agent and ask it to debug your frontend.

Without global install

cd your-project
npx browser-debug-agent setup kiro

What happens after setup

Your AI agent now has 10 browser tools available via MCP:

Tool	What it does
browser_open	Navigate to a URL in isolated Chromium
browser_snapshot	Get the accessibility tree of the page
browser_interact	Click, fill, type, hover
browser_evaluate	Run JS in the page context
browser_console	Get console log entries
browser_network	Get request/response log
browser_screenshot	Capture page or element
browser_verify	Run deterministic assertions
browser_stop	Close the browser session
browser_doctor	Health check

Plus a debugging methodology skill that teaches your agent to:

• Reproduce before editing
• Gather structured evidence (errors > console > network > DOM > geometry > pixels)
• Patch the smallest causal area
• Verify with browser-visible proof
• Never claim "fixed" without evidence

Example conversations

"The save button doesn't work on the settings page. Debug it."

Your agent will: open the page → click Save → check console for errors → inspect network for failed requests → find the bug → patch it → verify the fix with a real browser.

"Verify that the login page works at mobile, tablet, and desktop viewports."

Your agent will: open the page at 375px, 768px, 1280px → check for overflow → verify all interactive controls → report pass/fail with evidence.

CLI (for direct use)

You can also use bda directly from your terminal:

bda open http://localhost:3000     # open browser (persists between commands)
bda snapshot                       # accessibility tree
bda interact click "#submit"       # click a button
bda evaluate "document.title"      # run JS
bda console                        # see errors
bda network                        # see requests
bda screenshot                     # save PNG
bda verify checks.json             # deterministic assertions
bda stop                           # close

bda doctor                         # check environment
bda server discover                # detect dev server command

Verify manifests

Create verify.json:

{
  "url": "http://localhost:3000",
  "assertions": [
    { "type": "visible", "expect": "Settings", "label": "Heading shows" },
    { "type": "console_errors", "expect": "none", "label": "No JS errors" },
    { "type": "network_status", "expect": { "failed": "none" }, "label": "No 4xx/5xx" },
    { "type": "js", "expect": "document.querySelector('.error') === null", "label": "No error UI" }
  ]
}

bda verify verify.json   # exits 0 on pass, 1 on fail

Requirements

• Node.js >= 20
• Playwright (installed automatically by bda setup)
• One of the supported AI hosts

How it works

Your AI agent (Kiro, Claude Code, etc.)
         │
         ▼
    MCP Server (browser-debug-agent)
         │
         ▼
    Browser Daemon (persistent Chromium via Playwright)
         │
         ▼
    Your app (localhost)

• Browser Daemon: a persistent Chromium process that survives between tool calls. No cold start on every command.
• Evidence JSONL: every action is logged with automatic redaction of cookies, tokens, and credentials.
• Session ownership: only stops processes it started. Your dev server is safe.
• Deterministic verify: assertions produce pass/fail, no LLM judgment involved.

Supported hosts

Host	Setup command	Skill path	MCP config
Kiro	bda setup kiro	.kiro/skills/	.kiro/settings/mcp.json
Claude Code	bda setup claude-code	.claude/skills/	.claude/settings/mcp.json
Codex	bda setup codex	.codex/skills/	.codex/settings/mcp.json
Cursor	bda setup cursor	.cursor/skills/	.cursor/mcp.json
OpenCode	bda setup opencode	.opencode/skills/	.opencode/mcp.json
Gemini CLI	bda setup gemini-cli	.gemini/skills/	.gemini/settings/mcp.json

Add --global for user-level instead of project-level:

bda setup kiro --global

Troubleshooting

bda doctor   # shows runtime versions, host status, active sessions

Common issues:

• "Playwright not found" → bda setup installs it automatically. If it fails: npx playwright install chromium
• "No browser session" → your agent needs to call browser_open before other tools
• MCP not connecting → restart your AI host after running bda setup

Development

git clone https://github.com/anthropics/browser-debug-agent-skill.git
cd browser-debug-agent-skill/core
npm install
npm run build
npm test              # 29 unit tests
sh test-e2e.sh        # real browser E2E
sh test-e2e-repair.sh # repair loop test

License

MIT