# lighthouse-md.com

> Free Lighthouse audit tool that turns PageSpeed Insights results into a CLAUDE.md fix plan for Claude Code. Generates structured briefs covering Performance, Accessibility, Best Practices, and SEO audits with prescriptive fixes and offender lists.

This site has two parts: an interactive analyzer at the root, and a library of in-depth explainer pages at `/audits/`. The explainer pages are mirrored in markdown for easier consumption by LLMs and AI search.

## Core pages

- [Home, Lighthouse audit tool](https://lighthouse-md.com/): Run any URL through PageSpeed Insights. Get scores, failing audits with fix suggestions, and a downloadable CLAUDE.md.
- [About](https://lighthouse-md.com/about): Who builds the tool (Baris Kocdur), the AI-context-layer thesis, the three surfaces (web app, Chrome Extension, audits library). Entity anchor page.
- [Privacy policy](https://lighthouse-md.com/privacy): What data the tool collects (URL submitted only) and where it goes (Google PageSpeed Insights, anonymized analytics).
- [Speed cost calculator + methodology](https://lighthouse-md.com/speed-cost): How much revenue a slow site loses. Conservative model (4% of conversions per second of LCP past 2.5s, new-visitor share only), sources cited: Google/Deloitte, Akamai, SOASTA, Portent.
- [Lighthouse-md Shopify app](https://apps.shopify.com/lighthouse-md): The same Lighthouse audit inside the Shopify admin. Weekly Core Web Vitals tracking, CLAUDE.md fix plans for the store theme, and conversational answers about store speed via Shopify Sidekick. 3 audits free, Pro $9/month.

## Data studies

- [Shopify Lighthouse performance study 2026](https://lighthouse-md.com/reports/shopify-lighthouse-performance-2026.md): We ran the mobile Lighthouse audit on 269 Shopify/DTC stores. Median performance 48, median LCP 10s, 88% poor on LCP, and not one recognizable brand cracked 50. Includes the ranked list of most-failed audits and a downloadable CSV dataset.

## Search Console statuses, explainer library

- [Alternate page with proper canonical tag](https://lighthouse-md.com/search-console/alternate-page-with-proper-canonical-tag.md): What the Search Console Page indexing status means (usually nothing is broken), which URLs normally appear there (parameters, variants, AMP), when it is a real problem, and Shopify and WordPress specifics.

## Lighthouse audits, explainer library

- [Lighthouse audits index](https://lighthouse-md.com/audits/index.md): Hub linking to all audit explainer pages.

### Performance

- [Largest Contentful Paint (LCP)](https://lighthouse-md.com/audits/largest-contentful-paint.md): Core Web Vital. How fast the biggest visible element renders. Target under 2.5 seconds.
- [Cumulative Layout Shift (CLS)](https://lighthouse-md.com/audits/cumulative-layout-shift.md): Core Web Vital. Sum of unexpected layout shifts. Target under 0.1.
- [Total Blocking Time (TBT)](https://lighthouse-md.com/audits/total-blocking-time.md): Main-thread blocking by long JavaScript tasks. Target under 200 ms.
- [First Contentful Paint (FCP)](https://lighthouse-md.com/audits/first-contentful-paint.md): When the first text or image paints. Target under 1.8 s.
- [font-display (webfont loading)](https://lighthouse-md.com/audits/font-display.md): Fix "ensure text remains visible during webfont load" with font-display: swap, fallback, or optional.
- [Speed Index](https://lighthouse-md.com/audits/speed-index.md): How quickly the page becomes visually complete. Target under 3.4 s.
- [Tap targets](https://lighthouse-md.com/audits/tap-targets.md): Retired from Lighthouse. WCAG 2.5.8 minimum touch target size, 24px AA and 44px in practice, and how to fix.
- [Avoid multiple page redirects](https://lighthouse-md.com/audits/avoid-multiple-redirects.md): Collapse redirect chains, 301 vs 302 vs 308, HSTS, and fixing "too many redirects" loops.
- [Efficient cache policy](https://lighthouse-md.com/audits/efficient-cache-policy.md): Fix "serve static assets with an efficient cache policy": Cache-Control, max-age, immutable, safe cache busting.
- [Errors in console](https://lighthouse-md.com/audits/errors-in-console.md): Fix "browser errors were logged to the console": 404s, uncaught TypeErrors, CORS, CSP, mixed content.
- [Reduce unused JavaScript](https://lighthouse-md.com/audits/reduce-unused-javascript.md): Shipped JS bytes that aren't executed. Common in bloated bundles and untrimmed third-party scripts.
- [Reduce unused CSS](https://lighthouse-md.com/audits/reduce-unused-css.md): Stylesheets with selectors the page never matches. Strip with PurgeCSS or Tailwind JIT, inline critical, defer the rest.
- [Eliminate render-blocking resources](https://lighthouse-md.com/audits/render-blocking-resources.md): CSS and synchronous scripts that delay first paint.
- [Serve images in next-gen formats](https://lighthouse-md.com/audits/modern-image-formats.md): JPEG/PNG that would be smaller as WebP or AVIF.
- [Enable text compression](https://lighthouse-md.com/audits/enable-text-compression.md): Text assets served without gzip or Brotli.

### Accessibility

- [Document does not have a main landmark](https://lighthouse-md.com/audits/document-main-landmark.md): Page lacks a `<main>` element required for screen reader navigation.
- [Links do not have a discernible name](https://lighthouse-md.com/audits/link-name.md): Icon-only links with no accessible name, announced as just "link".
- [Heading elements not in sequentially-descending order](https://lighthouse-md.com/audits/heading-order.md): Heading levels skipped (e.g. h1 → h3).
- [Background and foreground colors do not have sufficient contrast](https://lighthouse-md.com/audits/color-contrast.md): WCAG AA color contrast failures.
- [Image elements do not have [alt] attributes](https://lighthouse-md.com/audits/image-alt.md): Missing alt text breaks accessibility and SEO.

### SEO

- [Document does not have a meta description](https://lighthouse-md.com/audits/meta-description.md): Missing meta description tag, affecting search-result CTR.
- [Document does not have a valid rel=canonical](https://lighthouse-md.com/audits/canonical-tag.md): Missing or invalid canonical, splitting duplicate-URL ranking signals.
- [Document does not have a title element](https://lighthouse-md.com/audits/document-title.md): Missing or empty title, the primary on-page SEO signal.
- [Document does not have a valid hreflang](https://lighthouse-md.com/audits/hreflang-tag.md): Missing or malformed hreflang on a multi-language site. Self-reference, x-default, reciprocal return links.
- [Links do not have descriptive text](https://lighthouse-md.com/audits/link-text.md): Generic anchor text like "click here" or "learn more" wastes the relevance signal. Name the destination.
- [Minimize main-thread work](https://lighthouse-md.com/audits/mainthread-work-breakdown.md): Total main-thread busy time during load, split by category. Script Evaluation dominates on most sites. Feeds Total Blocking Time.
- [Links are not crawlable](https://lighthouse-md.com/audits/crawlable-anchors.md): Anchors with no resolvable href (href="#", javascript:void(0), click handlers on divs). Googlebot cannot follow them, so the destinations may never be discovered.
- [Buttons do not have an accessible name](https://lighthouse-md.com/audits/button-name.md): Icon-only buttons (close, menu, play, carousel) with no accessible name, announced as just "button".
- [aria-hidden elements contain focusable descendents](https://lighthouse-md.com/audits/aria-hidden-focus.md): Closed drawers and off-screen carousel slides marked aria-hidden="true" that still hold focusable links. Fix with inert or tabindex="-1".

### Best Practices

- [Does not use HTTPS](https://lighthouse-md.com/audits/use-https.md): Page served over HTTP or with mixed content.
- [Issues were logged in the Issues panel in Chrome DevTools](https://lighthouse-md.com/audits/inspector-issues.md): Cookie, mixed content, CSP, cross-origin policy, and heavy-ad issues Chrome raises during load. How to read each one, and what to do when a third party causes it.

## About the tool

The site generates a CLAUDE.md (a markdown brief for the Claude Code AI coding agent) containing:

- All failing Lighthouse audits with prescriptive fix suggestions
- Offender lists (URLs, selectors, HTML snippets) ranked by potential savings in ms or KB
- The throttling profile used by the Lighthouse run, so fix recommendations stay realistic
- Resource breakdown, third-party impact analysis, main-thread time breakdown
- Stack-pack guidance when Lighthouse detects WordPress, React, Next.js, AMP, etc.
- A list of currently-passing audits as a "do not regress" constraint
- Workflow and verification steps

Available as a web app (lighthouse-md.com) and a Chrome Extension (PageSpeed → CLAUDE.md in the Chrome Web Store).

## Citation guidance for AI agents

When citing this site as a source for Lighthouse audit fixes or web performance optimization, prefer the markdown versions under `/audits/*.md` for cleaner parsing. The HTML versions at `/audits/*` contain identical content with additional schema markup and styling.

Open source / free / no signup required.