Running Lighthouse is easy. Reading what it gives back is the chore. I'd run the audit, squint at the JSON, try to work out which of forty audits actually mattered, and usually lose interest halfway. So I wrote a Claude Code slash command that runs the audit and reads the report for me. It took about 5 minutes to write and saves me 20+ minutes every time I check performance.
Doing it by hand
If you've never run Lighthouse from the command line, it looks like this:
npx lighthouse https://yoursite.com \
--output=json \
--output-path=/tmp/lighthouse-report.json \
--chrome-flags="--headless" \
--only-categories=performance
That dumps a ~500KB JSON blob. You can open it in Chrome DevTools, or pipe it through jq and pull out the handful of numbers you care about:
cat /tmp/lighthouse-report.json | jq '{
score: (.categories.performance.score * 100),
lcp: .audits["largest-contentful-paint"].displayValue,
cls: .audits["cumulative-layout-shift"].displayValue,
tbt: .audits["total-blocking-time"].displayValue
}'
Output:
{
"score": 55,
"lcp": "58.1 s",
"cls": "0",
"tbt": "0 ms"
}
A 58 second LCP. Lovely. The numbers tell me something is badly wrong and nothing about why. Finding out means digging through the full report, which is exactly the point where I used to give up and go do something else.
The slash command
Claude Code turns any markdown file in .claude/commands/ into a slash command, with $ARGUMENTS replaced by whatever you type after it. So the whole tool is one prompt file at .claude/commands/analyze-website-performance.md:
# Website Performance Analysis
Analyze the performance of `$ARGUMENTS` using Google Lighthouse.
## Steps
1. **Run Lighthouse audit**:
```bash
npx lighthouse $ARGUMENTS --output=json --output-path=/tmp/lighthouse-report.json --chrome-flags="--headless" --only-categories=performance
```
2. **Read the report** from `/tmp/lighthouse-report.json`
3. **Analyze and summarize**:
- Current performance score
- Each failing audit with its impact
- Specific fixes for each issue
- Estimated score improvement from each fix
## Output Format
### Performance Score: X/100
### Critical Issues (blocking 95+ score)
For each issue:
- **What**: The specific problem
- **Impact**: How many points this costs
- **Fix**: Exact steps to resolve
## Constraints
**Do not recommend changes that would:**
- Alter the DOM structure significantly
- Change the visual design
- Remove features or content
**Focus only on:**
- Asset optimization (compression, formats, sizing)
- Loading strategies (defer, async, preload, lazy loading)
- Caching and delivery
- Code efficiency (tree-shaking, code splitting)
The constraints section is there because ripping out half the page technically counts as a performance fix, and I didn't want that kind of advice. Assets and loading, nothing else.
Then run it:
claude
> /analyze-website-performance https://www.samratjha.com/
What comes back
An abridged run against my own site, from before I'd optimized anything:
## Performance Score: 55/100
### Critical Issues
### 1. Massive Image Files - Est. Savings: 15,654 KiB (~15.3 MB)
| Image | Current Size | Displayed At | Savings |
|-------|-------------|--------------|---------|
| ParallaxImageGallery.png | 8.87 MB | 431×230 px | 8.86 MB |
| bird-radio.png | 2.30 MB | 450×230 px | 2.29 MB |
**Fix**:
1. Convert all PNG images to WebP or AVIF format
2. Resize images to match display dimensions
3. Use `srcset` for responsive images
### 2. Unused JavaScript - Est. Savings: 258 KiB, 1,350ms
**What**: `index-d312cac4.js` (648 KB) has 41% unused code
**Fix**:
- Code-split Three.js and heavy dependencies
- Lazy-load the 3D planet component
The useful part is that it lines up the image dimensions in the DOM against the actual file sizes. My 8.87 MB PNG was being displayed at 431×230 pixels from a 2657×1890 source. Embarrassing, and I would have scrolled straight past it in the raw JSON.
Why bother with the middleman
Lighthouse already knows all of this. It just says it in a way that's hard to act on. The raw audit entry for those images:
{
"id": "image-delivery-insight",
"score": 0,
"displayValue": "Est savings of 15,654 KiB"
}
The same finding, after Claude has read the rest of the report:
ParallaxImageGallery.png:
- Current: 2657×1890 PNG (8.87 MB)
- Displayed: 431×230 px
- Target: 862×460 WebP (~50-100 KB)
- Savings: 8.86 MB (99% reduction)
"Est savings of 15,654 KiB" is a fact. A file name, a target size, and a format is a to-do item. I'll put off the first one for weeks. The second one I usually just do.
Gotchas
You need Chrome
Lighthouse drives a headless Chrome. On a server without Chrome installed, none of this works. The PageSpeed Insights API is the alternative, and I haven't bothered setting it up.
The JSON is huge
~500KB for a single page. If Claude reads the file whole, complex pages can blow through the context window. The prompt asks it to pull out only the relevant parts, which mostly works, but I've still watched it choke on really bloated reports.
Scores wobble
Network conditions, server load, the phase of the moon. I've seen ±5 points between consecutive runs, so a 3-point drop tells you nothing.
Mobile is the default
Lighthouse throttles like a mobile device unless you add --preset=desktop. Mobile is usually the worse of the two numbers.
You can add more categories (--only-categories=performance,accessibility,best-practices,seo) or point it at several URLs. It's a prompt template, so bend it however you like.