Token-efficient agent output mode + prompt tokenizer hygiene

[miguelcolmenares]

Context

AI agents (Copilot, Claude Code, Codex) consume this toolkit's output as input tokens: they run perf-check ... --insights / --json and then read the result to propose fixes. --json emits the near-raw PageSpeed Insights payload, so each agent turn pays tens of thousands of input tokens before reasoning about a single opportunity.

This issue tracks reducing that footprint without losing the signal an agent needs. Full write-up: docs/token-efficiency-analysis.md (companion analysis doc).

Key framing (from a review of the caveman tool's honest numbers): the lever here is the input an agent reads, not shortening replies. Output-style compression gives no benefit on Copilot's per-message billing, so it is out of scope. We optimize the data we emit.

Proposed work (prioritized)

P1 — Token-lean agent output mode (--llm / --compact)

Emit only decision-relevant data in a compact, stable shape:

• Scores: performance only unless others requested.
• Core Web Vitals as { metric, ms, rating } (numeric + Good/NI/Poor); no display strings or histograms.
• Top N opportunities (default 3-5) as { title, savingsMs, wastedBytes, attribution }, sorted by impact; drop long descriptions and audit boilerplate.
• LCP breakdown: TTFB, load delay, load time, render delay + LCP element selector.
• Third-party: total blocking ms + top offenders only.
• Omit passing audits and null metrics.

Prefer compact JSON (deterministic to parse) with an optional minimal-Markdown variant. Keys short but real words (no invented abbreviations such as cfg/impl, which the tokenizer splits the same as the full word for zero saving).

Why P1: cuts agent input by roughly an order of magnitude vs raw --json, and benefits every agent including Copilot (smaller context = better answer).

P2 — Tokenizer hygiene in embedded prompts/skills

Sweep the .md assets shipped by perf-prompts: replace Unicode arrow glyphs with words (to/then/becomes), expand invented abbreviations, drop filler/hedging while preserving code/paths/commands verbatim. Add a short "LLM-facing writing" note to the contributor docs to prevent regressions. Low effort, permanent, cross-agent.

P3 — Align --insights with the lean contract

Fold --insights into the --llm contract (or add an --llm flavor) so the "for AI agents" framing maps to a token-economical shape rather than terminal formatting.

P4 — Document per-mode token cost

Add a README table with approximate token counts of --json vs --insights vs --actionable vs --llm for a representative URL, so users pick the right mode deliberately.

Acceptance criteria

• --llm (or --compact) mode implemented for perf-check, covered by tests.
• Measured token reduction of --llm vs --json on a representative URL, documented (tokenizer such as tiktoken/gpt-tokenizer).
• Embedded prompts/skills swept for arrow glyphs and invented abbreviations; code/paths preserved.
• Contributor docs include an LLM-facing writing note.
• README documents per-mode token cost.

Non-goals

• No caveman-style "terse persona" output.
• No conflating output savings with input savings.
• No micro-optimizing for Copilot per-message billing.
• Never drop a field an agent needs to propose a correct fix; when in doubt, keep it and measure.

[miguelcolmenares]

The companion analysis is now on main: docs/token-efficiency-analysis.md (53deb94).

It backs the priorities in this issue: where the toolkit's LLM-facing tokens actually go, what transfers from the caveman prompt (tokenizer facts, input-side compression, structured minimal output, measuring before and after) versus what does not (the output-style persona, which yields nothing under per-message billing), and the explicit non-goals so the work does not drift.