Agent Advisor Beta

Usage says what your agents cost. Advisor says how much of that was avoidable — and where it went.

Beta. Every figure is an estimate of opportunity computed from local session logs (tokens are approximated from bytes and priced at your window's blended input rate), never promised savings. Every mechanism count is a floor: an unreadable transcript under-reports rather than failing the run.

How it works

The advisor re-reads the window's session transcripts and sizes each class of mechanical Read waste: identical re-reads (the same file read again, byte-identical), subset re-reads (a partial read already contained in an earlier full read), write read-backs (a read echoing content the agent had just written), and line-number scaffolding (the cat -n prefix bytes inside every Read result). Stale reads — reads later invalidated by an edit — are sized too, but reported as context and never summed into the recoverable headline, because reclaiming them needs staleness-aware context handling rather than better habits.

Waste is priced at the window's blended input rate: each model's share of the window's input tokens weights its own rate, so a Haiku-heavy window prices its waste cheaper than an Opus-heavy one. Because waste is priced at fresh-input rates while cached re-reads actually billed cheaper, the headline is capped at the window's measured spend and says so when the cap fires — an upper bound, clearly labelled.

The cache-health half

The second half of the report is about your prompt cache. The advisor scans the files that feed an agent's prompt prefix — your home and per-project CLAUDE.md files — for volatile-shaped content: UUIDs, ISO 8601 timestamps, JWT-shaped strings, hex digests. Content like that in a prefix file is an indicator the prefix churns between sessions, which breaks provider prompt-cache reuse. The result is a 0–100 alignment score plus per-file counts — an indicator, not proof.

Alongside it: context residency (how many assistant turns a Read stays in context — the multiplier on its cache-read cost) and cache-death windows (inter-message gaps longer than the provider cache TTL).

What leaves the scan

Nothing but numbers. Transcripts and CLAUDE.md files are read on this machine; the report carries counts, byte totals and file paths — never their content. Not even a truncated sample of a detected token is kept.

From the command line

yeaboi agents advisor
yeaboi agents advisor --window-days 7
yeaboi agents advisor --format json
yeaboi agents advisor --strict      # exit 3 if the run was degraded

Over MCP the same engine is agents_advisor_run, with agents_advisor_history for previously stored reports.