TokenSquirrel

Token-optimisation audit tool for Claude Code. Run periodic audits, get scored on 15 behaviours across three buckets — discipline, hygiene, and setup weight — and track improvements over time.

Based on the techniques in Token Economics Cheat-Sheet: Claude Code Cost Controls Reference.

No data leaves your machine.

Try it for a week

1. Run npx tokensquirrel — get your scorecard. Say Y to the nudge.
2. Use Claude Code normally for a week. The squirrel will find you.

The squirrel installs a Claude Code SessionStart hook (in ~/.claude/settings.json) that quietly checks how long it's been since your last audit. After 7 days, Claude itself will mention it at the top of your next session — no banners, no email, no daemon.

Remove the hook anytime: npx tokensquirrel claude --uninstall-nudge.

Quick start

npx tokensquirrel claude

Or install globally:

npm install -g tokensquirrel
tokensquirrel claude

tokensquirrel <tool> is a dispatcher. Today there are two tools — claude (the audit) and codex (a stub). Bare tokensquirrel is a back-compat alias for claude and prints a one-line stderr deprecation note when used with flags; the shim goes away in v1.0.

Usage

tokensquirrel claude                       Compact score + cost (default 24h)
tokensquirrel claude --detail              Full 15-behaviour scorecard
tokensquirrel claude --format md           Markdown output
tokensquirrel claude --hours 48            Score the last 48 hours
tokensquirrel claude --days 7              Score the last 7 days
tokensquirrel claude --weeks 4             Last 4 weeks only
tokensquirrel claude --project myapp       Filter by project name
tokensquirrel claude --trend               Show score history
tokensquirrel claude --trend 5             Show last 5 runs
tokensquirrel claude mot                   MOT inspection report (15-point service)
tokensquirrel claude skills                List installed skills
tokensquirrel claude skills --audit        Group by plugin, flag stale, suggest uninstalls
tokensquirrel claude skills --audit --fix  Interactively uninstall stale plugins
tokensquirrel claude --dashboard           Launch the local HTML dashboard
tokensquirrel claude --user-guide          Open the full user guide
tokensquirrel claude --label "day 1"       Tag this run with a snapshot label
tokensquirrel claude --no-save             Run without saving to history

What it scores

Discipline — actively managing context, cost, and model: /clear frequency, /context monitoring, /cost tracking, Plan mode usage, Model switching.

Hygiene — clean sessions and inputs: Paste hygiene, Session hygiene, Cache efficiency, Tool efficiency, MCP/plugin hygiene.

Setup weight — how heavy your install is per request: CLAUDE.md weight, Hook injection load, SessionStart noise, Skill bloat, MCP tool-schema weight.

Each behaviour is scored 0–100 with a letter grade (A–F).

Score trending

Every run automatically saves results to ~/.tokensquirrel/history.jsonl (older ~/.claude/claude-squirrel-history.jsonl is auto-migrated on first run). Use --trend to see how your scores change over time.

Data sources

Reads from your local ~/.claude/ directory:

• history.jsonl — per-message history
• stats-cache.json — aggregated token and activity metrics
• sessions/*.json — session metadata
• settings.json — MCP servers, enabled plugins, hook counts
• projects/**/*.jsonl — past transcripts (per-skill last-used; cached)
• ~/.claude/skills/ + plugin skill dirs — frontmatter token estimates
• All discovered CLAUDE.md files — total word count

License

MIT