Perf Triage

Perf Triage

A Claude Code skill for triaging runtime performance problems in a running web app — 100% CPU, jank, a freeze, a slow tab/route switch — by capturing a real CPU profile over the Chrome DevTools Protocol (CDP) and diagnosing from it, instead of guessing from source.

It encodes a repeatable workflow and the hard-won decision lessons from real perf investigations: which metric matches which symptom, how to capture a profile when the DevTools panel crashes on huge traces, and how to fix with measure-and-revert discipline.

Why CDP instead of the DevTools panel

A long, high-CPU spike produces a huge trace, and the DevTools Performance panel crashes rendering the flame chart. CDP's Profiler domain hands back a compact .cpuprofile with no UI involved, so capture always works. The bundled scripts automate this.

What it does

1. Set up a target — launch a separate CDP-enabled Chrome, have you log in and reach the pre-interaction state, hand back the URL.
2. Capture a CPU profile over CDP, driving the interaction itself (deterministic, short window).
3. Analyze offline — idle %, active CPU, per-function self-time, spike shape — picking the metric that matches the symptom.
4. Diagnose the mechanism (accidental O(N²), event/notification storm, an expensive cache guard).
5. Fix with discipline — smallest behavior-preserving change, re-measure each one, revert anything that doesn't help.

Install

/plugin marketplace add iamsaumya/perf-triage
/plugin install perf-triage@perf-triage

Then invoke it on an issue:

/perf-triage:perf-triage

To try it locally without installing:

claude --plugin-dir /path/to/perf-triage

Requirements

• A Chromium-based browser (Chrome / Edge / Brave) launchable with --remote-debugging-port.
• Node 21+ (built-in WebSocket/fetch), or Node 18–20 with the ws package (npm i ws) for the capture script.
• The web app running and reachable.

The bundled tooling

• skills/perf-triage/scripts/capture-cpuprofile.js — connect to Chrome on a debug port, reload, drive the interaction, record a .cpuprofile.

  node capture-cpuprofile.js --url <appUrl> --trigger "<button text>" [--reset "<other tab>"] [--seconds 22] [--out spike.cpuprofile] [--port 9222]
  

• skills/perf-triage/scripts/parse-cpuprofile.js — offline analysis (idle %, active CPU, self/inclusive time, active-CPU-per-second spike shape).

  node parse-cpuprofile.js <file.cpuprofile> [topN]
  

Both are generic — parameterized by URL, click targets, duration, and port. No app-, company-, or framework-specific assumptions.

License

MIT — see LICENSE.