Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/be1zebub/perfgraph/agents-mdgit clone --depth 1 https://github.com/Be1zebub/PerfGraphWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00915 | $0.00915 |
| Opus 5 | $0.00458 | $0.00458 |
| Sonnet 5 | $0.00183 | $0.00183 |
| Haiku 4.5 | $0.00092 | $0.00092 |
Grade A, and why
PerfGraph AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 99 lines — stays where its author put it; the contents beside it link to each section on GitHub.
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/poorissues[]— each with severity, confidence, metric value, threshold, remediationchains[]— causal degradation paths from root cause to user-facing impactrecommendations[]— 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
- Call
perfgraph_analyzeor runperfgraph run --url ... --pretty - Read
insights.jsonfor the quick picture - Read
report.jsonfor causal analysis and prioritized fixes - 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 |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 99 lines · 915 tokens per session scan A 311d6855d470
PerfGraph AGENTS.md is an instructions file published in the GitHub repository Be1zebub/PerfGraph (11 stars, last pushed 3d ago), licensed MIT. It adds 915 tokens to every session, about $0.0046 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
obscura AGENTS.md
Instructions for h4ckf0r0day/obscura, covering agents.md, build, rendering and stealth, no rendering, with rustls or stealth and test.
browser-harness CLAUDE.md
Instructions for browser-use/browser-harness, a project described as: Browser Harness | Self-healing harness that enables LLMs to complete any task.
web-quality-skills AGENTS.md
Instructions for addyosmani/web-quality-skills, covering agents.md, project overview, live audit routing, directory structure and skill format.
web-quality-skills CLAUDE.md
Instructions for addyosmani/web-quality-skills, covering claude.md, project summary, quick reference, available skills and key thresholds.
terminal AGENTS.md
Instructions for browser-use/terminal, covering agent notes, rust rewrite verification loop and terminal ui testing standard.
rustwright AGENTS.md
Instructions for Skyvern-AI/rustwright, covering repository instructions, public boundary, pull-request review, local verification and browser launches.