OhMyPerf

The first perf tool an LLM agent can actually fix your site with — statistical proof, not vibes.

🌐 Try the viewer live: hoainho.github.io/ohmyperf/viewer/ — drag any report.json onto the page and inspect every metric, every long-task, every render-blocking opportunity in your browser. No install, no signup.

OhMyPerf measures Core Web Vitals on a real machine with a real Chromium, then closes the loop: an AI agent can call measure → propose_patch → verify_fix in one conversation turn — and prove the fix improved your LCP/INP/CLS with a Mann-Whitney U test at α=0.05, not "looks better to me."

┌──────────┐    ┌───────────────┐    ┌──────────────┐
│ measure  │ →  │ propose_patch │ →  │  verify_fix  │
│ real CWV │    │ ranked, ROI   │    │  p-value per │
│ + trust  │    │ first-party   │    │   metric     │
└──────────┘    └───────────────┘    └──────────────┘
     ↓                  ↓                    ↓
 trustScore         fixPlan             verdict:
 servability       (18 patches         improvement |
 originClass        for tradeit.gg)    neutral |
                                       regression

30-second demo

Real CLI output, no editing:

$ npx -y @ohmyperf/cli@latest run https://example.com --runs 2 --format json
[ohmyperf] INFO OhMyPerf v1.0.0 report
[ohmyperf] INFO url:     https://example.com
[ohmyperf] INFO browser: chromium 148.0.7778.0 (bundled)
[ohmyperf] INFO mode:    real; runs=2; duration=2430ms
[ohmyperf] INFO aggregated:
[ohmyperf] INFO   lcp        median=  256.0  cov=25.0%  n=2
[ohmyperf] INFO   cls        median=  0.000  cov= 0.0%  n=2
[ohmyperf] INFO   fcp        median=  256.0  cov=25.0%  n=2
[ohmyperf] INFO   ttfb       median=  224.5  cov=25.5%  n=2
[ohmyperf] INFO   tbt        median=    0.0  cov= 0.0%  n=2
[ohmyperf] INFO   runtime.taskDuration median=   25.2  cov=20.2%  n=2
[ohmyperf] INFO wrote /path/to/ohmyperf-out/report.json

The full report.json is what LLM agents see — including (v0.2.0, pending publish):

• Report.trustScore — overall + per-metric {level, sampleConfidence, effectConfidence, recommendedAction}

• Report.fixPlan — ranked, deduped, ROI-scored patches with applicability: first-party | third-party-cannot-apply

• Report.meta.servability — real-page | bot-challenge-suspected | error-page | timeout-partial | unknown

• Every Resource tagged with originClass: same-origin | same-site | same-org | cross-site

CoV 25% on 2 runs (above 20% noise floor) → trustScore: low → agent's recommendedAction: "rerun with --runs 10 or --mode ci-stable before drawing budget conclusions". Honest about its own variance, not vibes.

Why this exists

Install

# CLI
npm install -g @ohmyperf/cli
ohmyperf run https://your-site.com

# MCP server — for Claude (OpenCode/Cursor/Cline) to call tools directly
npm install -g @ohmyperf/mcp-server

# Zero-install one-off
npx -y @ohmyperf/cli@latest run https://your-site.com

Requires Node ≥ 22. Playwright Chromium auto-downloads on first run (~150 MB).

Use it from an AI agent

Add to your MCP client config (Claude Desktop example):

{
  "mcpServers": {
    "ohmyperf": {
      "command": "npx",
      "args": ["-y", "@ohmyperf/mcp-server@latest"]
    }
  }
}

Then your LLM has 16 tools available: measure, propose_patch, verify_fix, get_fix_plan, get_trust_score, get_servability, diff, list_reports, and more. Tested with Claude, OpenCode, Cursor, Cline.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Engine: @ohmyperf/core (frozen 1.0.0 public API)               │
│  · Playwright + raw CDP (Target.setAutoAttach for cross-origin) │
│  · Plugin runtime · Calibration · Outlier rejection · Diff      │
│  · LLM-first signals: trustScore · fixPlan · servability        │
└─────────────────────────────────────────────────────────────────┘
        │
        ├──► CLI                 npx -y @ohmyperf/cli run <url>
        ├──► npm SDK             import { runEngine } from "@ohmyperf/core"
        ├──► MCP server          12 tools + 7 prompts (v0.1.0) — 17 tools in v0.2.0 [Unreleased]
        ├──► Chrome extension    click toolbar icon → measure current tab
        ├──► VSCode extension    Cmd+Shift+P → OhMyPerf: Measure URL
        ├──► Website             hoainho.github.io/ohmyperf — drop report.json on /viewer
        ├──► Share-server        Cloudflare Workers or Node
        ├──► ESLint plugin       7 CWV-linked rules at editor-save time
        └──► Fixers SDK          archetype registry + proposePatches()

Status: v0.1.0 on npm. v0.2.0 (issue #7) ships the agent fix loop + LLM-first signals + 2 new packages, pending credential refresh.

Why OhMyPerf

Surfaces

CLI quickstart

# Install
npm install -g @ohmyperf/cli
ohmyperf install-browser

# Measure
ohmyperf run https://example.com --runs 5 --format json,html

# CI-gating mode (calibrated CPU + Fast 4G)
ohmyperf run https://example.com --mode ci-stable --runs 5

# Compare two reports with Mann-Whitney significance (exit 1 on regression)
ohmyperf diff baseline.json candidate.json

# Share a report to a hosted endpoint
export OHMYPERF_SHARE_ENDPOINT=https://ohmyperf.dev
ohmyperf share ./ohmyperf-out/report.json

# Diagnostics
ohmyperf doctor
ohmyperf list-plugins --json

Subcommands: run, diff, share, doctor, list-plugins, install-browser. Exit codes 0–12 documented per the cli-surface capability spec.

Example output

[ohmyperf] INFO OhMyPerf v1.0.0 report
[ohmyperf] INFO url:     https://example.com
[ohmyperf] INFO browser: chromium 147.0.7727.0 (bundled)
[ohmyperf] INFO mode:    real; runs=5; duration=4823ms
[ohmyperf] INFO aggregated:
[ohmyperf] INFO   lcp        median=  44.0  cov=4.3%  n=5
[ohmyperf] INFO   fcp        median=  44.0  cov=4.3%  n=5
[ohmyperf] INFO   ttfb       median=   6.5  cov=12.3% n=5
[ohmyperf] INFO   cls        median=  0.000 cov=0.0%  n=5
[ohmyperf] INFO   tbt        median=   0.0  cov=0.0%  n=5
[ohmyperf] INFO audits: 1
[ohmyperf] INFO   [PASS] a11y.axe-violations
[ohmyperf] INFO wrote ./ohmyperf-out/report.json (9 KB)
[ohmyperf] INFO wrote ./ohmyperf-out/report.html (28 KB)

npm SDK quickstart

import { runEngine, createSilentLogger } from "@ohmyperf/core";
import { createPlaywrightAdapter } from "@ohmyperf/driver-playwright";
import { cwvPlugin, axePlugin } from "@ohmyperf/plugins-builtin";
import { writeJsonReport } from "@ohmyperf/reporter-json";

const { driver, adapter } = createPlaywrightAdapter({
  url: "https://example.com",
  kind: "chromium",
});

const report = await runEngine({
  opts: {
    url: "https://example.com",
    runs: 5,
    mode: "real",
    plugins: [cwvPlugin(), axePlugin({ tags: ["wcag2aa"] })],
  },
  driver,
  adapter,
  logger: createSilentLogger(),
});

console.log(report.aggregated.lcp);
// { median: 44, p75: 45, p95: 47, mean: 44.5, stdev: 1.2, cov: 0.027,
//   runs: 5, droppedOutliers: 0 }

await writeJsonReport(report, "./out");

The public API (@ohmyperf/core) is frozen at 1.0.0-stable and enforced by api-extractor in CI. See packages/core/etc/core.api.md for the 45-export contract.

Chrome extension

cd apps/extension-chrome
pnpm build
# Chrome → chrome://extensions → Developer mode → Load unpacked
# Point at apps/extension-chrome/extension-dist/

Click the toolbar icon on any tab. A "measuring…" badge appears, then opens a viewer tab with the full HTML report when done. Uses chrome.debugger directly — no companion app, no localhost relay.

Chrome Web Store submission is documented as deferred (requires publisher account + privacy policy URL + review cycle).

VSCode extension

cd apps/ide-vscode
pnpm build
# Code → Extensions → ⋯ → Install from VSIX
# Or develop: F5 in this folder launches an Extension Development Host.

Commands:

• OhMyPerf: Measure URL — prompts for URL, runs the CLI, opens result in a webview.

• OhMyPerf: Open Report File… — file picker for replaying saved reports.

Settings: ohmyperf.cliPath, ohmyperf.defaultUrl, ohmyperf.defaultRuns, ohmyperf.defaultMode.

VSCode Marketplace submission is documented as deferred.

MCP server (for AI agents)

OhMyPerf ships an MCP (Model Context Protocol) server so AI agents like Claude Desktop, OpenCode, Cursor, Cline, and Continue can call measure and diff as first-class tools.

Register with OpenCode

~/.config/opencode/opencode.json:

{
  "mcp": {
    "ohmyperf": {
      "type": "local",
      "command": ["npx", "ohmyperf-mcp"]
    }
  }
}

Register with Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ohmyperf": {
      "command": "npx",
      "args": ["ohmyperf-mcp"]
    }
  }
}

Install from Glama (MCP directory)

The OhMyPerf MCP server is listed in the Glama MCP directory — one-click install paths for every Glama-supported client, no npx command required.

# Glama CLI (one-off)
npx -y @glama/mcp-server@latest install hoainho/ohmyperf

# Or just point your client at the stdio command:
command:  npx
args:     [-y, @ohmyperf/mcp-server]

The glama.json at the repo root pins the install command + maintainer metadata so the Glama listing stays in sync with this README. Claim your own copy at https://glama.ai/mcp/servers/hoainho/ohmyperf/score to edit the description, configure Docker build instructions, and receive review notifications.

Tools exposed

What's available where: @ohmyperf/mcp-server@0.1.0 currently on npm exposes the 12 tools NOT marked (v0.2.0). The 5 v0.2.0-tagged tools (propose_patch, verify_fix, get_fix_plan, get_trust_score, get_servability) are committed on main and will land when v0.2.0 publishes — track at issue #7. All 17 tools + 7 prompts are also available today by pointing an MCP client at npx -y @ohmyperf/mcp-server@main once v0.2.0 lands.

Saved reports surface as resources at ohmyperf://reports/<timestamp>-<id>.json so the agent can read them back later without re-measuring.

Killer flow: closed agent fix loop (v0.2.0)

1. measure(url)              → report.json + opportunities
2. propose_patch(reportPath) → { archetype: "render-blocking-script-add-defer",
                                  search: '<script src="vendor.js"',
                                  replace: '<script src="vendor.js" defer',
                                  expectedImpactMs: 320,
                                  confidence: "high" }
3. (agent applies patch + deploys to preview)
4. verify_fix(baseline, candidateUrl) → ✅ no regression / ❌ REGRESSION

End-to-end loop time: ~5.5s against a real public URL (commit a41301f verified composition). Patches archetypes covering ~80% of typical opportunities (render-blocking scripts/stylesheets, LCP image fetchpriority + preload).

Website

Live at hoainho.github.io/ohmyperf (zero-credential GitHub Pages mirror, deployed via .github/workflows/deploy-pages.yml). Cloudflare Pages deploy at ohmyperf.dev is pending domain registration (#9).

cd apps/website
pnpm build                              # Next.js static export to out/
OHMYPERF_BASE_PATH=/ohmyperf pnpm build # for GitHub Pages subpath

Routes:

• / — landing page (light/dark theme, no external network requests)

• /viewer/ — drag-drop report.json to render in browser (no upload, no analytics, no signup)

• /measure/ — in-browser measurement SPA (CDP via the Chrome extension when installed)

• /report/ — local measurement history

• /r/:id — served by the share-server when deployed alongside

Share-server (hosted shareable links)

Two deployment targets from the same Hono codebase:

Cloudflare Workers + R2 + D1 (production)

cd packages/share-server
# wrangler.toml + D1 schema (D1_SCHEMA export)
wrangler d1 execute ohmyperf-db --file=schema.sql
wrangler deploy

Node + filesystem (self-host)

cd packages/share-server
pnpm build
PORT=4170 OHMYPERF_SHARE_DATA_DIR=./data node dist/node.js
# listening on http://127.0.0.1:4170

API:

POST /api/share          { report, password?, expiresInMs?, private? } → { id, url, expiresAt }
GET  /api/r/:id          → raw report JSON (with optional password gate)
GET  /r/:id              → rendered HTML (uses @ohmyperf/viewer)
DELETE /api/r/:id        → 204

Per-IP rate limit (10/hour default), 10 MB body cap, mandatory security headers (X-Content-Type-Options, Referrer-Policy, X-Frame-Options), env-secret scrubber in the upload client.

GDPR / Privacy Policy / DPA / DSAR endpoint defer to legal review.

CI integration

Drop-in templates/ci/github-actions.yml:

- run: npx ohmyperf run "$OHMYPERF_URL" --mode ci-stable --runs 5 \
       --format json,html,markdown --output ./perf
- uses: actions/upload-artifact@v4
  with: { name: ohmyperf-reports, path: perf/ }
- if: github.event_name == 'pull_request'
  run: ohmyperf diff .ohmyperf-baseline/report.json perf/report.json

Auto-posts the Markdown summary as a PR comment via actions/github-script@v7. Mann-Whitney significance gates the merge.

Architecture

Monorepo: pnpm workspaces + Turborepo.

ohmyperf/
├── packages/
│   ├── core/                     # Engine, plugin runtime, calibration, diff
│   ├── driver-playwright/        # Playwright + raw CDP (newCDPSession)
│   ├── driver-extension/         # chrome.debugger driver
│   ├── plugins-builtin/          # cwv, axe, custom-metric-example
│   ├── reporter-{json,html,markdown}/
│   ├── viewer/                   # Pure-TS HTML report renderer
│   ├── share-client/             # Upload + redaction pipeline
│   ├── share-server/             # Hono backend (Workers + Node)
│   └── tests-oopif-corpus/       # Synthetic cross-origin iframe fixtures
├── apps/
│   ├── cli/                      # ohmyperf binary (citty)
│   ├── website/                  # Static landing + drag-drop viewer
│   ├── extension-chrome/         # MV3 + chrome.debugger
│   ├── ide-vscode/               # Command palette + webview
│   └── mcp-server/               # @modelcontextprotocol/sdk stdio server
└── openspec/                     # OpenSpec proposal + ADRs

ADRs:

• ADR-001 Driver abstraction; Playwright primary; raw CDP via newCDPSession()

• ADR-002 OOPIF via Target.setAutoAttach({flatten:true}); CLS dual reporting

• ADR-003 Plugins in-process; npm trust; shared reports are inert JSON

• ADR-004 Chrome extension via chrome.debugger

• ADR-005 Cloudflare Workers + R2 + D1; Hono + S3 + Postgres self-host parity

Capability matrix

Cross-browser deep-inspection is Chromium-only. Firefox and WebKit get CWV via the web-vitals polyfill + standard PerformanceObserver.

Honest defer list

Documented per surface in each commit message. Not blockers for v0 dogfood:

• Per-frame collector support in Chrome extension's measurement path Done (v0.2.0): cross-origin OOPIFs get real CDP sessions via context.newCDPSession(frame).

• Source-map detection on longestScript Done stage-1 (v0.2.0): schema slot + sourceMappingURL regex detection. Stage 2 (VLQ decode + fetch + repo-root mapping) deferred to v0.3 — depends on adding @jridgewell/sourcemap-codec.

• VSCode Marketplace publish engineering ready (v0.2.0) — .github/workflows/publish-vscode.yml + vsce package verified locally produces valid .vsix; needs anh's VSCE_PAT secret. See docs/PUBLISH-VSCODE.md.

• Cloudflare Pages website deploy engineering ready (v0.2.0) — .github/workflows/deploy-website.yml ready; needs anh's CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID secrets. See docs/DEPLOY-WEBSITE.md.

• smithery.ai + glama.ai MCP listings engineering ready (v0.2.0) — smithery.yaml configured for stdio runtime. See docs/PUBLISH-MCP-LISTINGS.md.

• Chrome Web Store extension publish (requires publisher account + privacy policy URL + review cycle)

• JetBrains Marketplace + IntelliJ plugin (v0.3+)

• GDPR / Privacy Policy / DPA / Terms / DSAR endpoint (require legal review)

• Argon2id password hashing in share-server (v0 uses SHA-256; Workers doesn't expose Argon2id natively)

• Source-map decorations + CodeLens in VSCode extension (v0.3+)

• Scenario user-flow files in CLI (v0.3+ — engine assumes single-URL goto)

• TypeScript loader for .ts scenario files (v0.3+; v0 supports .mjs only)

• Cloud real-device farm (explicit non-goal per ADR-002)

• RUM SDK (different product category, explicit non-goal)

• Mobile-native apps (Android/iOS WebView remote debugging is v0.4+)

Repository state

365 tests across 13 workspaces, all passing on Node 22 and Node 24, against real Chromium + real Hono server + mocked chrome.debugger/vscode APIs:

@ohmyperf/core                 94
@ohmyperf/driver-playwright     6
@ohmyperf/driver-extension      6
@ohmyperf/viewer               83
@ohmyperf/reporter-markdown     8
@ohmyperf/reporter-deck        50
@ohmyperf/share-server         10
@ohmyperf/design-tokens        32
@ohmyperf/website               7
ohmyperf-vscode                 2
@ohmyperf/extension-chrome      4  (+ 1 deferred-skip integration test)
@ohmyperf/mcp-server           13
@ohmyperf/tests-oopif-corpus   19
@ohmyperf/tests-visual-regression  3
@ohmyperf/eslint-plugin         7  (v0.2.0 — RuleTester)
@ohmyperf/fixers                9  (v0.2.0 — proposePatches + archetype registry)
ohmyperf-cli                   10
@ohmyperf/runner               24
                            ──────
                              387 (+ 1 skip)

Quality gates wired in CI:

• pnpm typecheck across 31 workspaces (strict TS, exactOptionalPropertyTypes, noUncheckedIndexedAccess)

• pnpm lint with import-layering rules (plugins can't import core internals, viewer can't import drivers, CDP types stay inside driver packages)

• pnpm test (Vitest) with OHMYPERF_CHROMIUM_PATH for real-browser tests

• pnpm license:audit — 396+ packages scanned, allow-list of Apache-2.0 / MIT / ISC / BSD / MPL-2.0

• pnpm --filter @ohmyperf/core api:check — api-extractor enforces the frozen 1.0.0 public surface

• actionlint v1.7.12 across all 7 workflows (0 warnings)

• publish-stable.yml preflight: npm whoami + npm access list packages @ohmyperf to catch misconfigured tokens before pipeline cost (skips itself in OIDC-only mode)

Contributing

This project follows OpenSpec conventions. Architecture changes go through the multi-agent deep-design pipeline (Metis scope + Oracle architecture + Momus review) before code. See openspec/ for the proposal and ADRs.

Pull requests must:

• Pass pnpm typecheck && pnpm lint && pnpm test && pnpm license:audit

• Update the API contract (packages/core/etc/core.api.md) when changing public exports

• Match existing ESLint layering rules — no CDP types in @ohmyperf/core, no driver imports in @ohmyperf/viewer

License

Apache-2.0. See LICENSE and NOTICE for third-party attributions (axe-core is MPL-2.0; web-vitals, Playwright, Lighthouse audit modules, tracium-equivalent are Apache-2.0).