Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (71 loc) · 3.64 KB

AGENTS.md

File metadata and controls

98 lines (71 loc) · 3.64 KB
Raw

PerfGraph — AI Agent Instructions

This file tells AI coding agents (Claude, ChatGPT, Copilot, etc.) how to work with PerfGraph.

What PerfGraph is

A CLI tool that collects real browser performance data via CDP, runs it through a 5-stage pipeline, and produces a structured JSON report with causal chains and prioritized fixes. Designed to be consumed by AI agents.

collect → normalize → extract → analyze → report

How AI agents should use PerfGraph

Quick entry point

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

This runs the full pipeline. The output is a report.json with:

  • summary.score — good / moderate / poor
  • issues[] — each with severity, confidence, metric value, threshold, remediation
  • chains[] — causal degradation paths from root cause to user-facing impact
  • recommendations[] — prioritized, with evidence and expected impact

MCP mode (for AI agents with MCP support)

perfgraph mcp

Starts an MCP stdio server. Agents can call perfgraph_analyze with a URL and get structured results back. The response includes paths to:

File When to read
insights.json Read first. Agent-optimized ~5-15 KB summary: Lighthouse scores, LCP element selector, render-blocking URLs, critical path depth
report.json Read for causal chains and prioritized recommendations
manifest.json File index with descriptions. Only needed if you want raw data
lighthouse.json / trace.json Deep dives only — these are large

Workflow for agents

  1. Call perfgraph_analyze or run perfgraph run --url ... --pretty
  2. Read insights.json for the quick picture
  3. Read report.json for causal analysis and prioritized fixes
  4. Only open raw files (lighthouse.json, trace.json, network.json) when you need specifics not covered by insights

Diagnostics categories

Category What it detects
LCP Large Contentful Paint, TTFB, render-blocking resources
JavaScript Long tasks, Total Blocking Time, heavy execution, unused code
Network Request chains, bandwidth bottlenecks, waterfall depth
Layout Layout shifts (CLS), DOM size, forced reflows
Third-party Overhead from embedded scripts, tracking pixels, widgets

Development commands

npm install          # install deps
npm run build        # compile TypeScript
npm run typecheck    # type-check only
npm test             # run tests
npm run dev          # tsx watch mode

Type system

  • Strict TypeScript with noUncheckedIndexedAccess
  • Zod schemas at every data boundary: src/*/types.ts
  • CDP data, Lighthouse audits, file I/O — all validated on ingress
  • Internal code works with typed interfaces, not raw JSON

Project conventions

  • kebab-case for files (lcp-breakdown.ts, not lcpBreakdown.ts)
  • camelCase for variables and functions
  • PascalCase for types, interfaces, and classes
  • Early returns. Keep nesting ≤ 3.
  • No @ts-ignore, @ts-expect-error, or as any — ever.

Causal rules

Rules live in src/causal/rules/. Each rule file exports an array of CausalRule objects. A rule:

  • Has a unique id, label, category
  • Has a build() function that takes FeatureSet and returns an array of CausalNode + CausalEdge
  • Can attach evidence (URLs, selectors, metric values) to nodes

Adding a new rule: create a file in src/causal/rules/, register it in src/causal/builder.ts, write a test in test/causal/.

Reporting issues

If PerfGraph gives wrong results, file an issue with:

  • The URL tested
  • The command run
  • The report.json (or at least the summary section)