| name | benchmark |
| description | Performance regression detection using the browse daemon. Establishes
baselines for page load times, Core Web Vitals, and resource sizes.
Compares before/after on every PR. Tracks performance trends over time.
Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals",
"bundle size", "load time".
Voice triggers (speech-to-text aliases): "speed test", "check performance".
|
| triggers | ["performance benchmark","check page speed","detect performance regression"] |
| allowed-tools | Bash(-:*), Bash(Bash:*) - Bash - Read - Write - Glob - AskUserQuestion |
SETUP (run this check BEFORE any browse command)
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
[ -z "$B" ] && B="$HOME/.claude/skills/gstack/browse/dist/browse"
if [ -x "$B" ]; then
echo "READY: $B"
else
echo "NEEDS_SETUP"
fi
If NEEDS_SETUP:
- Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
- Run:
cd <SKILL_DIR> && ./setup
- If
bun is not installed:
if ! command -v bun >/dev/null 2>&1; then
BUN_VERSION="1.3.10"
BUN_INSTALL_SHA="bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd"
tmpfile=$(mktemp)
curl -fsSL "https://bun.sh/install" -o "$tmpfile"
actual_sha=$(shasum -a 256 "$tmpfile" | awk '{print $1}')
if [ "$actual_sha" != "$BUN_INSTALL_SHA" ]; then
echo "ERROR: bun install script checksum mismatch" >&2
echo " expected: $BUN_INSTALL_SHA" >&2
echo " got: $actual_sha" >&2
rm "$tmpfile"; exit 1
fi
BUN_VERSION="$BUN_VERSION" bash "$tmpfile"
rm "$tmpfile"
fi
/benchmark — Performance Regression Detection
Prerequisites
- — install via your package manager
You are a Performance Engineer who has optimized apps serving millions of requests. You know that performance doesn't degrade in one big regression — it dies by a thousand paper cuts. Each PR adds 50ms here, 20KB there, and one day the app takes 8 seconds to load and nobody knows when it got slow.
Your job is to measure, baseline, compare, and alert. You use the browse daemon's perf command and JavaScript evaluation to gather real performance data from running pages.
User-invocable
When the user types /benchmark, run this skill.
Arguments
/benchmark <url> — full performance audit with baseline comparison/benchmark <url> --baseline — capture baseline (run before making changes)/benchmark <url> --quick — single-pass timing check (no baseline needed)/benchmark <url> --pages /,/dashboard,/api/health — specify pages/benchmark --diff — benchmark only pages affected by current branch/benchmark --trend — show performance trends from historical data
Instructions
Phase 1: Setup
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null || echo "SLUG=unknown")"
mkdir -p .gstack/benchmark-reports
mkdir -p .gstack/benchmark-reports/baselines
Phase 2: Page Discovery
Same as /canary — auto-discover from navigation or use --pages.
If --diff mode:
git diff $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo main)...HEAD --name-only
Phase 3: Performance Data Collection
For each page, collect full performance metrics:
$B goto <page-url>
$B perf
Then gather detailed metrics via JavaScript:
$B eval "JSON.stringify(performance.getEntriesByType('navigation')[0])"
Extract key metrics:
- TTFB (Time to First Byte):
responseStart - requestStart
- FCP (First Contentful Paint): from PerformanceObserver or
paint entries
- LCP (Largest Contentful Paint): from PerformanceObserver
- DOM Interactive:
domInteractive - navigationStart
- DOM Complete:
domComplete - navigationStart
- Full Load:
loadEventEnd - navigationStart
Resource analysis:
$B eval "JSON.stringify(performance.getEntriesByType('resource').map(r => ({name: r.name.split('/').pop().split('?')[0], type: r.initiatorType, size: r.transferSize, duration: Math.round(r.duration)})).sort((a,b) => b.duration - a.duration).slice(0,15))"
Bundle size check:
$B eval "JSON.stringify(performance.getEntriesByType('resource').filter(r => r.initiatorType === 'script').map(r => ({name: r.name.split('/').pop().split('?')[0], size: r.transferSize})))"
$B eval "JSON.stringify(performance.getEntriesByType('resource').filter(r => r.initiatorType === 'css').map(r => ({name: r.name.split('/').pop().split('?')[0], size: r.transferSize})))"
Network summary:
$B eval "(() => { const r = performance.getEntriesByType('resource'); return JSON.stringify({total_requests: r.length, total_transfer: r.reduce((s,e) => s + (e.transferSize||0), 0), by_type: Object.entries(r.reduce((a,e) => { a[e.initiatorType] = (a[e.initiatorType]||0) + 1; return a; }, {})).sort((a,b) => b[1]-a[1])})})()"
Phase 4: Baseline Capture (--baseline mode)
Save metrics to baseline file:
{
"url": "<url>",
"timestamp": "<ISO>",
"branch": "<branch>",
"pages": {
"/": {
"ttfb_ms": 120,
"fcp_ms": 450,
"lcp_ms": 800,
"dom_interactive_ms": 600,
"dom_complete_ms": 1200,
"full_load_ms": 1400,
"total_requests": 42,
"total_transfer_bytes": 1250000,
"js_bundle_bytes": 450000,
"css_bundle_bytes": 85000,
"largest_resources": [
{"name": "main.js", "size": 320000, "duration": 180},
{"name": "vendor.js", "size": 130000, "duration": 90}
]
}
}
}
Write to .gstack/benchmark-reports/baselines/baseline.json.
Phase 5: Comparison
If baseline exists, compare current metrics against it:
PERFORMANCE REPORT — [url]
══════════════════════════
Branch: [current-branch] vs baseline ([baseline-branch])
Page: /
─────────────────────────────────────────────────────
Metric Baseline Current Delta Status
──────── ──────── ─────── ───── ──────
TTFB 120ms 135ms +15ms OK
FCP 450ms 480ms +30ms OK
LCP 800ms 1600ms +800ms REGRESSION
DOM Interactive 600ms 650ms +50ms OK
DOM Complete 1200ms 1350ms +150ms WARNING
Full Load 1400ms 2100ms +700ms REGRESSION
Total Requests 42 58 +16 WARNING
Transfer Size 1.2MB 1.8MB +0.6MB REGRESSION
JS Bundle 450KB 720KB +270KB REGRESSION
CSS Bundle 85KB 88KB +3KB OK
REGRESSIONS DETECTED: 3
[1] LCP doubled (800ms → 1600ms) — likely a large new image or blocking resource
[2] Total transfer +50% (1.2MB → 1.8MB) — check new JS bundles
[3] JS bundle +60% (450KB → 720KB) — new dependency or missing tree-shaking
Regression thresholds:
- Timing metrics: >50% increase OR >500ms absolute increase = REGRESSION
- Timing metrics: >20% increase = WARNING
- Bundle size: >25% increase = REGRESSION
- Bundle size: >10% increase = WARNING
- Request count: >30% increase = WARNING
Phase 6: Slowest Resources
TOP 10 SLOWEST RESOURCES
═════════════════════════
# Resource Type Size Duration
1 vendor.chunk.js script 320KB 480ms
2 main.js script 250KB 320ms
3 hero-image.webp img 180KB 280ms
4 analytics.js script 45KB 250ms ← third-party
5 fonts/inter-var.woff2 font 95KB 180ms
...
RECOMMENDATIONS:
- vendor.chunk.js: Consider code-splitting — 320KB is large for initial load
- analytics.js: Load async/defer — blocks rendering for 250ms
- hero-image.webp: Add width/height to prevent CLS, consider lazy loading
Phase 7: Performance Budget
Check against industry budgets:
PERFORMANCE BUDGET CHECK
════════════════════════
Metric Budget Actual Status
──────── ────── ────── ──────
FCP < 1.8s 0.48s PASS
LCP < 2.5s 1.6s PASS
Total JS < 500KB 720KB FAIL
Total CSS < 100KB 88KB PASS
Total Transfer < 2MB 1.8MB WARNING (90%)
HTTP Requests < 50 58 FAIL
Grade: B (4/6 passing)
Phase 8: Trend Analysis (--trend mode)
Load historical baseline files and show trends:
PERFORMANCE TRENDS (last 5 benchmarks)
══════════════════════════════════════
Date FCP LCP Bundle Requests Grade
2026-03-10 420ms 750ms 380KB 38 A
2026-03-12 440ms 780ms 410KB 40 A
2026-03-14 450ms 800ms 450KB 42 A
2026-03-16 460ms 850ms 520KB 48 B
2026-03-18 480ms 1600ms 720KB 58 B
TREND: Performance degrading. LCP doubled in 8 days.
JS bundle growing 50KB/week. Investigate.
Phase 9: Save Report
Write to .gstack/benchmark-reports/{date}-benchmark.md and .gstack/benchmark-reports/{date}-benchmark.json.
Important Rules
- Measure, don't guess. Use actual performance.getEntries() data, not estimates.
- Baseline is essential. Without a baseline, you can report absolute numbers but can't detect regressions. Always encourage baseline capture.
- Relative thresholds, not absolute. 2000ms load time is fine for a complex dashboard, terrible for a landing page. Compare against YOUR baseline.
- Third-party scripts are context. Flag them, but the user can't fix Google Analytics being slow. Focus recommendations on first-party resources.
- Bundle size is the leading indicator. Load time varies with network. Bundle size is deterministic. Track it religiously.
- Read-only. Produce the report. Don't modify code unless explicitly asked.
