perfgraph

PerfGraph

[![npm][badge-version]][npm] [![license][badge-license]][license] [![npm downloads][badge-downloads]][npm] [![github stars][badge-stars]][repo]

Real browser metrics → causal degradation graph → actionable report. Built for AI agents, useful for humans.

PerfGraph launches a headless Chromium browser, captures performance data via Chrome DevTools Protocol, runs it through a 5-stage analysis pipeline, and produces a structured report with issues sorted by severity, causal chains, and prioritized fixes.

npx perfgraph run --url https://example.com --pretty

PerfGraph — not a symptom list, a diagnosis.
Root cause → impact → fix, in one graph.

Use from an AI agent →

Why

Lighthouse gives you a score. PerfGraph tells you why it's bad and what to fix first.

Instead of digging through a 10k-line trace.json or a wall of Lighthouse audits, you get a focused report with root causes linked to impact. The output is designed to be read by AI agents (or you) without a decoder ring.

Pipeline

collect → normalize → extract → analyze → report

Install

npm install -g perfgraph

Or skip the install:

npx perfgraph --help

Requirements: Node.js ≥ 22 and Playwright's Chromium build. The browser is not downloaded automatically — install it once:

npx playwright install chromium

If the binary is missing, PerfGraph fails with the exact expected path instead of a cryptic launch error.

Quick start

Full pipeline, one command:

perfgraph run --url https://example.com --pretty

Want to use PerfGraph from your AI agent? See AI agent workflow.

Step by step:

# 1. Collect data
perfgraph collect --url https://example.com --output ./results

# 2. Normalize → Extract → Report
perfgraph normalize ./results/perfgraph_example_20260609_120000 --output ir.json
perfgraph extract ir.json --output features.json
perfgraph report features.json --output report.json --pretty

Commands

perfgraph run

Full pipeline in one shot.

--url <url>           Required. Target URL to analyze.
--output <dir>            Output directory (default: ./perfgraph-output).
--runs <n>            Number of collection runs (default: 1).
--pretty              Pretty-print the final report JSON.
--device <name>       Mobile emulation (e.g. "iPhone 13").
--owned-domain <host> Treat an extra hostname as first-party CDN (repeatable).
--no-lighthouse       Skip Lighthouse collection.
--no-coverage         Skip JS/CSS coverage.
--no-console          Skip console log capture.
--no-dom              Skip DOM snapshot.

perfgraph collect

Captures performance data from a URL. See run options — same flags apply.

perfgraph normalize <input>

Converts raw collected data into a validated IRBundle. Accepts a run directory or a parent directory (auto-detects latest run).

--output, -o <file>   Write to file (default: stdout).
--pretty              Pretty-print JSON.

perfgraph extract <ir-file>

Computes diagnostic features from a normalized IR bundle.

--input, -i <file>    Path to IR JSON (alternative to positional).
--output, -o <file>   Write to file (default: stdout).
--pretty              Pretty-print JSON.

perfgraph analyze <features-file>

Applies causal rules and builds a degradation graph.

--input, -i <file>    Path to FeatureSet JSON (alternative to positional).
--output, -o <file>   Write to file (default: stdout).
--pretty              Pretty-print JSON.

perfgraph report <features-file>

Generates the final performance report. Accepts a FeatureSet JSON (from extract) — runs the causal engine internally, no need to call analyze separately.

--input, -i <file>    Path to FeatureSet JSON (alternative to positional).
--output, -o <file>   Write to file (default: stdout).
--pretty              Pretty-print JSON.

AI agent workflow

1. Make the CLI available

npm install -g perfgraph
npx playwright install chromium

2. Install the skill (optional but recommended)

The package ships an agent skill that describes how to invoke the CLI and how to interpret its artifacts. Copy it into your agent's skills directory:

# OpenCode
cp -r node_modules/perfgraph/skills/perfgraph ~/.config/opencode/skills/

# Claude Code
cp -r node_modules/perfgraph/skills/perfgraph ~/.claude/skills/

If you work on the skill itself, link it instead of copying it. A copy goes stale, and then the agent learns the old way to run the tool:

# Linux and macOS
ln -s "$PWD/node_modules/perfgraph/skills/perfgraph" ~/.config/opencode/skills/perfgraph

In a checkout of this repository the skill lives at skills/perfgraph/SKILL.md, with the metric reference in skills/perfgraph/references/interpretation.md.

3. Run the pipeline

perfgraph run --url https://example.com --output ./perfgraph-output --pretty

Read the resulting files progressively:

1. manifest.toon — files actually produced;
2. insights.toon — compact triage and top recommendations;
3. report.toon — issues, causal chains, evidence and recommendations;
4. report.md or graph.toon — readable diagnosis and causal graph;
5. raw trace.json, network.json and lighthouse.json only for targeted deep dives.

The agent should summarize the status, show an ASCII causal degradation graph for the 1–3 main chains, give 3–5 prioritized actions, and mention confidence, warnings and missing data. .toon files are text and should not be parsed as JSON. The full agent instructions live in skills/perfgraph/SKILL.md.

Runs and their spread

perfgraph run --runs 3 writes runs-summary.json next to the run directories. It holds the metrics of every run, both the lab run PerfGraph measured and the Lighthouse run, and the spread of each: variance for the lab run — the run the report describes — and varianceLighthouse for Lighthouse's own runs. The first run is often an outlier, so the median is the number to quote.

Insights format

insights.toon is the compact triage artifact. It keeps the two measurement runs apart, because PerfGraph and Lighthouse each navigate the page on their own:

runContext:  browser, os, device, viewport, throttling, owned do