The Problem
PageSpeed Insights gives you a diagnosis. A score, some warnings, a list of opportunities. But between that diagnosis and actual work lives a gap: translating those warnings into prioritized tasks with clear acceptance criteria.
For developers using AI coding agents, that gap is even wider. The agent needs structured input — not a screenshot of a dashboard, but a Markdown file with clear priorities, specific tasks, and guardrails that prevent regressions. The raw PageSpeed output is noisy, inconsistent between runs, and lacks the confidence signals an agent needs to act decisively.
The Build
Lighthouse Handoff started as a personal tool — a Chrome extension that grabbed PageSpeed data and formatted it into something actionable. The first version was simple: extract the data, format it as Markdown, copy to clipboard. But the real value emerged when that Markdown was fed to coding agents.
The structured format — priorities, tasks, guardrails, acceptance criteria — gave the agent exactly what it needed to make targeted improvements without introducing regressions. What began as a clipboard helper became a full handoff layer between browser diagnostics and agent-driven development.
Core Capabilities
- Confidence thresholds: Each recommendation carries a confidence score so the agent knows which fixes are high-signal vs speculative
- Fixed recommendation ordering: Consistent priority ranking across runs, so agents can track what changed without re-sorting noise
- Multi-run median testing: Runs PageSpeed multiple times and reports the median, filtering out one-off fluctuations
- Variance analysis: Shows how stable each metric is across runs, highlighting which scores are reliable and which are noisy
The Local Companion
The Chrome extension handles extraction and formatting, but the real processing happens in a local companion endpoint. This local server component takes the raw PageSpeed data and runs the statistical analysis — computing medians across runs, calculating variance, and assigning confidence scores to each recommendation.
The companion keeps everything on-machine. No data leaves your development environment. The extension sends data to localhost, the companion processes it, and the structured Markdown output is ready for your agent. This separation also means the heavy lifting doesn't slow down the browser.
Lessons Learned
The most interesting lesson was about the gap between human-readable and agent-readable output. Humans can interpret a PageSpeed dashboard and understand context — "this image is obviously the hero shot, don't compress it below 80%." Agents need explicit structure, clear boundaries, and unambiguous success criteria.
Another insight: raw PageSpeed scores are unreliable across runs. A page might score 85 on one run and 72 on the next, with identical code. Multi-run median testing with variance analysis turned out to be essential, not a nice-to-have. Without it, agents chase ghosts — trying to fix regressions that were just measurement noise.
Current Status
Lighthouse Handoff is shipped and available in the Chrome Web Store. It's a free extension with no account required. The local companion runs as a standalone process alongside your development environment.
The tool continues to evolve based on real usage patterns. Recent work has focused on better handling of accessibility scores and improved formatting for different coding agent interfaces.