web-perf-audit

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

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:

🚀 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

Prerequisites

📖 CLI Command Reference

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

/perf analyze — Full Audit