AGENT SKILL

hamster-cpu-profiling

Investigate main-thread freezes / slow pages with a real CPU profile instead of guessing. Use when a page locks up, the sidebar/cards go unresponsive, requests hang pending, a 'freeze' or 'jank' is reported, or you need to prove a perf fix worked (before/after). Drives a real browser via agent-browser, captures a Chrome DevTools profile, and parses it for the dominant hot frame — separating real app cost from profiler/dev-mode artifacts.

License 许可
MIT
所属仓库
gethamster/skills
最近更新
2026-11-05
Stars
★ 4
Forks
0

01 前言 Front Matter

name
hamster-cpu-profiling
version
1.0.0
description
Investigate main-thread freezes / slow pages with a real CPU profile instead of guessing. Use when a page locks up, the sidebar/cards go unresponsive, requests hang pending, a 'freeze' or 'jank' is reported, or you need to prove a perf fix worked (before/after). Drives a real browser via agent-browser, captures a Chrome DevTools profile, and parses it for the dominant hot frame — separating real app cost from profiler/dev-mode artifacts.

02 资源文件 5

03 SKILL.md 正文

Hamster CPU profiling — find the freeze before theorizing

A page freeze is a main-thread CPU block: one JavaScript task runs so long that paint, input, and pending fetches all stall behind it. You cannot fix it by reading code and guessing — the cost is rarely where it looks. Get a real CPU profile first, find the dominant frame, fix that, then re-profile to prove it.

First, classify the failure mode (see feedback_verify_failure_mode_before_fixing): a CPU hang (this skill) is different from a thrown error (error boundary) or a network stall (waterfall). The tell for a CPU hang: an in-page probe can't run during the block — you must measure from outside the page.

Tooling: agent-browser, NOT Playwright

Use the agent-browser CLI. It drives a persistent, auth-preserving browser session and exposes profiler start/stop. Playwright's per-test isolation makes warm-cache / post-deploy repro awkward, and you can't easily time round-trips from outside.

agent-browser --session-name <name> open "<url>"     # navigate (auth persists per session)
agent-browser --session-name <name> profiler start    # begin CPU profile (DETACHES the page)
agent-browser --session-name <name> profiler stop out.json
agent-browser --session-name <name> eval "1+1"        # round-trip probe

The method

1. Open the page and confirm it rendered

agent-browser --session-name perf open "http://localhost:8080/home/<account>/<page>"
agent-browser --session-name perf eval "document.querySelectorAll('<rows-selector>').length"

Session auth can expire — if you land on /auth/sign-in, fill input[type=email] / input[type=password] and click the submit button (snapshot -i -c to get its ref; refs are NOT stable across reloads, re-snapshot each time). Always go through the proxy port (8080), never raw Next (3000).

2. Detect the block from OUTSIDE (eval round-trip)

A CPU hang can't run an in-page timer, so measure the wall-clock of an eval round-trip from the shell:

for i in $(seq 1 20); do
  t0=$(node -e 'process.stdout.write(String(Date.now()))')
  agent-browser --session-name perf eval "1+1" >/dev/null 2>&1
  t1=$(node -e 'process.stdout.write(String(Date.now()))')
  echo "[$i] $((t1 - t0)) ms"
done

Baseline is ~160–200 ms. A block shows as seconds. (A reload-triggered first eval also includes navigation time — don't read that one as pure CPU; use the trace's task durations instead, step 5.)

3. Force the worst case (for local-first / stash pages)

Local-first pages (@kit/stash) resolve from IndexedDB + react-query. The expensive path is a cold resolve: the id-list is on disk but the entity rows are not (a post-deploy cache bust, or a large cold account). Reproduce it by deleting entity blobs while keeping the id-list, then reload. Stash realtime tiers have a 30s staleTime, so wait ~35s after load before reloading so the list actually refetches. See scripts/bust-stash-entities.js for the IndexedDB cursor.

⚠️ Local dev only. That helper deletes IndexedDB data — it's a repro tool for localhost, and self-aborts on any non-localhost origin. Never run it against a deployed environment.

4. Capture the profile (mind the detach + reload caveats)

profiler start detaches the page, so fire the reload AFTER starting, and background it — a foreground reload hangs ~2 min because analytics requests never let the page reach networkidle.

agent-browser --session-name perf profiler start
agent-browser --session-name perf reload >/dev/null 2>&1 &   # background
RPID=$!
sleep 9                                                        # capture window
agent-browser --session-name perf profiler stop trace.json
kill $RPID 2>/dev/null

5. Parse — and separate signal from artifact

The bundled scripts in scripts/ aggregate the trace. The cardinal rule: agent-browser's own instrumentation and React dev-mode logging are NOT your app's cost. Strip them or you'll chase ghosts:

  • (idle) / (program) / agentation* → agent-browser overhead. It also hooks setTimeout/clearTimeout, so native timer self-time is wildly inflated (~80µs/call vs ~1µs in prod). Use timer call counts as a signal, never their µs.
  • logComponentRender / logComponentEffect / measure / run → React dev-mode instrumentation, absent in production.
  • What's left — your app + library JS — is the real prod-relevant cost.
node scripts/longtasks.cjs trace.json        # GROUND TRUTH: longest main-thread tasks (a >50ms task janks; >200ms is a visible freeze)
node scripts/classify.cjs trace.json         # self-time split into app-JS vs artifacts; top prod-relevant frames
node scripts/callers.cjs trace.json setTimeout   # who calls a hot native fn (catches agentation inflation)
node scripts/profile-selftime.cjs trace.json     # raw self-time by function (no classification)

The longest-task number from longtasks.cjs is the user-facing truth and the metric to quote before/after. classify.cjs tells you which frame to attack.

6. Fix the dominant frame, then PROVE it

Re-run the exact same capture after the fix and compare longest-task + tasks>200ms + the top app-JS frames. Do not claim a fix without an after-profile showing the hot frame gone. A real example (briefs list, ~1000 items): longest task 620ms → 108ms, tasks >200ms 2 → 0, after replacing an N-observer useQueries with one cache subscription — the query-core observer frames vanished from the profile entirely.

Common traps

  • Trusting raw self-time. Native clearTimeout topped one profile at 196ms — but callers.cjs showed it was agent-browser's hook. Classify first.
  • Per-render JSON.stringify/join look guilty but profile at ~0ms — V8 is fast; the real cost was observer machinery + re-render count. Measure, don't assume.
  • Reading the post-reload first eval as CPU. It includes navigation; use trace task durations.
  • Dev vs prod skew. jsxDEV and React dev logging inflate render cost in dev. The structure of the cost (which subsystem, how many re-renders) transfers to prod; the absolute µs does not. For a prod-accurate number, profile a production build.

Scripts

All in scripts/ (plain Node, no deps). Handle both .cpuprofile and DevTools-trace (Profile/ProfileChunk) formats.

Script Answers
longtasks.cjs How bad is the block? (longest tasks, busy time, task count)
classify.cjs Where is the real cost? (app-JS vs artifact buckets, top frames)
callers.cjs <fn> Who calls this hot function? (de-attributes inflated native frames)
profile-selftime.cjs Raw self-time leaderboard (unclassified)
bust-stash-entities.js Force the cold-resolve worst case (eval body)

04 同仓库更多 Skills