What you get
A repo-ready brief that turns abstract Lighthouse output into work Claude Code can act on.
Real fix suggestions
Each failing audit comes with a concrete, prescriptive action across Performance, Accessibility, Best Practices, SEO and Agentic Browsing.
Top offenders, ranked
The exact URLs, selectors, and HTML snippets responsible, with potential savings in ms or KB.
One-click handoff
Open Claude Code with the full plan pre-loaded, or copy / download the CLAUDE.md.
Agentic Browsing score
Google's new Lighthouse category: can AI agents read and operate your page? Covers the accessibility tree, llms.txt, WebMCP tools and the ARD manifest.
How it works
From URL to merged PR in four steps.
- Paste a URL. Pick mobile or desktop strategy.
- We call PageSpeed Insights v5. Lighthouse runs in the cloud, takes 10–30 seconds.
- Review failing audits. Every audit below 0.9 gets a fix suggestion and offender list.
- Hand off to Claude Code. Open it with the prompt loaded, or drop CLAUDE.md into your repo.
Common Lighthouse audits, explained
Plain-English deep-dives on the audits we see most often. Browse the full reference library →
Largest Contentful Paint (LCP)
How quickly the biggest visible element renders. Good: under 2.5 s. Preload, drop lazy-loading, fix render-blocking.
Total Blocking Time (TBT)
Main-thread blocking by long JS tasks. Good: under 200 ms. Code-split, defer third-parties, Web Workers.
Cumulative Layout Shift (CLS)
Unexpected layout movement. Good: under 0.1. Set image dimensions, reserve ad space, stabilize fonts.
Reduce unused JavaScript
Bytes shipped but never executed. Code-split per route, tree-shake imports, audit third-party scripts.
Render-blocking resources
CSS and synchronous JS that delays first paint. Inline critical CSS, defer the rest.
Document does not have a main landmark
Screen reader users can't jump to primary content. Fix: wrap content in <main>.
Links do not have a discernible name
Icon-only links announced as just "link". Fix: add aria-label or hidden text.
Buttons do not have an accessible name
Icon-only buttons announced as just "button". Fix: add aria-label and hide the icon.
aria-hidden elements contain focusable descendents
Hidden drawers and carousel slides still in the tab order. Fix: add inert to the hidden container.
Color contrast
Text fails WCAG AA contrast. Aim for 4.5:1 for body, 3:1 for large text and UI.
Heading order
Skipped heading levels (h1 → h3) break the semantic outline. Use CSS for sizing, not tag choice.
Image alt attributes
Missing alt breaks accessibility and image SEO. Empty alt is OK for decorative images.
Meta description
Missing description hurts SERP click-through. Add 140–160 chars summarizing the page.
Canonical tag
Fix a non-canonical URL or "canonical missing" error. Add one self-referential, absolute rel=canonical per page to consolidate duplicate-URL ranking signals.
Title element
The strongest on-page SEO signal and the SERP headline. One unique 50–60 char title per page.
hreflang tag
Fix invalid or missing hreflang for multi-language sites. Self-reference, x-default, reciprocal return links.
Links do not have descriptive text
"Click here" and "learn more" anchors waste the signal. Fix: name the destination.
Minimize main-thread work
The main thread was busy too long to answer taps. Read the category split: Script Evaluation is usually the largest row.
Links are not crawlable
href="#", javascript:void(0) and click handlers on divs. Googlebot cannot follow them. Fix: a real href.
Next-gen image formats
JPEG/PNG that would be smaller as WebP or AVIF. Convert, serve with <picture>, or use an image CDN.
First Contentful Paint (FCP)
When the first text or image paints. Good: under 1.8 s. Server time, render-blocking, fonts.
Enable text compression
Text served without gzip/Brotli. A one-line server change cuts transfer size 60–80%.
Reduce unused CSS
Stylesheets with selectors the page never uses. Strip with PurgeCSS or Tailwind JIT, inline critical, defer the rest.
Use HTTPS
HTTP or mixed content fails this. Install TLS, 301 to HTTPS, fix insecure subresources, add HSTS.
font-display: swap
“Ensure text remains visible during webfont load.” One CSS descriptor stops invisible text; when to use swap, fallback, or optional.
Speed Index
How quickly the page becomes visually complete. Good: under 3.4 s. Fix render-blocking, fonts, and hero images.
Tap targets
“Tap targets are not sized appropriately.” Lighthouse retired it; WCAG 2.5.8 did not. The numbers that still apply.
Avoid multiple page redirects
“Avoid multiple page redirects.” Each hop costs a round trip. Collapse the chain, and fix too many redirects loops.
Efficient cache policy
“Serve static assets with an efficient cache policy.” Fingerprint filenames, set a one-year max-age, keep HTML fresh.
Errors in console
“Browser errors were logged to the console.” 404s, uncaught TypeErrors, CORS, CSP, and mixed content, with the fix for each.
Legacy JavaScript
“Avoid serving legacy JavaScript to modern browsers.” Modern browserslist, polyfills only where needed, ES2020 targets.
Forced reflow
“Forced reflow while executing JavaScript.” Batch layout reads before writes, defer to requestAnimationFrame, use observers.
Network dependency tree
“Avoid chaining critical requests.” Shorten the longest chain: preload fonts, drop @import, inline critical CSS, trim preconnects.
Issues in the DevTools Issues panel
Cookie, mixed content, CSP, and cross-origin issues. Fix the ones on your domain, decide on the third-party ones.
Unload event deprecated
“Unload event listeners are deprecated and will be removed.” Replace with pagehide and visibilitychange, fix old jQuery and vendor rows.
ERR_BLOCKED_BY_CLIENT
“Failed to load resource: net::ERR_BLOCKED_BY_CLIENT.” Who blocked the request, how to get a clean run, how to survive blockers.
FAQ
Common questions about CLAUDE.md, Lighthouse, and Core Web Vitals.
What is CLAUDE.md?
CLAUDE.md is a plain markdown file Claude Code reads at the root of your repository to understand the project context. This tool generates one scoped to your failing Lighthouse audits, including the throttling profile used, third-party impact, main-thread breakdown, and the list of currently passing audits so the agent doesn't regress them.
How does the “Ask Claude” button work?
It opens Claude Code via the claude://code/new deep link with the generated fix plan pre-filled as the initial prompt. You need the Claude Code desktop app installed for the deep link to resolve.
Which audits does this cover?
All five Lighthouse categories: Performance, Accessibility, Best Practices, SEO, and Agentic Browsing (how well AI agents can read and operate the page: accessibility tree, llms.txt, WebMCP tools). Any audit scoring below 0.9 is included with an actionable fix suggestion and a ranked offender list.
How do I fix Lighthouse performance issues?
Start with the worst-scoring audits. Common wins: defer non-critical JavaScript, preload the LCP image, set explicit width and height on images to prevent layout shift, enable text compression at the server or CDN, eliminate render-blocking CSS, and remove unused third-party scripts. This tool ranks offenders by potential savings (in ms or KB) so you fix the highest-impact issues first.
What are Core Web Vitals?
Core Web Vitals are three user-experience metrics Google uses as ranking signals: Largest Contentful Paint (LCP) under 2.5 s, Interaction to Next Paint (INP) under 200 ms, and Cumulative Layout Shift (CLS) under 0.1. Lighthouse and PageSpeed Insights report these alongside the audits that affect them.
Is there a Chrome Extension?
Yes. Install Lighthouse-MD from the Chrome Web Store. It analyzes the active tab with one click, no URL copy-pasting. Like the web app, it audits through Google PageSpeed Insights, so the page must be publicly reachable.
Can Claude Code actually fix Lighthouse audits?
Yes, given proper context. The CLAUDE.md this tool generates is designed specifically as agent context, it includes the throttling profile, prescriptive fix per audit, ranked offenders, and a "do not regress" list of currently passing audits. Most audits in Performance, Accessibility, Best Practices, and SEO can be resolved by Claude Code with this brief as input.
What is a good Lighthouse score?
Lighthouse uses three thresholds per category: 90–100 Good (green), 50–89 Needs Improvement (orange), 0–49 Poor (red). For SEO ranking and Core Web Vitals, aim for 90+ on Performance with all three Core Web Vitals in the Good range.
What is Largest Contentful Paint (LCP)?
LCP measures how quickly the largest visible element (usually the hero image or main heading) renders. Aim for under 2.5 seconds. Common fixes: preload the LCP image, avoid lazy-loading it, reduce server response time, eliminate render-blocking CSS.
What is Total Blocking Time (TBT)?
TBT measures how long the main thread is blocked by long JavaScript tasks during page load. Aim for under 200 ms. Fixes: code-split heavy bundles, defer non-critical scripts, replace synchronous third-party scripts, move heavy work to Web Workers.
What is Cumulative Layout Shift (CLS)?
CLS measures unexpected layout movement during page load. Aim for under 0.1. Fixes: set explicit width and height on images and embeds, reserve space for dynamically inserted content like ads, avoid inserting content above existing content unless triggered by user action.
Does this work on staging or localhost?
No. Google PageSpeed Insights runs the audit from Google's servers, so the URL must be publicly reachable over HTTPS. This applies to the web app and the Chrome Extension. For localhost or a private staging site, run Lighthouse in Chrome DevTools, or analyze a public preview deploy (for example a Vercel or Netlify preview URL).
How long does an analysis take?
Typically 10–30 seconds, depending on the page complexity and Google's queue. The audit runs in Google's cloud, not in your browser, so it doesn't consume your bandwidth or CPU.
Is the data I submit private?
The URL you submit is sent to Google PageSpeed Insights to run the audit. It is not stored on our servers. See the privacy policy for full details. No account is required and we do not collect personal data.
How accurate are the “Top offenders” lists?
They come straight from Lighthouse's own audit results. We surface the first few items per audit so the brief stays actionable rather than exhaustive, Claude Code can use the patterns to find similar issues across the codebase.