Key takeaways

A score alone is not enough context. Include metrics, targets, evidence URLs and affected pages.

Add a guardrail such as "Do not change layout, copy, or design."

Fix at the template level, so one change covers every page built from it.

Ask the agent to list each file it edited and what each change fixes.

Re-audit the same URLs on the same device to confirm the improvement.

Steps

01 Audit the site Run Lighthouse on every page and group the failing audits by template, so you know which fixes cover the most pages.

02 Write or copy a precise prompt Give Claude Code the device, metric values and targets, evidence URLs, affected pages, a guardrail against design changes, and ask it to list the files it edits.

03 Run Claude Code in your repository Open Claude Code in the project root, paste the prompt, and let it find the template and make the changes.

04 Review and build Review the diff, run your build and tests, and deploy to a preview or staging URL.

05 Re-audit Re-run Lighthouse on the same URLs and device, and compare before and after.

Claude Code can read your codebase, find the template behind a slow page, and make targeted changes. What it cannot do on its own is see your Lighthouse results. The quality of the fix depends on the quality of what you hand over.

What to give the agent

A prompt like “make the site faster” invites guesswork. A good prompt reads like a bug report:

Context: the site, device, Lighthouse version, test region, run date and the framework in use.
Issues, ranked by impact: each failing audit with its metric value and target, for example “LCP 4.1 s, target under 2.5 s”.
Evidence: the exact resources involved, such as the image URL that is the LCP element or the script blocking the main thread.
Scope: the template and the list of affected URLs, so the agent fixes the cause once.
Guardrail: “Do not change layout, copy, or design.”
Report back: “List each file you edited and what it fixes.”

Here is an example for a blog template:

Fix the Lighthouse issues below on example.com (mobile).
Stack: Next.js

1. Largest Contentful Paint 4.1 s (target under 2.5 s)
   Template /blog/[slug] · 140 pages affected
   Evidence: /images/blog/hero.jpg (1.2 MB, not preloaded)
2. Cumulative Layout Shift 0.21 (target under 0.1)
   Template /blog/[slug] · 140 pages affected
   Evidence: <img> in .post-header has no width or height

Targets: Performance 90+, Accessibility 100.
Do not change layout, copy, or design.
When you finish, list each file you edited and what it fixes.

AiroPages generates this prompt for you from your audit data. Use the Copy for coding agent button on the site overview, a page report, an issue or a template group, and choose Prompt, Markdown checklist or JSON. See coding agents.

Run it in Claude Code

Open a terminal in your project root and start claude.
Paste the prompt. Claude Code searches the codebase for the template and the resources named in the evidence.
Read its plan before it edits. If it proposes a design change, point back at the guardrail.
Review the diff. Typical fixes are adding width and height to images, preloading or prioritizing the LCP image, deferring non-critical scripts, and adding accessible names to buttons and links.
Run your build and tests, then deploy to a preview or staging URL.

Close the loop with MCP

Copying a prompt is a one-way handoff. With the Model Context Protocol (MCP), the agent can read issues and re-audit by itself. Add the AiroPages MCP server to Claude Code with your API key:

claude mcp add --transport http airopage https://mcp.airopages.com --header "Authorization: Bearer <KEY>"

The agent can then call list_issues and get_fix_prompt, make changes, call run_audit on the URLs it touched, wait_for_audit, and compare_runs to report before and after scores. Re-scans draw from your monthly allowance and need a Pro or Agency plan. Full setup is in the MCP docs.

Check the result properly

Re-audit the same URLs on the same device, and compare medians rather than single runs; see why Lighthouse scores vary. Lab improvements show up immediately. Field data in CrUX is a rolling 28-day window, so expect real-user metrics to catch up over the following weeks.

See every page’s score. Start with your site.

Enter your site. We count its pages and show the exact price before you pay: once from $5, or monthly from $19.99.

See the exact price for your site. Pay once from $5, or subscribe.

Using Claude Code to fix Lighthouse issues

TL;DR