
webgpu-inspector
Capture and analyze WebGPU frames from a live page with Claude.
- GitHub stars
- 380
Install
/plugin install webgpu-inspector@webgpu-inspector-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add brendan-duncan/webgpu_inspector.
Contents
Discovered from sourceSkills 1
WebGPU capture analysis
A WebGPU Inspector capture is a record of one or more rendered frames: the full GPU object graph plus the ordered list of WebGPU API calls. This skill explains how to read one and what to flag.
Capture files
Saved captures are .wgpuc binary files: an ASCII header line
(WGPUCAP <version> <jsonByteLength>\n), then <jsonByteLength> bytes of
metadata JSON (the object described under "Capture shape" below, so the front
of the file is readable text), then raw buffer/texture payload bytes located
by the metadata's payloadTable. Don't parse one by hand — pass the path to
load_capture_file and use the MCP tools. Legacy captures (single-object
.json, or NDJSON with base64 payload lines) load the same way.
Capture shape
objects— map of numeric id to a record:{ id, type, label, descriptor, stacktrace, ... }. Types:Adapter,Device,Buffer,Texture,TextureView,Sampler,BindGroup,BindGroupLayout,PipelineLayout,RenderPipeline,ComputePipeline,ShaderModule,RenderBundle.commands— ordered array of{ index, method, object, args, result, ... }.objectis the GPU object the method was called on;argsare its arguments. References to GPU objects appear as{ "__id": N, "__class": ..., "__label": ... }.validationErrors— WebGPU validation errors raised during the capture.- Large buffer/texture payloads live out-of-band (referenced by
__payloadId); the MCP tools strip them, so you see__base64Omittedmarkers and byte lengths instead of bytes.
Workflow
Always start with get_capture_summary — it carries object/command counts,
derived stats, and a heuristic issues list. Then drill in:
get_commandswith amethodfilter, apassLabelregex, or anoffset/limitwindow — never fetch the whole list at once for a large capture.get_objectfor a pipeline, bind group, or texture descriptor.get_shaderfor a ShaderModule's WGSL.get_validation_errorsfor correctness problems.
To debug a specific draw (e.g. "this draw read a vertex attribute as 0"):
get_draw_state(commandIndex)resolves the bound pipeline (+ vertex layout), bind groups, vertex/index buffers, and draw params for a draw command. Each vertex buffer reports abufferDataCommandIndex.decode_vertex_buffer(commandIndex)— pass a vertex buffer'sbufferDataCommandIndexto decode its first N vertices into per-attribute numbers (the layout is taken from the pipeline automatically).diff_draws(cmdA, cmdB)compares a working vs. a broken draw's resolved state.get_pixel_history(textureId, x, y)lists every fragment that touched a pixel and why it was kept or dropped (depth-failed, stencil-failed, discarded, scissored, ...). Use it for "why is this pixel black / wrong / missing".debug_shader(commandIndex, ...)runs one invocation on the CPU with the captured resources:vertexIndexfor a vertex,x/yfor a fragment,invocationfor compute. Passwatch: ["name", ...]for a line-by-line trace of variables. ItsmissingDatafield says when the capture lacks the bound buffers' bytes; recapture withpayloads: "all"then.get_frame_issuesruns the Frame Issues rules andget_render_graphshows the pass dependencies (results nothing reads, overwritten before read, reads of discarded attachments).
To try a shader fix on the live page, replace_shader(shaderId, code) swaps the
module's WGSL (it reports validation errors), then check with screenshot_page
or a new capture; restore_shader undoes it. Capture ids and live ids match.
For very large frames, capture only what you need: capture_frames accepts
passLabel / passType (capture heavy payloads for matching passes only) and
maxBufferSize (per-buffer byte cap; truncated buffers are marked). To inspect a
live buffer without a full capture, use read_buffer.
Cite index (command) and id (object) values in findings so the user can
locate them in the WebGPU Inspector DevTools Capture panel.
Performance analysis
When the goal is performance — the frame is slow, janky, dropping frames, or the user asks where the time goes / whether it's CPU- or GPU-bound / about fillrate — take the GPU-timed path by default, without being asked to enable it:
- Capture with per-pass GPU timing:
capture_frames({ profilePasses: true, payloads: "none" }).profilePassesinjects per-pass GPU timestamp queries so each render/compute pass carries a measureddurationMs(and the frame a total GPU time);payloads: "none"keeps the capture light — profiling needs the command list and object graph, not the buffer/texture bytes. Treat "analyze the performance of a frame" as implyingprofilePasses: true. - Call
analyze_performance(not justget_capture_summary). It returns the frame budget and a CPU-/GPU-/vsync-bound verdict, passes ranked by GPU time each annotated with render-target size/format/MSAA, blend usage, fragment-shader complexity, and a likely bottleneck (fillrate/ROP vs fragment-ALU), plus heuristic issues and ranked improvement suggestions. - For a live page,
get_frame_statssamples fps / dropped frames / CPU submit time / bound verdict over a short window without a capture — use it to confirm the page is actually dropping frames or is CPU-bound before drilling in. get_bottlenecksgives each pass a verdict from its GPU time, primitives and fragment counts (tiny triangles, overdraw, fragments shaded then rejected, heavy targets).get_overdraw(textureId)shows where the overdraw is.- To find the expensive shader code:
get_shader_flame_graphranks the frame's cost by pass, pipeline, stage and statement (measureDrawTimes: truemeasures each draw), andmeasure_shader_cost(commandIndex)measures each statement of one draw's shader on the GPU. - After a change, recapture and
compare_captures(captureA, captureB)to show what moved.
The GPU-replay tools (get_bottlenecks' counts, get_overdraw,
measure_shader_cost, measureDrawTimes) need a browser from launch_browser
or attach_browser; they replay the capture in a tab of their own.
Notes:
- GPU timing needs the adapter's
timestamp-queryfeature; the inspector enables it automatically when available and it is a no-op otherwise. Without it,analyze_performancestill ranks passes by fill workload and says GPU time is unavailable — re-run once the feature is present for real timings. - The fillrate-vs-fragment-ALU verdict is a static heuristic (render-target bytes × MSAA × area × blend, plus a WGSL fragment-complexity scan). To confirm fillrate, reduce the render-target resolution and re-measure: GPU time scaling ~linearly with pixel count ⇒ per-pixel (fillrate/fragment) bound; flat ⇒ vertex/geometry/CPU bound.
What to look for
Correctness
- Any
validationErrors— always report these first; they are real bugs. - A canvas texture used after its frame expired, or destroyed objects still referenced (the inspector reports these as validation errors).
Per-frame cost / hitching
createRenderPipeline/createComputePipelineinside the captured frame — pipeline creation is expensive; move it to load time.createShaderModuleinside the frame — same idea.- Large or numerous
writeBuffer/writeTexturecalls every frame — consider persistent buffers, mapped writes, or uploading less.
CPU submission overhead
- High
setPipeline/setBindGroup/setVertexBuffercounts relative to draw calls — sort draws by pipeline and bind group to cut state changes. - Redundant consecutive
setPipeline/setBindGroup(the summary flags these) — the bind is a no-op and can be skipped. - Many small draw calls with the same pipeline — candidates for instancing, batching, or render bundles.
Pass structure
- Excess
beginRenderPasscalls — each pass has fixed cost; merge where the attachments allow. loadOp: "load"where"clear"would do (forces an attachment read), orstoreOp: "store"on attachments whose result is never used.- Depth/stencil attachment configuration vs. what the draws need.
Shaders (via get_shader)
- Work in the fragment stage that could move to the vertex stage.
- Dynamically uniform branching, heavy loops, or texture sampling in loops.
- Bind group layout mismatches across entry points.
Reporting
Give a prioritized list. For each finding: severity (error > warning > info), a one-line description, why it matters for this capture, and a concrete fix. Reference command indices and object ids. Distinguish confirmed bugs (validation errors) from heuristics (a flagged pattern that may be intentional) — say which is which rather than overstating.
Commands 2
Analyze a WebGPU Inspector capture in depth.
$ARGUMENTS may be a capture id (e.g. cap-2), a path to a saved capture
file (.wgpuc, or legacy .json), or empty (use the most recent capture).
Do this:
- If
$ARGUMENTSlooks like a file path, callload_capture_filewith it. Otherwise calllist_captures; pick the capture matching$ARGUMENTS, or the most recent one if$ARGUMENTSis empty. If there are no captures, tell the user to run/webgpu-inspector:capturefirst and stop. - Call
get_capture_summaryfor that capture.- If the request is about performance (slow, janky, dropped frames,
bottleneck, CPU/GPU bound, fillrate, "where's the time going"), also call
analyze_performancefor the frame-budget/bound verdict, per-pass GPU-time ranking, and improvement suggestions. If the summary has nogpuTiming(the capture wasn't taken withprofilePasses: true) and a page is still connected, offer to re-capture withcapture_frames({ profilePasses: true, payloads: "none" })so passes carry real GPU timings — don't wait to be asked to enable it.get_frame_statsgives a live fps / dropped-frame / bound read without a capture.
- If the request is about performance (slow, janky, dropped frames,
bottleneck, CPU/GPU bound, fillrate, "where's the time going"), also call
- For each entry in
issues, confirm and explain it usingget_commands(pass the reportedcommandIndices),get_object, andget_shader. - Review the shaders involved with
get_shader; check the WGSL for obvious inefficiencies relevant to the captured workload. - Call
get_validation_errorsand explain any that are present. - Give the user a prioritized list of findings. For each: severity, what it is, why it matters, and a concrete fix — citing command indices and object ids so they can locate it in the WebGPU Inspector DevTools panel.
Use the webgpu-capture-analysis skill for guidance on interpreting the data.
Capture and summarize WebGPU frames from a page.
$ARGUMENTS may contain a URL to open, a frame count, or both (default 1 frame).
Do this:
- Call
browser_status. If no browser is connected:- If
$ARGUMENTShas a URL, calllaunch_browserwith it. - Otherwise tell the user you can
launch_browser(the plugin starts Chrome) orattach_browser(to a Chrome started with--remote-debugging-port=9222), and ask which — or ask for a URL to open.
- If
- If a browser is connected but
$ARGUMENTShas a URL, callopen_pagewith it. - Call
list_pages. If none are connected, the page may not use WebGPU, or it created GPU objects before finishing load — say so and stop. If exactly one page is connected, use it; if several, ask whichpageId. - Call
capture_frameswith that page and the requested frame count. If the request is about performance (slow, janky, dropped frames, bottleneck, CPU/GPU bound, fillrate, timing), passprofilePasses: trueso each pass carries a measured GPU duration — andpayloads: "none"for a lighter perf-only capture — then report viaanalyze_performance. Treat a performance request as implyingprofilePasses: true; you don't need the user to ask for it. - Report the returned summary in plain language: total commands, draw calls,
dispatches, render/compute passes, object counts, validation errors, and
every entry in
issues. - Offer to dig deeper — shaders (
get_shader), specific commands (get_commands), object descriptors (get_object), validation errors.
MCP servers 1
Sponsors
Details
- Marketplace
- brendan-duncan/webgpu_inspector
- Source
- claude-plugin
- Category
- Community