Debug Chrome WebGPU applications on macOS — browser-level via Chrome DevTools MCP, GPU-driver-level via Xcode xctrace Metal System Trace. Use when: WebGPU rendering bugs, GPU performance issues, shader debugging, frame timing analysis, Metal command buffer profiling.
How this skill is triggered — by the user, by Claude, or both
Slash command
/webgpu-metal-debug-kit:webgpu-metal-debug-kitThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Debug Chrome WebGPU applications on macOS at two levels:
Debug Chrome WebGPU applications on macOS at two levels:
xctrace Metal System TraceMetal Toolchain: !/usr/bin/xcrun xctrace list templates 2>/dev/null | grep -q "Metal System Trace" && echo "installed" || echo "NOT INSTALLED — run: xcodebuild -downloadComponent MetalToolchain"
setup-metal-debug.sh.navigate_page, wait 2-3 seconds before calling evaluate_script.evaluate_script over take_screenshot. Stats = few tokens. Screenshot = ~1MB tokens./usr/bin/xcrun xctrace directly. Never use bash scripts/capture-metal-trace.sh (PATH issues in Claude Code).The user provides a URL to their running WebGPU app. If they say "demo", run bash ${CLAUDE_SKILL_DIR}/../../demo/start.sh --no-open in the background. The script finds an available port automatically and prints Server ready: http://localhost:<port>/demo/. Parse the URL from the output and use it. The --no-open flag prevents opening a system browser (MCP Chrome will be used instead).
navigate_page → <user's URL>
Wait, then verify the debug helpers are loaded:
// evaluate_script
() => window.__gpu ? window.__gpu.stats() : 'not loaded'
If window.__gpu is not available, the app may not include webgpu-debug-helpers.js. Guide the user to add it.
window.__gpu.stats() // { fps, avgMs, maxMs, frameGapMs }
window.__gpu.setDebugMode(0) // normal
window.__gpu.setDebugMode(1) // render path (blue=hit, dark=miss)
window.__gpu.setDebugMode(2) // step heatmap (green=few, red=many)
window.__gpu.setDebugMode(3) // depth (dark=near, bright=far)
window.__gpu.setDebugMode(4) // normals (RGB)
window.__gpu.textures() // tracked texture info
window.__gpu.timings() // GPU timing records
Check list_console_messages for WGSL shader errors or WebGPU warnings.
When frameGapMs >> avgMs, there may be a driver-level bottleneck.
GPU_PID=$(pgrep -f "Google Chrome.*--type=gpu-process" | head -1)
echo "GPU PID: $GPU_PID"
rm -rf /tmp/webgpu-metal-trace.trace
/usr/bin/xcrun xctrace record \
--template 'Metal System Trace' \
--attach "$GPU_PID" \
--time-limit 5s \
--output /tmp/webgpu-metal-trace.trace
Export and analyze:
/usr/bin/xcrun xctrace export --input /tmp/webgpu-metal-trace.trace --toc | grep schema
/usr/bin/xcrun xctrace export --input /tmp/webgpu-metal-trace.trace \
--xpath '/trace-toc/run/data/table[@schema="metal-gpu-intervals"]'
Look for:
Note: For full Metal encoder/command buffer detail, the user should configure MCP with --browser-url to connect to a Chrome launched with --disable-gpu-sandbox. See assets/mcp-settings-metal.json.
| Symptom | Action |
|---|---|
| Artifacts | setDebugMode(1) — which path is wrong? |
| Shader error | list_console_messages |
| Data missing on GPU | __gpu.stats() — check uploadCount |
| Slow, GPU time fine | Metal trace — command buffer count |
| Hot pixels | setDebugMode(2) — red = expensive |
npx claudepluginhub penspanic/webgpu-metal-debug-kit --plugin webgpu-metal-debug-kitOpens and inspects Metal GPU .gputrace files using the gpudebug CLI. Covers draw calls, render encoders, pipeline state, resource bindings, textures, buffers, and shader source.
Interprets WebGPU Inspector frame captures including GPU object graphs, command lists, render/compute passes, buffers, textures, shaders, and validation errors. Useful when analyzing captured .json files from WebGPU Inspector MCP tools or DevTools.
Analyzes Meta Quest and Horizon OS VR performance using Perfetto traces — frame timing, CPU/GPU bottlenecks, render pass analysis. Use when profiling frame drops, jank, or thermal issues on Quest devices.