Lighthouse

Lighthouse Optimization Loop

Method: 3 mobile + 3 desktop runs per audit, averaged for reliability. After each code change, re-audit AND visually verify the page with chrome-devtools MCP to catch regressions.

---

Setup

1. Parse URL from $ARGUMENTS. If no URL, ask the user. Default: http://localhost:3000

1. Verify prerequisites:

``bash lighthouse --version # CLI must be installed for the batched 3x3 protocol ` If lighthouse is missing: npm install -g lighthouse The chrome-devtools MCP is shipped by default; if missing, see mcp-configs/recommended.json`.

1. Create results directory:

``bash mkdir -p ~/.claude/tmp/lighthouse ``

1. Take baseline screenshots before any changes:

• mcp__chrome-devtools__navigate_page (type: "url", url: ``)
• mcp__chrome-devtools__take_screenshot

Describe the current layout, key elements, and visual state. This is your visual baseline — you will compare against it after every change to catch regressions.

1. Confirm with user: Show the URL, confirm the dev server is running, ask if there are specific pages or routes to audit beyond the main URL.

---

Audit Protocol

Each audit consists of 3 mobile + 3 desktop runs, averaged per category.

Run the audits

# Mobile runs (Lighthouse default is mobile)
for i in 1 2 3; do
  lighthouse  \
    --output=json \
    --output-path=~/.claude/tmp/lighthouse/mobile-$i.json \
    --chrome-flags="--headless --no-sandbox" \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done

# Desktop runs
for i in 1 2 3; do
  lighthouse  \
    --output=json \
    --output-path=~/.claude/tmp/lighthouse/desktop-$i.json \
    --chrome-flags="--headless --no-sandbox" \
    --preset=desktop \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done

Extract scores

For each JSON result file:

cat ~/.claude/tmp/lighthouse/mobile-1.json | \
  jq '{
    performance: (.categories.performance.score * 100),
    accessibility: (.categories.accessibility.score * 100),
    bestPractices: (.categories["best-practices"].score * 100),
    seo: (.categories.seo.score * 100)
  }'

Compute averages

Average the 3 runs per category for both mobile and desktop. Report as:

## Audit Results

| Category | Mobile (avg) | Desktop (avg) |
|----------|-------------|---------------|
| Performance | XX | XX |
| Accessibility | XX | XX |
| Best Practices | XX | XX |
| SEO | XX | XX |

Extract failing audits

From the JSON, find specific audits that failed or scored poorly:

cat ~/.claude/tmp/lighthouse/mobile-1.json | \
  jq '.audits | to_entries[] | select(.value.score != null and .value.score  **Autonomous mode:** to drive this loop turn-by-turn without re-prompting, set
> `/goal mobile and desktop scores in all four categories meet their targets, or stop after 20 rounds`.
> A goal evaluator (Haiku by default) reads the audit table after each turn and decides whether to continue.
> See [/goal docs](https://code.claude.com/docs/en/goal).

LOOP until all scores >= 90 or user interrupts:

1. IDENTIFY the lowest-scoring category and its top failing audits

• Read the Lighthouse audit details for specific recommendations
• Cross-reference with the project's performance rules

1. PLAN one targeted fix

• Focus on the highest-impact failing audit
• One fix at a time — never batch multiple unrelated changes
• Common fixes by audit:

• render-blocking-resources → async/defer scripts, inline critical CSS • largest-contentful-paint → priority attribute, preload, optimize image • cumulative-layout-shift → explicit dimensions, font-display • unused-javascript → dynamic imports, code splitting • uses-responsive-images → srcSet + sizes, next/image (satus) or `/vite-imagetools` (novus), proper dimensions • uses-text-compression → verify gzip/brotli enabled • image-size-responsive → width/height attributes • unminified-javascript → check build config • dom-size → reduce DOM nodes, virtualize lists • third-party-summary → defer/lazy-load third-party scripts • font-display → font-display: swap or optional • offscreen-images → loading="lazy" (NOT on above-fold/LCP images)

1. IMPLEMENT the fix

• Edit the relevant source files
• Keep changes minimal and focused

1. VERIFY BUILD

• Run the project build to ensure no compilation errors
• If TypeScript project: tsc --noEmit first

1. VISUAL REGRESSION CHECK

• mcp__chrome-devtools__navigate_page to the same URL
• mcp__chrome-devtools__take_screenshot
• Compare against the baseline screenshot:

• Layout intact? (same general structure, no collapsed/missing sections) • Content visible? (text, images, interactive elements still present) • Styling correct? (colors, spacing, typography not broken) • Functionality preserved? (interactive elements still look clickable)

• If regression detected: REVERT the change immediately and try a different approach
• Also check critical user flows if the change affects interactive elements:
• mcp__chrome-devtools__take_snapshot (a11y tree — confirms interactive elements are present, returns uids)
• mcp__chrome-devtools__take_screenshot (visual verification)

1. RE-AUDIT

• Run full audit protocol again (3 mobile + 3 desktop)
• Compare against previous scores

1. LOG RESULTS

• Append to ~/.claude/tmp/lighthouse/results.tsv:

round mobileperf desktopperf mobilea11y desktopa11y status description

• Status: "kept" (scores improved), "reverted" (regression or no improvement)

1. REPORT

• Show score delta: "Performance: 72 → 85 (+13)"
• Show what was changed and why
• Show the current failing audits for the next round

1. CONTINUE to next round

---

## Visual Regression Protocol

This is the critical safety net. Performance changes MUST NOT break the UI.

### After every code change:

1. **Navigate:** `mcp__chrome-devtools__navigate_page` (type: "url", url: ``)
2. **Screenshot:** `mcp__chrome-devtools__take_screenshot`
3. **Compare** against baseline:
   - Is the page layout the same structure?
   - Are all visible elements still present?
   - Is text readable and properly styled?
   - Are images displaying correctly?
   - Are interactive elements (buttons, forms, nav) visually intact?

### Regression = immediate revert

If any visual regression is detected:
1. `git checkout -- ` to revert
2. Log status as "reverted (visual regression)" in results.tsv
3. Try an alternative approach to the same audit issue
4. NEVER accept a performance improvement that breaks the UI

### Multi-page checks

If the user specified multiple URLs/routes, check ALL of them after each change. A fix that improves the homepage but breaks a subpage is still a regression.

---

## Targets

Default targets (override by telling the agent different ones):

| Category | Mobile | Desktop |
|----------|--------|---------|
| Performance | >= 90 | >= 95 |
| Accessibility | >= 95 | >= 95 |
| Best Practices | >= 95 | >= 95 |
| SEO | >= 95 | >= 95 |

The loop continues until ALL categories on BOTH mobile and desktop meet their targets, or the user interrupts.

---

## Core Web Vitals Focus

When Performance score is low, prioritize these metrics:

| Metric | Target | What to Fix |
|--------|--------|-------------|
| LCP 
Updated: 

## Current Scores
| Category | Mobile | Desktop | Target | Status |
|----------|--------|---------|--------|--------|
| Performance | XX | XX | 90/95 | pass/fail |
| Accessibility | XX | XX | 95/95 | pass/fail |
| Best Practices | XX | XX | 95/95 | pass/fail |
| SEO | XX | XX | 95/95 | pass/fail |

## Progress (baseline → current)
| Category | Mobile | Desktop |
|----------|--------|---------|
| Performance | 62 → 91 (+29) | 78 → 96 (+18) |
| ... |

## Changes Applied
| Round | Fix | Mobile Perf Delta | Visual QA |
|-------|-----|-------------------|-----------|
| 1 | Added priority to hero image | +12 | pass |
| 2 | Deferred analytics script | +8 | pass |
| 3 | Added font-display: swap | +3 | pass |

## Remaining Issues
Top failing audits still to address...

---

Completion

When all targets are met:

1. Print final score summary with deltas from baseline
2. List all changes made (files modified and why)
3. Suggest running a final full visual QA: /qa
4. Do NOT auto-commit — let the user review the changes first

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: darkroomengineering
• Source: darkroomengineering/cc-settings
• License: MIT

Install and usage instructions live in the source repository linked above.