GPU Performance Agent

Profile WebGPU and WebGL apps from your terminal. Get useful diagnostics, compare changes, and give your coding agent real measurements to work with.

Website · npm · Full reference · Agent skill

One command. A useful report.

Start your app, then point the profiler at it:

npx gpu-perf-agent agent --url http://localhost:5173 --out reports/base.json

A short digest lands in your terminal. Full measurements are saved to JSON. No changes to your app required.

Requires Node.js 22+ and Chrome/Chromium. The default runner has zero required npm dependencies. Check your setup with npx gpu-perf-agent doctor --quick.

What you get

• Find expensive work. Frame pacing, slow frames, draw calls, declared GPU allocations, and actionable warnings.
• Check whether a change helped. Before/after comparisons, confidence intervals, and regression budgets.
• Keep agents focused. Compact output, structured JSON, a bundled skill, and a built-in MCP server.
• Iterate without the startup tax. Reuse Chrome while each capture gets an isolated browser context.

Make a change. Measure it again.

Capture the candidate with the same settings, then compare:

npx gpu-perf-agent agent --url http://localhost:5173 --out reports/candidate.json
npx gpu-perf-agent compare --base reports/base.json --candidate reports/candidate.json --agent

The comparison reports regressions, improvements, and inconclusive results. Invalid measurements are flagged explicitly. Exit codes: 0 valid / passing, 1 regression or command error, 2 invalid or incompatible evidence.

For more confidence, use interleaved A/B runs or enforce a performance budget.

Pick your workflow

| You want to… | Use | | --- | --- | | Inspect a visual report | npx gpu-perf-agent agent --url http://localhost:5173 --html | | Profile a static build | npx gpu-perf-agent agent --file dist/index.html --file-root dist | | Get machine-readable output | Add --json | | Connect an MCP client | npx gpu-perf-agent mcp | | Keep Chrome ready for repeated jobs | npx gpu-perf-agent serve --port 9099 --auto-instrument |

For the persistent server, add --server http://127.0.0.1:9099 to your capture command. Use the Node API to integrate directly, or the agent skill to teach your assistant the workflow.

Know what you’re measuring

Frame timing observes browser cadence. GPU duration needs timing hooks. Allocation tracking estimates declared storage, not physical VRAM residency. Compare the same scene and capture settings; use more samples when results are inconclusive.

Read the full reference →

What’s new · Measured tool overhead · Examples · MIT license