webperf

WebPerf Snippets

Tested JavaScript snippets that measure and debug web performance. Your AI agent runs them for you, or you run them yourself in DevTools: the same code every time.

AI agents are good at interpreting performance data and unreliable when they write measurement code on the fly. WebPerf Snippets keeps both apart: the measurement is fixed code, tested in CI, that returns structured data, and the agent reasons about the result. The same snippets run in the console, the CLI, the DevTools extension and the Agent Skills, and every one returns an object that follows a single contract (snippets/SCHEMA.md).

→ Why AI audits need deterministic scripts

Run them with an AI agent

Not sure which snippet to run? Start from the symptom in Which snippet should I use?

Copy prompt

Snippet pages have a Copy prompt button above the code. It copies a prompt that asks any AI agent with a terminal to run that snippet with the CLI on the URL you give it, and to report the value, the cause and the issues. The agent runs the published snippet instead of rewriting it or estimating the result.

Agent skills

The snippets are packaged as Agent Skills for Claude Code, Cursor, OpenCode, Gemini CLI, VS Code extensions and other compatible agents. With Chrome DevTools MCP, the agent runs the snippets in your browser and reads the object they return.

npx skills add nucliweb/webperf-snippets

This installs the skills from the GitHub repository into ~/.claude/skills/. To install them from a clone instead:

git clone https://github.com/nucliweb/webperf-snippets.git
cd webperf-snippets
npm run install-skills   # into .claude/skills/ of the current project
npm run install-global   # into ~/.claude/skills/, for every project

The skills include workflows (predefined sequences, such as a complete loading audit or a font loading investigation) and decision trees that pick the next snippet from the result of the previous one: when TTFB is above 600 ms, the agent runs TTFB-Sub-Parts to find whether the time goes to DNS, the connection or the server.

User: "Analyze loading performance"

Agent:
1. Runs TTFB.js → 1.9 s (poor)
2. Follows the decision tree → runs TTFB-Sub-Parts.js
3. Finds that the server response takes most of the time
4. Runs Service-Worker-Analysis.js
5. Reports the findings with specific fixes

Skills activate when the request matches them:

Audit this page for Core Web Vitals
Debug slow LCP
Why is my TTFB so high?
Check for image optimization issues

See SKILLS.md for every skill, its workflows and its triggers.

→ Read more about WebPerf Agent Skills

CLI

The CLI runs the same snippets headlessly with Playwright. It diagnoses LCP regressions in CI, gates pull requests on performance budgets and automates the audits you run by hand. The --json output is what an agent or a script reads.

npx webperf-snippets https://example.com --json
npx webperf-snippets https://example.com --snippet LCP-Subparts
npx webperf-snippets https://example.com --workflow audit
npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1

The core-web-vitals, audit, loading and interaction workflows chain several snippets in one run. A composite GitHub Action (nucliweb/webperf-snippets/.github/actions/webperf-snippets) wraps the CLI for CI, with budgets and a Markdown output ready to post as a pull request comment.

The CLI is published to npm as webperf-snippets. See the CLI documentation and cli/README.md for installation, usage and CI integration.

Run them in your browser

Every snippet also runs by hand in the DevTools console, with the same code the agents use. All snippets are tested in Google Chrome; most also work in other Chromium-based browsers and in Firefox, and Safari has limited Performance API support. Each snippet page shows the browser support of the APIs it needs.

Run in the console

1. Copy any snippet from webperf-snippets.net
2. Open DevTools (F12 or Cmd+Option+I / Ctrl+Shift+I)
3. Go to the Console tab
4. Paste and press Enter

Save as a DevTools snippet

1. Open DevTools → Sources tab → Snippets panel
2. Click + New snippet
3. Name it (e.g., "LCP")
4. Paste the code
5. Right-click → Run (or Cmd+Enter / Ctrl+Enter)

DevTools extension (beta)

A DevTools panel runs the snippets on the inspected page without pasting them, shows their results, and audits the page with the checks of the CLI. It installs from a zip while it is in beta.

→ DevTools extension

Video tutorial

https://github.com/nucliweb/webperf-snippets/assets/1307927/2987a2ca-3eef-4b73-8f6b-7b1e06b50040

What you can measure