web-perf-audit

📖 English ·  简体中文 ·  繁體中文 ·  日本語 ·  한국어 ·  Español ·  Türkçe ·  Русский

Fixes that ship > advice that sits in a dashboard. Multi-Agent Web Performance Audit Pipeline — SCAN → ANALYZE → SCORE → REPORT. Not another Lighthouse wrapper. A complete audit-to-fix workflow with CWV impact estimates. Works with Claude Code, Cursor, VSCode Copilot, and any CI pipeline.

---

Why web-perf-audit

You run Lighthouse. It says LCP 4.2s, score 62. You stare at the screen. Now what?

Every tool tells you what's wrong. None of them tell you what to change, line by line, and why that specific change will work. web-perf-audit fills that gap — it runs a multi-agent pipeline that:

• Scans your page with Lighthouse + Puppeteer for raw CWV metrics
• Analyzes across 5 dimensions in parallel (rendering path, resource hints, images, fonts, JS bundles)
• Scores every finding against its real Core Web Vitals impact (not discovery order)
• Generates a prioritized report with copy-pasteable fixes, each backlinked to the web.dev principle that explains it

"The goal isn't a 100/100 Lighthouse score — it's a page that loads fast and responds instantly for real users."

---

✨ Core Features

🎯 web.dev Standards-Aligned

Every audit rule traces back to web.dev/learn/performance. LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1. Not our opinions — Google's thresholds, measured at p75.

🤖 Multi-Agent Audit Pipeline

5 specialized agents run in parallel: Project Scanner, Resource Analyzer, Metric Scorer, Change Predictor, and Optimization Planner. Each does one thing well.

🔧 Deterministic + Measured Hybrid

Static checks (missing defer, wrong font-display, absent srcset) are deterministic — same page, same result. Runtime metrics (LCP, TBT) come from real browser measurement via Lighthouse + Puppeteer.

📊 Offline Dashboard

Interactive Chart.js dashboard with score ring, CWV cards, category breakdown, and priority-ordered issue list. Works entirely offline — no external API calls after audit.

🔁 Incremental Git-Aware Audits

SHA256 fingerprint caching skips unchanged pages. perf-diff compares two audits across branches — catch performance regressions before they merge, not after.

🧩 Cross-Platform & Multi-IDE

Runs on macOS / Linux / Windows. Native Claude Code skill, plus Cursor rules, VSCode Copilot instructions. One-liner CI integration for GitHub Actions, GitLab CI, Jenkins.

---

🏗 Architecture

Multi-Agent Audit Pipeline

graph TB
    subgraph Trigger["🔔 Trigger"]
        CLI["/perf analyze URL"]
        CI["git push / PR opened"]
        IDE["Claude Code / Cursor / Copilot"]
    end

    subgraph Stage1["Stage 1 — SCAN"]
        Scanner["🔍 Project Scanner Agent<br/>· Framework detection (Vite/Webpack/Next)<br/>· Build artifact discovery<br/>· .webperfignore filtering"]
        LH["📡 Lighthouse + Puppeteer<br/>· LCP / CLS / INP / TBT / FCP<br/>· CrUX field data (PSI optional)"]
    end

    subgraph Stage2["Stage 2 — ANALYZE (5 agents parallel)"]
        CRP["📐 Critical Path Agent<br/>render-blocking CSS/JS<br/>request chain depth<br/>DOM size audit"]
        Hints["💡 Resource Hints Agent<br/>preload/prefetch/preconnect<br/>missing crossorigin<br/>sync script detection"]
        Img["🖼 Image Audit Agent<br/>WebP/AVIF detection<br/>srcset/sizes check<br/>LCP image optimization"]
        Font["🔤 Font Audit Agent<br/>font-display analysis<br/>woff2 format check<br/>subsetting audit"]
        JS["⚡ JS Bundle Agent<br/>Puppeteer Coverage API<br/>Long Task observer<br/>third-party attribution"]
    end

    subgraph Stage3["Stage 3 — SCORE"]
        Scorer["⚖️ Metric Scorer Agent<br/>· CWV impact weighting<br/>· severity × reach multiplier<br/>· P0 (≥20) / P1 (10-19) / P2 (<10)"]
    end

    subgraph Stage4["Stage 4 — REPORT"]
        Reporter["📝 Optimization Plan Agent<br/>· match fix templates<br/>· generate before/after code<br/>· estimate millisecond savings"]
        Output["📦 Output<br/>audit-report.json<br/>report.md<br/>dashboard.html"]
    end

    subgraph Diff["🔄 Incremental / Diff Mode"]
        Fingerprint["SHA256 fingerprint cache"]
        Predictor["🔮 Change Predictor Agent<br/>· Git diff → impact estimation<br/>· regression risk flagging"]
    end

    CLI --> Scanner & LH
    CI --> Scanner & LH
    IDE --> Scanner & LH
    Scanner & LH --> CRP & Hints & Img & Font & JS
    CRP & Hints & Img & Font & JS --> Scorer
    Scorer --> Reporter --> Output
    Output --> Fingerprint
    Fingerprint --> Predictor
    Predictor --> Output

Layered Design

Layer	Responsibility	Technology
Trigger	CLI / CI / IDE invocation	Claude Code Skill, GitHub Actions, Cursor rules
Scan	Raw data collection + project discovery	Lighthouse CLI, Puppeteer, PageSpeed Insights API
Analyze	5-dimension static + runtime analysis	Python 3.8+ (HTMLParser, urllib), Node.js (Puppeteer)
Score	CWV-weighted priority calculation	Python scoring engine (7-category × severity multipliers)
Generate	Report rendering + fix templating	Python (Markdown/JSON), Chart.js (dashboard HTML)
Diff	Incremental caching + cross-branch comparison	SHA256 fingerprinting, JSON structural diff

How we adapted Understand-Anything's pipeline

Understand-Anything pioneered the multi-agent code analysis pipeline — project-scanner → file-analyzer → architecture-analyzer → tour-builder → graph-reviewer. We adapted this pattern for web performance:

Understand-Anything	web-perf-audit	Adaptation
project-scanner (language/framework detection)	Project Scanner Agent (build tool detection, .webperfignore)	Code structure → page structure
file-analyzer (function/class extraction)	Resource Analyzer Agent (HTML/CSS/JS static audit)	AST nodes → DOM + CSSOM nodes
architecture-analyzer (layer tagging)	Metric Scorer Agent (CWV impact scoring)	Architecture layers → performance dimensions
tour-builder (guided walkthrough)	Optimization Plan Agent (fix generation)	Code tour → fix checklist
graph-reviewer (integrity check)	Change Predictor Agent (regression detection)	Schema validation → performance regression

---

🚀 Quick Start

4 steps from zero to audit report

# 1. Clone
git clone https://github.com/EVEDensity/web-perf-audit.git && cd web-perf-audit

# 2. Install dependencies
npm install -g lighthouse && npm install

# 3. Run your first audit
python scripts/fetch_metrics.py "https://example.com" --output-dir .web-perf
python scripts/analyze_critical_path.py .web-perf/metrics.json -o .web-perf/critical-path.json &
python scripts/check_resource_hints.py "https://example.com" -o .web-perf/resource-hints.json &
python scripts/audit_images.py "https://example.com" -o .web-perf/images.json &
python scripts/audit_fonts.py "https://example.com" -o .web-perf/fonts.json &
node scripts/audit_js_bundles.js "https://example.com" --output .web-perf/js-bundles.json &
wait
python scripts/score_and_report.py "https://example.com" --output-dir .web-perf --format all

# 4. Open the dashboard
open .web-perf/dashboard.html   # macOS
start .web-perf/dashboard.html  # Windows
xdg-open .web-perf/dashboard.html  # Linux

Or use the one-liner (Claude Code)

/plugin install web-perf-audit@EVEDensity/web-perf-audit
/perf analyze https://example.com

---

📦 Installation

macOS / Linux

# One-shot install
curl -fsSL https://raw.githubusercontent.com/EVEDensity/web-perf-audit/main/install.sh | bash

# Or step by step
git clone https://github.com/EVEDensity/web-perf-audit.git ~/.web-perf-audit
cd ~/.web-perf-audit
npm install -g lighthouse
npm install
echo 'alias perf-audit="python ~/.web-perf-audit/scripts/fetch_metrics.py"' >> ~/.bashrc

Windows (PowerShell)

# One-shot install
iwr -Uri https://raw.githubusercontent.com/EVEDensity/web-perf-audit/main/install.ps1 -OutFile install.ps1; ./install.ps1

# Or step by step
git clone https://github.com/EVEDensity/web-perf-audit.git $env:USERPROFILE\.web-perf-audit
cd $env:USERPROFILE\.web-perf-audit
npm install -g lighthouse
npm install

IDE Plugin Setup

IDE	How to enable
Claude Code	/plugin install web-perf-audit@EVEDensity/web-perf-audit
Cursor	Add .cursorrules: @web-perf-audit analyze on save
VSCode Copilot	Add to .github/copilot-instructions.md: Use web-perf-audit for performance reviews
Codex / Gemini CLI	Copy SKILL.md to your skills directory

Prerequisites

Dependency	Version	Required For
Python	≥ 3.8	All analysis + scoring scripts
Node.js	≥ 18	Lighthouse CLI + Puppeteer (JS audit)
Lighthouse	latest (npm i -g lighthouse)	CWV metric collection
Puppeteer	^22.0.0 (npm i puppeteer)	JS Coverage + Long Task API

---

📖 CLI Command Reference

All commands follow the /perf namespace. Each entry shows: purpose, example, flags, and output.

/perf analyze — Full Audit