SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstoken-audit

token-audit

Agents & models

View repository

Updated 10-15 20:05

About this skill

Token Audit

Find where Claude Code tokens are leaking — and what to fix first.

When to use this skill

  • User asks to audit their token usage or Claude Code costs
  • User hitting weekly plan limits (Pro / Max 5x / Max 20x)
  • User wonders why a task burned more tokens than expected
  • Before/after installing lots of MCPs, plugins, or skills (drift check)
  • As a periodic self-review (weekly or bi-weekly)

What it does

Runs a local-only audit with three inputs:

  1. ccusage (external CLI, 13k★ open source) — baseline $ totals per day/model/session
  2. JSONL transcripts — per-turn analysis for patterns ccusage doesn't see. Walks both:
    • ~/.claude/projects/**/*.jsonl (Claude Code CLI)
    • ~/Library/Application Support/Claude/local-agent-mode-sessions/**/.claude/projects/**/*.jsonl (Claude desktop "cowork" / local-agent-mode sessions)
  3. Config inventory — ~/.claude/settings.json, plugins, skills, MCP servers

Then produces a ranked report of leaks with ballpark weekly $ savings for each.

How to run it

python SKILL_DIR/scripts/audit.py --days 7

Outputs JSON to stdout. You (Claude) then synthesize a narrative report in the user's language — default English, switch to match the user's current conversation language.

Language handling

  • Default: English
  • If the user's recent messages are in another language, write the report in that language
  • Technical terms (ccusage, /compact, /rewind, MCP, CLAUDE.md) stay untranslated

Report structure (adapt tone, keep sections)

  1. Spend summary — total, by model, by project, trend vs prior week (from ccusage)
  2. Top bottlenecks — session / project / file Pareto view: where to look FIRST
  3. Top leaks ranked by weekly savings — each with:
    • Severity badge (🔴 critical / 🟡 warning / 🟢 suggestion)
    • Evidence (3-5 bullets with numbers)
    • Estimated weekly cost + savings
    • Concrete fix action
    • Thariq citation where applicable
  4. Other ideas worth considering — 1-3 user-specific suggestions you (Claude) brainstorm based on the user's profile. The canned detectors catch patterns that generalize; this section catches patterns unique to this user. Read references/additional-optimizations.md for seeds (language efficiency, off-peak shifting, runaway cron check, local-model offloading, cache-TTL strategy, desktop-client blindness, skill pruning) and the brainstorming pattern. Curate 1-3 that actually apply to THIS user — don't list them all. If nothing fits, skip the section entirely.
  5. One fix to apply this week — single highest-leverage action
  6. Trend / context — plan-fee share, savings as % of subscription week

Leak detectors (v1)

Detector What it catches Source
tool_schema Full MCP tool schemas loaded every turn (~20k tok) — only fires if ENABLE_TOOL_SEARCH is OFF Samarth Gupta audit
hook_bloat Session-start / PreCompact hooks re-injecting large output into every session Novel
claude_md_bloat CLAUDE.md > 2k tokens, paid on every turn Anthropic cost doc (200-line target)
model_selection Opus used on short/simple turns where Sonnet would suffice Novel
context Turns past 400k-token context (context rot zone) Thariq Shihipar, Anthropic
skill_descriptions Total skill-description budget per turn (flags fat individual skills + bloated totals) Novel
bash_antipatterns cat/head/tail/find/grep via Bash instead of native Read/Glob/Grep Samarth Gupta audit
cache Sessions with <50% cache hit ratio (churn-driven cache misses) Novel
file_reads Same file Read 3+ times in one session (rewind candidate) Thariq Shihipar, Anthropic

Prerequisites

  • Node.js 20+ for ccusage (auto-fetched via npx — no install needed)
  • Python 3.11+ for the analyzer
  • Read access to ~/.claude/projects/, ~/.claude/settings.json, and (if you use the Claude desktop app's cowork mode) ~/Library/Application Support/Claude/local-agent-mode-sessions/ (already yours)

If ccusage is unavailable, the audit proceeds without baseline $ totals — detectors still work from JSONLs alone.

How to frame savings — READ THIS

Most users are on a flat-rate subscription (Pro $20 / Max 5x $100 / Max 20x $200). Reporting "saves $2,200/week" when they pay $200 flat is misleading — they won't "save" that from their pocket. What they actually gain:

  1. Headroom before hitting weekly rate limits (the real pain for Max users)
  2. Better model quality (less context rot, fewer cache-miss penalties)
  3. Capacity for more projects on the same plan
  4. If API user: actual dollar savings

Narration rules when writing the report:

  • Lead with tokens reclaimed per week, not dollars. "~3.9B tokens/week reclaimable" is honest.
  • Frame as category reduction: "~80% reduction in Opus spend on this category". Percentages ground the claim in the leak itself.
  • Mention plan capacity when helpful: "≈ 15% of your Max 20x weekly Opus allowance". Ask the user for their plan only if they haven't said; otherwise don't guess.
  • Put dollar figures in parentheses as context, not the headline: "(≈ $6,800/week at Anthropic API list pricing — reference only; your subscription is flat-fee)".
  • For the total line at the bottom, use "capacity reclaimable" not "savings". If user hits rate limits, optionally add: "this could let you stay on your current plan instead of buying a second subscription".
  • API users are the exception — for them, dollar savings are direct. If you know they're API-direct, lead with $.

Detectors compute all of:

  • est_weekly_tokens — honest, plan-neutral primary metric
  • est_weekly_cost_usd — at API list pricing
  • est_weekly_savings_usd — what the fix would eliminate (at list pricing)

Plan limits are published in scripts/cost_model.py (Pro/Max5x/Max20x ranges). Use plan_savings_summary(amount, plan) helper to generate the "≈ X% of subscription-week" phrasing.

Why we still compute dollars internally: for ranking. Dollar impact is the cleanest way to prioritize leaks across heterogeneous categories.

What the skill does NOT do

  • Does not edit your CLAUDE.md, settings.json, hooks, or skills automatically
  • Does not send transcripts, settings, or any content over the network
  • Does not authenticate to Anthropic or any external service
  • Does not analyze other coding assistants (Codex, Cursor, Aider) in v1 — see roadmap

Recommended invocation pattern

  1. Run audit.py --days 7
  2. Read the JSON output
  3. Present findings in the user's language as a tight report (see "Report structure" above)
  4. After presenting, offer to walk through fixes inline — no separate subcommand:

    "Want me to apply any of these? I can: (a) add the Sonnet default to <project>/.claude/settings.json, (b) trim the oversized CLAUDE.md, (c) enable ENABLE_TOOL_SEARCH. Pick any."

    • For each fix the user picks: show the exact diff, ask y/N, back up the file with a timestamped copy, then write.
    • Never modify settings.json, hooks, or CLAUDE.md without explicit per-fix confirmation.
  5. If the user wants real-time prevention (they ask "how do I stop this from happening again?"), propose user-specific hooks. See references/hook-design.md for principles and patterns. Critical rules:
    • Consult the claude-code-guide agent or https://code.claude.com/en/docs/claude-code/hooks for the current hook API before writing any hook code — the spec changes, don't rely on memory
    • Design hooks matched to THIS user's actual waste profile (project, thresholds, leak type), not generic one-size-fits-all hooks
    • Informational at objective thresholds, never prescriptive on tool choice
    • Always show the exact script + settings.json diff, per-hook y/N, kill-switch included
  6. Re-run after 1-2 weeks to measure delta

Roadmap (v2+, not shipped)

  • User-specific hook designer — guidance for Claude to propose hooks matched to the user's audit profile (principles already in references/hook-design.md; surface this in step 5 of the invocation pattern)
  • Cross-assistant support: Codex (AGENTS.md, reasoning_effort), Aider (.aider.conf.yml, map-tokens), Cursor (Auto vs API pool routing)
  • More detectors: extended-thinking budget runaway, agent-team 7x multiplier, .claudeignore absence, plan-mode underuse, stale-session resume, pasted-blob vs @file mentions
  • Auto-weekly cron digest (to Telegram or email)
  • Trend tracking: store audit results over time, show week-over-week deltas

Authoritative references

Baked into the analysis:

Privacy & safety

  • All analysis is local. No network calls except the optional npx ccusage@latest fetch.
  • Transcript content (tool result payloads, file contents, user messages) is parsed for size/counts/tool-names only — never retained, never transmitted.
  • Settings.json is read-only. Nothing is written.
  • Detectors summarize patterns; specific content (e.g., customer names, code) is not extracted into the report.