coach

Token-Efficiency Coach

Reads a Claude Code session transcript and coaches the user on token waste — the observable inefficiencies (uncached context, context bloat, oversized tool output, failed tool calls, output-heavy turns, wrong-tier routing, redundant reads) — with a per-finding fix and a dollar estimate. It flags waste; it never grades work quality or scores a person. The analyzer runs locally and reads only your own session log, so no prompt leaves your machine.

The report below is generated at command time by the shared engine (scripts/analyze.py), which auto-finds the latest session for this project when no path is given, or analyzes the path you pass as an argument.

Coach report

!python3 "${CLAUDE_PLUGIN_ROOT}/scripts/analyze.py" $ARGUMENTS

Your task

1. Relay the ranked report above to the user in your own words — lead with the headline (total cost, the single biggest recoverable amount) and then the findings in priority order. Keep dollar figures framed as upper-bound estimates, exactly as the engine does. Do not invent numbers the report did not produce.
2. Offer to apply the top fix. Pick the highest-severity finding and propose the concrete remedy it implies, for example:
   • Low cache hit → restructure the session so stable context (system prompt, instructions, pinned files) sits at the FRONT and stays byte-identical so it caches.
   • Context bloat / very long thread → compact the conversation or split the remaining work into a fresh session to shed dead context.
   • Oversized tool output / redundant reads → read targeted line ranges, grep for the lines needed, and pipe noisy commands through head/tail instead of dumping whole files.
   • Everything on the priciest model → route mechanical steps (renames, greps, boilerplate, file reads) to a cheaper tier and reserve the top model for real reasoning.
3. Offer to wire up the live statusline if the user does not already have one. The plugin ships scripts/statusline.py (live $cost · ctx tokens · cache-hit% · ⚠), but a plugin cannot register a statusLine itself — it must go in the user's ~/.claude/settings.json pointing at a stable copy of the script. If they say yes, walk them through the README's "Wire up the statusline" steps (copy the script to a stable path, add the statusLine block, accept the trust dialog).

If the report says no waste patterns tripped, congratulate the user on a clean session and skip the fix offer (the statusline offer may still apply).

Notes for maintainers

• All detection logic lives in scripts/analyze.py (the single engine). This command adds zero analysis logic — it only injects the engine's output and relays it.
• Waste patterns + coaching copy live in scripts/patterns.json; prices in scripts/prices.json. Edit those, not this file, to tune behavior.
• ${CLAUDE_PLUGIN_ROOT} is substituted in skill content for plugin skills, so the engine path above resolves to the installed plugin's scripts/analyze.py.