| name | chrome-devtools-runtime-debugger |
| description | Use guided Chrome DevTools MCP setup and workflows for browser runtime debugging. Use when a web app needs console, network, DOM, accessibility, Lighthouse, performance, responsive, or live-browser investigation beyond normal tests. |
Chrome DevTools Runtime Debugger
Purpose
Give agents a repeatable path for observing real browser behavior through Chrome DevTools MCP without bundling global MCP config into this plugin.
Inspect First
- local runtime URL, dev scripts, healthcheck, logs, browser test failures, console/network symptoms, and existing MCP configuration notes
- whether the user has Chrome DevTools MCP installed and available in the current session
Procedure
-
Choose the right browser tool.
- Use Playwright tests for repeatable product workflows.
- Use
$click-path-and-browser-qa to turn repeated browser workflows into route/control inventories and Playwright coverage.
- Use Chrome DevTools MCP for console errors, network failures, DOM/CSS inspection, Lighthouse, performance traces, responsive emulation, and live debugging.
-
Guide setup when missing.
- Use
scripts/check_chrome_devtools_mcp.py when available to check whether chrome-devtools is configured.
- For Codex, document the official command:
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest.
- Do not edit global Codex config unless the user explicitly asks.
- Restart Codex or use a new session when MCP config changes are needed.
-
Run diagnosis.
- Start local runtime and confirm healthcheck.
- Open the target URL.
- Inspect console and page errors.
- Inspect failed network requests and CORS/auth/env issues.
- Capture screenshots for layout or visual regressions.
- Run Lighthouse or performance traces only when relevant.
-
Document findings.
- Create or update
docs/observability/browser-debugging.md from assets/templates/chrome-devtools-debugging.md.tmpl.
- Link findings to
observability-harness, testing-strategy-builder, or tdd-playwright-workflow follow-up checks.
- Route process evidence, evaluator criteria, and task traces to
sprint-contract-observability.
Validation
- Confirm the local app is reachable before browser debugging.
- Confirm Chrome DevTools MCP availability with the helper or
codex mcp list; if unavailable, provide setup guidance instead of pretending the tool is callable.
- Capture concrete evidence: console message, network request, screenshot, DOM state, Lighthouse item, or trace summary.
- Confirm any fix is rechecked in the browser or covered by Playwright.
Completion Criteria
- Browser failure has concrete runtime evidence.
- Setup guidance is clear when Chrome DevTools MCP is unavailable.
- Debugging outputs are linked to tests or docs so the issue is not rediscovered from scratch.