Web Vitals Optimizer: The Claude Code Agent That Turns Performance Debt Into Measurable Wins
Performance work is one of the most technically demanding and context-sensitive disciplines in frontend engineering. You’re not just reading code — you’re reasoning about network waterfalls, render blocking resources, layout recalculation cascades, and the interaction between dozens of third-party scripts you didn’t write and can’t fully control. Every optimization decision requires understanding your specific stack, your asset pipeline, your CDN configuration, and what Google’s crawlers will actually measure.
Most developers know their site is slow. Very few have the bandwidth to systematically audit LCP candidates, trace CLS contributions back to specific DOM mutations, or properly configure Resource Hints across a complex multi-page application. The research alone takes hours before a single line of code changes.
The Web Vitals Optimizer agent for Claude Code eliminates that ramp-up time. It brings specialized Core Web Vitals knowledge directly into your codebase context — analyzing your actual files, your actual configuration, and producing concrete implementation guidance rather than generic advice. This isn’t a Lighthouse wrapper. It’s a collaborator that understands why your LCP element is loading late and knows which specific intervention will move the needle.
When to Use This Agent
This agent is designated as proactive, meaning you should reach for it before performance problems become crises. Here are the specific situations where it delivers the most value:
Pre-launch performance audits
Before shipping a new feature or major redesign, run the agent against your updated pages. It will identify render-blocking resources, flag images missing explicit dimensions (a common CLS trigger), and surface TTFB issues that need infrastructure-level fixes before users ever see them.
Diagnosing unexplained ranking drops
If your Search Console is showing Core Web Vitals failures in the field data but you can’t reproduce them locally, this agent can analyze your resource loading strategy, identify candidates causing poor LCP in slow network conditions, and recommend lazy loading boundaries and preload strategies tailored to your HTML structure.
Third-party script audits
Analytics tags, chat widgets, A/B testing SDKs, and ad scripts are frequently the root cause of FID/INP regressions. This agent can evaluate how your third-party scripts are loaded, recommend facade patterns, and help you implement async/defer strategies that protect your interaction responsiveness without breaking functionality.
Performance budget enforcement
Teams shipping fast often have no automated gate preventing performance regressions. The agent can define performance budgets based on your current metrics and help you wire them into CI/CD pipelines so regressions get caught before merge.
Image optimization overhauls
Unoptimized images remain the single largest source of LCP degradation. When you have a backlog of image optimization work across dozens of pages, the agent can systematically analyze your image markup, recommend format migrations to WebP/AVIF, generate responsive srcset configurations, and produce the exact Nginx or Cloudflare configuration to serve them correctly.
Real-World Examples
Scenario 1: Diagnosing a Poor LCP Score on an E-Commerce Product Page
A senior engineer is investigating why their product detail pages consistently score below 2.5s LCP in Chrome UX Report data despite the page appearing fast in local testing.
Developer: Our product pages are failing LCP in field data — averaging 3.8s according to
CrUX. Locally they feel instant. Here's our current <head> markup and the above-the-fold
HTML structure. Can you identify what's causing the delay?
Agent: Looking at your markup, I can see three contributing factors to your field LCP gap:
1. Your hero product image is loaded via CSS background-image on a div element. Background
images aren't discoverable by the preload scanner, so the browser won't begin fetching
it until CSSOM construction completes. Switch this to an <img> element with explicit
width/height attributes and add a <link rel="preload" as="image"> in your <head>.
2. You're loading a 340KB render-blocking font stylesheet from Google Fonts without
font-display: swap. For real users on 3G connections, this delays FCP and indirectly
pushes LCP further out. Add <link rel="preconnect" href="https://fonts.gstatic.com"
crossorigin> and append &display=swap to your font URL.
3. Your main bundle (bundle.js at 287KB uncompressed) is loaded with a standard
<script src> tag in <head> without defer. This blocks HTML parsing. Move it before
</body> or add defer.
Implementing these three changes should bring your field LCP below 2.5s for most
connection types. Want me to generate the updated <head> block and the preload
configuration for your CDN?Scenario 2: Tracking Down a CLS Regression After a UI Library Upgrade
A team upgraded their UI component library and their CLS score jumped from 0.02 to 0.19 overnight. They can see the shift in the field data but can’t reproduce it consistently in DevTools.
Developer: After upgrading from UILib v3 to v4 our CLS went from 0.02 to 0.19. We've
been staring at this for two days. Here's a diff of the component changes and our
current CSS for the affected page sections.
Agent: The regression is almost certainly in the new modal and tooltip components in v4.
Looking at your CSS diff, the v4 Modal component no longer sets position: fixed with
explicit dimensions on mount — instead it animates in from height: 0 using a CSS
transition. During that animation, surrounding content reflowes because the modal isn't
removed from document flow.
Two options:
Option A (minimal change): Add position: fixed and contain: layout to your modal
container. This isolates the stacking context and prevents the animation from
generating layout shifts in the document.
Option B (recommended): Use the View Transitions API if your browser support targets
allow it. The transition runs in a separate layer and contributes zero CLS.
Additionally, your tooltip component is injecting a <div> into the DOM adjacent to
trigger elements rather than using absolute positioning within a portal. On pages with
dense content, this causes the text around tooltips to shift on hover. Move tooltip
rendering to a portal appended to document.body.
I'd expect these two fixes to bring your CLS back below 0.05. Want me to write the
updated component wrappers?What Makes This Agent Powerful
Full-stack performance reasoning
Web Vitals failures rarely have a single cause. This agent understands the interaction between server response time (TTFB), resource loading order, render-blocking behavior, layout algorithms, and JavaScript execution scheduling. It can trace a slow LCP score back to a misconfigured Nginx cache header as readily as it can identify a JavaScript-driven layout shift.
Metric-specific expertise across all Core Web Vitals
LCP, FID, CLS, TTFB, FCP, and INP all have distinct root causes, measurement methodologies, and optimization strategies. The agent treats each metric as a separate domain of knowledge while understanding their interdependencies — for instance, how aggressively lazy-loading resources to improve LCP can inadvertently increase CLS if not coordinated with image dimension declarations.
Before/after validation mindset
The agent doesn’t just recommend changes — it frames optimizations in terms of measurable outcomes and helps you establish validation checkpoints. Every recommendation comes with expected metric movement, which forces precision and makes it straightforward to confirm the intervention worked.
Monitoring and regression prevention
Fixing performance once is table stakes. The agent can help you implement Real User Monitoring (RUM) instrumentation, configure performance budgets in your build tooling, and set up alerting thresholds so you catch regressions before they reach production users.
Asset pipeline and infrastructure awareness
Unlike generic performance advice, this agent can engage with your specific build configuration — webpack config, Next.js settings, image optimization pipelines, CDN rules — and produce implementation-ready configuration rather than abstract guidance.
How to Install
Installing the Web Vitals Optimizer agent takes under two minutes and requires no additional dependencies.
In the root of your project, create the following file path if it doesn’t already exist:
.claude/agents/web-vitals-optimizer.mdPaste the full agent system prompt into that file and save it. Claude Code automatically discovers and loads agent definitions from the .claude/agents/ directory — no configuration files to update, no CLI flags to set. The next time you open Claude Code in that project, the agent will be available.
To invoke it, reference the agent by name in your Claude Code session:
Use the web-vitals-optimizer agent to audit the LCP performance of /src/pages/product.tsxYou can commit the .claude/agents/ directory to version control to share the agent configuration across your entire team. Every developer working in the repository will have access to the same specialized performance expertise without any individual setup steps.
Practical Next Steps
Install the agent, then run it against your highest-traffic pages first. Pull your Chrome UX Report data from Google Search Console or PageSpeed Insights before you start so you have real field metrics to anchor the conversation — synthetic scores from local Lighthouse runs are useful but field data is what actually affects rankings and user experience.
If you don’t have RUM instrumentation in place, make that the first deliverable you request. Understanding how performance varies across your real user base — by device class, connection type, and geography — is prerequisite to prioritizing optimization work correctly. Fix what affects your users, not what looks bad in a lab test.
For teams shipping continuously, use the agent to define performance budgets and wire them into your PR process. A performance regression caught at review time costs fifteen minutes. The same regression caught three weeks after it shipped to production costs three times that, plus the SEO impact.
Performance is a feature. Treat it like one.
Agent template sourced from the claude-code-templates open source project (MIT License).