Browser Runtime Debugging Toolkit
Overview
UI/CSS/DOM layout issues often have root causes that only manifest at runtime — dynamically generated DOM structures, CSS specificity conflicts, layout calculation anomalies. Static code analysis (Read/Grep) and console-based debugging (console.log) have a fundamental limitation: they cannot observe the rendered DOM tree, computed CSS properties, or box model geometry.
This skill provides a scene-to-tool decision table and usage guides for each tool. Referenced by PDCA hosts via frontmatter dependencies (invoked after a prerequisite check when browser-reproducible scenarios are detected). Hosts are SoT for that edge.
Prerequisites
Step 1: Check MCP Availability
Before using browser debugging tools, check if chrome-devtools-mcp (sometimes called chrome-devtools-connect) is available:
| Platform |
Check Method |
| Claude Code |
Run claude mcp list and look for "chrome-devtools" |
| OpenCode |
Check available tools, or cat ~/.config/opencode/opencode.json |
| Cursor |
Settings → MCP → view server list |
Step 2: If MCP Is Missing — Adaptive Choice
When chrome-devtools-mcp is not available, present the user with three options:
Option A: Auto-install (Recommended)
The AI runs the installation command directly for the detected platform:
| Platform |
Install Command |
| Claude Code |
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest |
| OpenCode |
Add MCP config to ~/.config/opencode/opencode.json |
| Cursor |
Use "Install in Cursor" button from official README, or manually add to MCP settings |
After installation, restart the AI tool to load the MCP server.
Option B: Manual Install
Provide the exact commands (same as Option A) for the user to copy-paste and run themselves. Wait for user confirmation before proceeding.
Option C: Skip — Use Manual DevTools
Fallback: guide the user to open browser DevTools manually (F12) and inspect elements by hand. Slower than MCP but requires no setup.
Step 3: Environment Prerequisites
- Node.js LTS + npm (required by chrome-devtools-mcp)
- Chrome browser (stable version; Google Chrome or Chrome for Testing)
Step 4: Verify Installation
After install/enable, verify the MCP is loaded:
| Platform |
Verification |
| Claude Code |
claude mcp list shows chrome-devtools |
| OpenCode |
Config file contains chrome-devtools entry |
| Cursor |
Settings → MCP shows server with green status |
Scene → Tool Decision Table
| Problem Scene |
Default: ego-browser |
Fallback: chrome-devtools-mcp |
Fallback: web-access CDP Proxy |
Key Capability |
| DOM structure anomaly (missing/wrong elements) |
snapshotText() a11y tree + js() DOM walk |
Elements panel |
/eval read DOM |
Live DOM tree, element selection, attribute inspection |
| CSS not applying / specificity conflict |
js() getComputedStyle + override-chain walk |
Elements → Styles |
/eval getComputedStyle |
Computed styles, override chain, box model |
| Layout shift / box model anomaly |
js() getBoundingClientRect + ancestor walk |
Computed / Layout panel |
/eval getBoundingClientRect |
Box model visualization, flex/grid guides |
| Interaction anomaly (click not responding) |
click(@N) + js() listener/state check + cdp() Console |
Console + Event Listeners |
/click vs /clickAt real-gesture comparison |
Event listener inspection, JS runtime errors |
| Login wall / captcha interrupts the debug flow |
handOffTaskSpace → user acts → takeOverTaskSpace (unique) |
— |
— |
Atomic human-AI handoff mid-debug; agent and user share one browser without fighting for control |
| Selector-fragile UI (Canvas / virtualized list / frequently re-skinned page) |
snapshotText() @N refs + visual mode (screenshot + coordinates) |
— (non-macOS: playwright-mcp a11y snapshot) |
— |
a11y-tree refs survive CSS/markup churn; re-snapshot after mutation |
| Login state + full CDP domains needed together (e.g. network waterfall behind login) |
cdp('Network.*') in logged-in task space |
attach to an existing logged-in Chrome |
/eval reads only; no full domains |
Raw CDP passthrough with inherited login state |
| Render performance (jank/frame drops) |
cdp('Performance.*') raw trace |
Performance panel (purpose-built — preferred for perf) |
— |
Flame chart, Long Tasks, render stats; pair with perf-optimize-workflow |
| Visual regression (style overwritten) |
captureScreenshot() before/after diff |
— |
/screenshot before/after diff |
Screenshot diff; pair with visual-qa skill |
| Async loading / network issues |
cdp('Network.*') + drainEvents() |
Network panel |
— |
Request/response, waterfall, status codes |
| State management anomaly (React/Vue) |
js() inspect store / component state |
React/Vue DevTools (user-operated extensions) |
— |
Component tree, props/state, time travel |
Default channel: ego-browser (external skill, macOS only) — runtime-check it first; it is a runtime-local dependency, not declared in frontmatter dependencies, so upstream workflows like solve-workflow stay free of any external-plugin requirement. If ego-browser is unavailable (not installed / non-macOS) or fails mid-task (error, cannot reach the page, raw cdp() too low-level for the need), degrade along the chain below and tell the user which channel you are on — never silently fall back. The fallback columns point to chrome-devtools-mcp (MCP server, see Prerequisites) and the external web-access skill's CDP Proxy (same weak-reference rule: verify availability, abort with an install hint if missing). Non-macOS substitutes for the ego-browser row: playwright-mcp (MCP, a11y-tree snapshots) → agent-browser (CLI).
Tool Usage Guides
chrome-devtools-mcp (MCP Server)
Type: MCP server (Chrome DevTools Protocol) / Availability: Environment-dependent (see Prerequisites)
When to use: Real-time inspection of page DOM, CSS, network, and console — AI operates DevTools directly without manual context switching.
Core capabilities: DOM inspection (querySelector, computed styles, element attributes), CSS debugging (matched rules, override chain, box model), Console (execute JS, read output), Network (request/response inspection), Screenshot (page or element capture).
Usage pattern: When MCP is available, connect to the browser in the workflow's analysis stage → reproduce the problem and inspect runtime state (DOM structure, computed styles, console, network) → compare expected vs actual to anchor root cause; in the verification stage, validate that the fix works.
Note: If MCP is not installed, see the Prerequisites section above for adaptive setup options (auto-install / manual / skip).
playwright / webapp-testing (Skill)
Type: Skill (browser automation) / Availability: OpenCode built-in playwright; user skill webapp-testing
When to use: Automated interaction reproduction (click, type, navigate), screenshot comparison, end-to-end verification.
Difference from chrome-devtools-mcp: Playwright focuses on automated operations (script-driven, batch verification); chrome-devtools-mcp focuses on real-time inspection (interactive debugging, instant feedback).
visual-qa (Skill)
Type: Skill (visual quality assurance) / Availability: shared/opencode skill
When to use: Screenshot comparison, design review, visual regression verification. Especially suited for before/after fix comparison scenarios.
Framework DevTools (Browser Extensions)
| Framework |
DevTools |
Core Capability |
| React |
React DevTools |
Component tree, props/state, Profiler timeline |
| Vue |
Vue DevTools |
Component tree, Vuex/Pinia state, routing |
| Angular |
Angular DevTools |
Component tree, change detection, Signal dependency graph |
Framework DevTools are browser extensions that AI cannot operate directly. Guide the user to install and inspect manually.
Three channels, three postures — choose by signal
Pick the channel by what the debug session needs, not by habit. The three overlap in basic interaction (click / fill / evaluate / screenshot) but differ sharply in posture:
| Aspect |
chrome-devtools-mcp |
web-access CDP Proxy |
ego-browser (macOS) |
| Posture |
Inspect (DevTools panels: Elements / Network / Performance) |
Lightweight control + verify (operate the page, capture state) |
Full control + raw CDP + human-AI handoff |
| Login state |
Fresh session by default; can attach to an existing Chrome |
Connects to user's daily browser — login state native |
Inherited from user's browser — login state native |
| Element targeting |
CSS / text queries |
CSS via /eval |
snapshotText() a11y refs (@N) + CSS + xpath + coordinates |
| Full CDP domains (Network/Performance/Console) |
✅ via panels |
❌ (proxy subset: eval/click/scroll/screenshot) |
✅ cdp() raw passthrough |
| Human-AI handoff mid-debug |
❌ |
❌ |
✅ handOffTaskSpace / takeOverTaskSpace |
| Browser isolation |
Separate fresh instance |
Shares user's browser (background tabs, parallel-safe) |
Isolated Task Space — never disturbs user's tabs |
| Scripting posture |
MCP tools (interactive) |
curl HTTP API (batch, parallel agents) |
heredoc JS batch (multi-step in one round) |
| Platform |
Cross-platform (Chrome-family) |
Cross-platform |
macOS only |
Default: ego-browser first. Start every browser debugging / control session on the ego-browser channel (runtime-check availability first). It is the only channel that bundles full interaction + page JS + raw CDP + inherited login state + isolated task space + human-AI handoff, so one channel covers the whole observe → reproduce → verify loop. Degrade only when it is unavailable (not installed / non-macOS) or fails for the need at hand:
ego-browser (macOS, default — runtime-checked)
├─ unavailable or failed?
│ ├─ non-macOS → playwright-mcp (MCP, a11y snapshots) → agent-browser (CLI)
│ ├─ need purpose-built panels (perf trace / network waterfall / computed style),
│ │ where raw cdp() is too low-level or fails → chrome-devtools-mcp
│ ├─ need lightweight login-state control or curl-parallel sub-agents → web-access CDP Proxy
│ └─ nothing available → guide user to manual DevTools (F12)
└─ still tell the user which channel you are on (never silently fall back)
Two specialist exceptions where the fallback may be the better first pick even when ego-browser works: performance traces (chrome-devtools-mcp's purpose-built Performance tooling beats raw cdp('Performance.*')) and unattended CI regression (Playwright / webapp-testing — no user browser exists in CI). Pure information retrieval (search / scraping / anti-scrape platforms) is not a debugging task — that belongs to effective-web-research + web-access, not this skill.
For the web-access curl API cheat sheet, the ego-browser heredoc recipes, and debugging recipes per channel, see [reference.md](reference.md).
Workflow Integration
Referenced by PDCA hosts via frontmatter dependencies (missing → host aborts). Also discovered by debug-workflow and similar workflow skills through environment capability exploration. Delegated to by hybrid-debug for runtime evidence in hybrid app (WebView/WKWebView/Electron + H5) debugging, and by runtime-evidence-debug for UI/CSS/DOM instrumentation in general debugging:
- Analysis stage: Browser-reproducible problems (UI/CSS/DOM as typical scenes) → prioritize browser tools to reproduce the problem and inspect runtime state
- Before console.log debugging: For UI issues, inspect with browser DevTools first (more efficient than console.log), then fall back to logging if still unresolved
- Verification stage: After fix, use browser tools to verify that the fix works (before/after runtime-state comparison)
Progressive enhancement: This skill does not replace the host workflow's core process. When loaded as a strong dependency it is guaranteed by the host prerequisite check; in other workflows (e.g., debug-workflow), when browser tools are unavailable, the original process executes unchanged.
Quick Reference
Scene detection: Can this problem be reproduced in a browser? (UI/CSS/DOM issues are the typical scenes)
Signal keywords: style, layout, render, display, visibility, position, size, color, animation
→ Yes → Prioritize browser tools to reproduce and inspect (this skill's decision table guides selection)
→ No → Follow original static analysis / console.log debugging process
Tool selection (default + degradation — full table in "Three channels" section):
1. ego-browser (macOS, runtime-checked) — DEFAULT: full interaction / js() / raw cdp() / login state / task space / handoff
2. unavailable or failed → non-macOS: playwright-mcp → agent-browser
3. → purpose-built panels (perf / network / computed style): chrome-devtools-mcp
4. → lightweight login-state control, curl-parallel: web-access CDP Proxy
5. Unattended CI / batch E2E → playwright / webapp-testing (specialist exception)
6. Visual comparison / design review → visual-qa
7. No browser tooling → guide user to manual DevTools
MCP prerequisite check:
→ MCP missing? Present adaptive choice: A=auto-install / B=manual / C=skip
→ See Prerequisites section for platform-specific commands
