Chrome DevTools Orchestrator - CLI + MCP Integration
Browser debugging and automation through two complementary approaches: CLI (bdg) for speed and token efficiency, MCP for multi-tool integration.
1. WHEN TO USE
Activation Triggers
Use when:
- User mentions "browser debugging", "Chrome DevTools", "CDP" explicitly
- User asks to inspect, test, or automate browser tasks with lightweight CLI approach
- User wants screenshots, HAR files, console logs, or network inspection via terminal
- User mentions "bdg" or "browser-debugger-cli" explicitly
- User needs quick DOM queries, cookie manipulation, or JavaScript execution in browser
- User wants terminal-based browser automation with Unix pipe composability
- User needs production-ready automation scripts for CI/CD browser testing
Automatic Triggers:
- "bdg", "browser-debugger-cli" mentioned explicitly
- "lightweight browser debugging" or "quick CDP access"
- "terminal-based browser automation"
- "screenshot without Puppeteer"
When NOT to Use
Do not use for:
- Complex UI testing suites requiring sophisticated frameworks (use Puppeteer/Playwright)
- Heavy multi-step automation workflows better suited for frameworks
- Cross-browser testing (bdg supports Chrome/Chromium/Edge only)
- Visual regression testing or complex test frameworks
- When user explicitly requests Puppeteer, Playwright, or Selenium
2. SMART ROUTING
The mcp-tooling hub picks the workflow mode, and a request naming Chrome DevTools, CDP, bdg or browser debugging selects this packet through that hub mode signal.
The first loads are references/cdp-patterns.md for the CDP command patterns and references/session-management.md for the session lifecycle.
references/troubleshooting.md serves install and troubleshooting intent, and the full diagnostics wait for their on-demand keywords.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Tool Comparison
Prefer CLI (bdg) for fast, low-token browser inspection. Use MCP via Code Mode when browser work must be chained with other tools or parallel isolated sessions.
CLI Approach (Priority) - browser-debugger-cli (bdg)
Installation & Verification
Check with command -v bdg, install with npm install -g browser-debugger-cli@alpha, then verify bdg --version 2>&1.
MCP Approach (Fallback) - Chrome DevTools via Code Mode
When CLI unavailable or multi-tool integration needed.
Prerequisites
- Code Mode configured in
.utcp_config.json - Chrome DevTools MCP server registered with
--isolated=true
Isolated Instances
Key Feature: MCP uses --isolated=true flag for independent browser instances.
Benefits of isolated instances:
- Each instance runs in its own browser process
- Multiple parallel browser sessions possible
- No session conflicts between instances
- Register multiple instances for parallel testing (e.g.,
chrome_devtools_1,chrome_devtools_2)
Configure one or more Chrome DevTools MCP entries in .utcp_config.json with --isolated=true when parallel browser sessions are needed.
Live Instance (Your Own Chrome)
chrome_devtools_live runs chrome-devtools-mcp --autoConnect and attaches to the Chrome the user already has open, with its logins. Use it only for signed-in work that an isolated browser cannot do, such as the ClickUp editor pass, because an isolated instance starts logged out on every run. Aside owns that work by default, and this instance is its fallback.
- Setup, once: the user turns on remote debugging at
chrome://inspect/#remote-debugging. Chrome must be open, and it may ask the user to allow each new connection. - Stay out of the user's way: open pages with
new_page({ url, background: true }), which keeps the user's view as it is and selects the new tab for later calls. Close only the tab you opened, found by the page ID that appeared inlist_pagesafter yournew_page, never by URL, since the user may have the same page open. Never navigate, press keys in or close a tab you did not open. - Fallback, not default: the isolated instances stay the default for every other MCP task.
Configuration Check
cat .utcp_config.json | jq '.manual_call_templates[] | select(.name | startswith("chrome_devtools"))'
Invocation Pattern
Tool naming is {manual_name}.{manual_name}_{tool_name}. Run MCP browser operations inside call_tool_chain() and close pages in a finally block.
Available MCP Tools
Common MCP tools include navigation, screenshots, console messages, viewport resize, clicks, form fill, hover, keyboard, waits, page creation/selection/close. Use underscores in tool names and confirm exact names with Code Mode discovery.
When to Prefer MCP
- Already using Code Mode for other tools (external services, Figma, etc.)
- Need to chain browser operations with other MCP tools
- Parallel browser testing - compare multiple sites/viewports simultaneously
- Complex multi-step automation in TypeScript
- Type-safe tool invocation required
MCP Limitations
- Higher token cost than CLI
- Requires Code Mode infrastructure
- Subset of CDP methods (CLI has 300+ methods across 53 domains)
- Less self-documenting than CLI's
--list,--describe
MCP Session Cleanup
Always close browser instances when done. Wrap Code Mode browser operations in try/finally so cleanup runs even on errors.
4. RULES
✅ ALWAYS Rules
- Check CLI availability first and prefer CLI when it fits.
- Use discovery commands before CDP methods.
- Verify session status before CDP commands.
- Capture stderr with
2>&1. - Stop sessions after operations.
- Use
jqfor JSON processing. - Keep captures out of the repository and out of replies. HAR files, cookie dumps, traces, heap snapshots and screenshots of logged-in pages can hold live session cookies and bearer tokens. Write them to a scratch folder outside the repository, such as
"${TMPDIR:-/tmp}", or to a path the repository ignores, and never commit them. Redact cookie and authorization values before quoting any of it in a reply, report or file. Print cookie names and domains, not values, unless the operator explicitly needs one.
⛔ NEVER Rules
- Execute CDP commands without an active session.
- Hardcode CDP method lists.
- Skip error handling or exit-code checks.
- Leave sessions running.
- Assume method names without discovery.
- Use on Windows without WSL.
⚠️ ESCALATE IF
- Chrome/Chromium cannot be found.
- Sessions fail after 3 retries.
- Cross-browser testing is required.
- Complex UI testing needs a heavier framework.
- Windows use lacks WSL.
5. SUCCESS CRITERIA
Browser Debugging Completion Checklist
The workflow is complete when:
- A CLI or MCP path is selected.
- Installation or configuration is verified.
- The session is active.
- CDP operations exit 0 with valid JSON.
- The requested data is captured.
- Captures sit outside the repository and are redacted before they are quoted.
- Sessions are cleaned up.
- Discovery and error handling are documented.
Quality Targets
Quality targets are fast session startup, quick screenshot/console capture, and handled errors.
6. INTEGRATION POINTS
Framework Integration
This skill operates within the behavioral framework defined in AGENTS.md.
Key integrations:
- Gate 2: Skill routing via
skill_advisor.py - Tool Routing: Per AGENTS.md Section 5 decision tree
- Continuity: Context preserved by
/speckit:save, which writes throughgenerate-context.js
Tool Usage Guidelines
Use Bash for bdg, Read for references, Grep for logs/output, and Glob for screenshots/HAR exports. Chrome/Chromium is the runtime; set CHROME_PATH if auto-detection fails.
7. QUICK REFERENCE
Essential CLI Commands
bdg cdp --listbdg cdp --describe <domain>bdg cdp --search <term>bdg <url>bdg statusbdg stopbdg dom screenshot <path>bdg console --listbdg dom querybdg dom evalbdg network har <path>
In shell scripts, install a trap so bdg stop 2>&1 runs on exit.
8. REFERENCES AND RELATED RESOURCES
The router discovers Markdown resources dynamically from references/ and assets/ when those directories exist.
This skill currently routes over the flat reference set: references/cdp-patterns.md, references/session-management.md and references/troubleshooting.md.
The asset assets/utcp-chrome-devtools-manuals.md is the registered-state snapshot of the chrome_devtools_1 and chrome_devtools_2 Code Mode manuals. Check .utcp_config.json first and add only the entries it lacks.
Scripts: scripts/install.sh and scripts/doctor.sh, both documented in scripts/README.md.
Examples: examples/README.md — automation example scripts. It lives outside the references//assets/ discovery roots, so it is linked here rather than auto-loaded by the router.
Feature catalog: feature-catalog/feature-catalog.md — the full CLI + MCP capability inventory (30 features across 7 domains), with per-feature files per domain.
Server pointers: mcp-servers/bdg-cli/README.md (CLI install pointer) and mcp-servers/chrome-devtools-mcp/README.md (the Code Mode server behind the manuals) — nothing vendored.
Related skills: mcp-code-mode for MCP fallback and sk-code for browser verification in application-code workflows.
Install guide: INSTALL-GUIDE.md.