I recently posted a reel where I ask Claude Code to get my site to 100/100 in Lighthouse and it does it on its own, without me touching a line of code.
It's not magic or a trick for the camera. It's an agent loop: you give it an objective with a condition the agent can verify, and it works — audit, fix, re-measure — until it's met.
Lighthouse is the perfect case for this, because the "done" condition is objective: all four categories at 100. No opinions. Either it's at 100 or it isn't.
Here's the full flow, step by step, with the prompt ready to copy.
Before you start: install and set up Claude Code
This guide assumes you already have Claude Code installed and your project set up. If not, start here and come back:
- Claude Code Tutorial: Full Step-by-Step Guide — installation plus getting your project ready:
CLAUDE.md, context, and the setup I use daily.
Don't skip this. The loop is only as good as the context you give it. A project with no CLAUDE.md and no command to run the site forces the agent to guess — and guessing burns tokens. Five minutes of setup saves you half the loop.
If you want to understand what an agent loop is under the hood (and why the harness matters more than the loop), read Agent Loops and Loop Engineering 2026.
Step 1 — Pick the project
Open a terminal at the root of the project you want to optimize. It has to be a project you can run locally (an npm run build / npm run start, pnpm dev, whatever you use) and, ideally, with tests passing.
Why it matters: the loop will spin up your site, run Lighthouse against it and read the score. If it can't run it, it can't measure — and without measuring there's no loop.
Always work on a fresh branch: git checkout -b perf/lighthouse-100. That way everything the agent does stays isolated and you review it all at once in the PR.
Step 2 — Start a fresh session
Inside the project, open a clean Claude Code session:
claudeA new session, not one you've been dragging from another task. Dirty context is the number one cause of loops going off the rails: the model fills up with stale stuff, summarizes poorly, and starts making things up. Start fresh.
Step 3 — Drop the prompt (the /goal)
This is the heart of it. Instead of feeding it task by task, you give it one objective with a verifiable condition using /goal:
/goal Get this site to 100/100 in Lighthouse across all four categories
(Performance, Accessibility, Best Practices and SEO) on mobile.
"Done" condition (verifiable):
- Spin up the local production build and run Lighthouse in mobile mode.
- Don't stop until all 4 categories are at 100.
- After every change, re-run Lighthouse and show me the score.
Rules:
- Don't break existing functionality. Tests must keep passing.
- Small, atomic changes: one commit per improvement, with a clear message.
- If a change doesn't raise the score, revert it.
- At the end, leave a summary of what you changed and why.You paste it, hit Enter, and from there it works on its own.
Why this prompt works: it has a measurable objective (100/100), a check the agent itself can run (Lighthouse), and limits that prevent disaster (don't break tests, atomic changes, revert what doesn't help). That's loop engineering: the exit condition and the limits matter more than the loop.
What the agent does, in order
- Audits how your site and code stand today — gets the baseline.
- Decides what to fix to reach 100.
- Makes the changes and tests them: performance, accessibility, SEO and best practices.
- Spins the site up in Chrome, runs Lighthouse and reads the score.
- Repeats without stopping until all four categories are at 100.
You don't lift a finger. You watch the score climb pass after pass.
Step 4 — Review the changes
When the loop finishes (or you stop it because it already got there), review the diff. This isn't optional: the agent optimizes for the number, and sometimes the number goes up with shortcuts you don't want.
git diffThings to watch closely:
- Did it strip content or features to bump the score? An empty page scores 100 easily. We don't want that.
- Do images still look good? Over-compression is the classic performance trap.
- Real accessibility, not hacks:
aria-labelandaltshould mean something, not be filler. - Tests green: run your suite and confirm nothing broke.
If anything in the diff feels off, don't merge it. Ask the agent to explain it or revert it. A 100 isn't worth it if it breaks the real experience.
Step 5 — Push the PR
Once the diff checks out, push it as a PR for the record and, if you work with others, so it gets reviewed:
git add -A
git commit -m "perf: Lighthouse 100/100 (performance, a11y, SEO, best practices)"
git push -u origin perf/lighthouse-100Open the PR on GitHub. In the description, paste the summary the agent left: what changed and why. Future you will thank you.
Step 6 — Verify with Lighthouse (yourself, again)
Trust but verify. Run Lighthouse yourself, with no agent in the middle:
- In Chrome: DevTools → Lighthouse tab → Mobile → Analyze. Check all four categories.
- From the terminal:
npx lighthouse https://your-site.local --view - Online (once deployed): PageSpeed Insights gives you Lighthouse plus real field data.
If you get 100 across the four locally, that's the first half done. Now confirm it holds in production.
Step 7 — Once it's live: WebPageTest
A local 100 is lab data: your machine, your network, lab conditions. Production is a different beast — CDN, real latency, third-party scripts, caching. So once you've deployed, verify from the outside.
Go to WebPageTest and run a test against your production URL:
- Paste the URL, pick a real location near your audience and a mobile device (a Moto G is a good "worst case").
- Run the test (ideally 3 runs, and look at the median).
- Watch the filmstrip and timeline: when content shows, when it's interactive.
- Check the numbers that matter: LCP, CLS, TBT/INP.
WebPageTest shows you what PageSpeed hides: the request waterfall. That's where you spot the third party slowing you down (a pixel, a chat widget, a font) that never shows up locally. If the score drops in prod, that waterfall tells you why — and you re-run the loop pointed at the production URL.
Closing: what you're actually learning here
This isn't about Lighthouse. It's about delegating verifiable work.
The pattern repeats for anything with an objective "done" condition: "get all tests green", "migrate this without breaking anything", "raise coverage to 90%". If you can describe what done looks like in a way a machine can check, you can loop it.
Lighthouse is the best first loop because the verification is free and binary. Start there, watch the agent work on its own, then take the pattern to bigger problems.
Show receipts, not opinions. The score is at 100 or it isn't. The rest is noise.