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
- 最近更新
- 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
- 脚本scripts/bust-stash-entities.js2.5 KB
- 脚本scripts/callers.cjs2.2 KB
- 脚本scripts/classify.cjs2.8 KB
- 脚本scripts/longtasks.cjs1.2 KB
- 脚本scripts/profile-selftime.cjs3.1 KB
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 hookssetTimeout/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
clearTimeouttopped one profile at 196ms — butcallers.cjsshowed it was agent-browser's hook. Classify first. - Per-render
JSON.stringify/joinlook 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.
jsxDEVand 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
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.