Get value in 30 seconds

TokenSquirrel reads the data Claude Code already writes to ~/.claude/ and tells you, in plain English, whether your habits are costing you quality and money. There is no install step and no config — if you already use Claude Code, you already have everything you need.

Why this matters. For the long-form argument that token discipline is a professional skill (and the storm coming when frontier models get more expensive), see Part 1 of the Token Economics series. This guide is the practice; that essay is the why.

Run it

npx tokensquirrel              # alias for `tokensquirrel claude`
npx tokensquirrel claude       # the canonical form

That’s it. No flags. No setup. The first run takes a few seconds while npm fetches the package; subsequent runs are instant.

Dispatcher. tokensquirrel <tool> routes to a tool. Today there are two: claude (the audit you came here for) and codex (a stub — see Level 200). Bare tokensquirrel is a back-compat alias for claude; passing flags without the subcommand prints a one-line stderr deprecation note. The shim goes away in v1.0 — prefer tokensquirrel claude <flags> going forward.

What you’ll see

A compact card with four things:

• Overall grade (A–F) — a single letter summarising the last 24 hours of Claude Code use.
• Estimated daily cost — extrapolated from token counts and the public API price list.
• Sparkline — your overall score trend across recent runs, so you can see whether things are getting better or worse.
• One headline — the biggest single behaviour costing you money or quality right now.

Act on the headline

If the headline says “your cache hit rate dropped to 40%” — that’s the thing to fix today. If it says “you’ve never used /clear” — that’s the thing to try this afternoon.

You don’t have to read the rest of this guide to act on it. Run the command, read one sentence, change one habit. That’s the whole loop.

Where the data lives

Everything stays on your machine. TokenSquirrel reads ~/.claude/ and appends each run to ~/.tokensquirrel/history.jsonl. Nothing is transmitted, nothing is sent anywhere. You can delete the history file at any time and start fresh.

Tip: prefer reading docs in your terminal? Run npx tokensquirrel --user-guide to open this same content in your pager.

Next

When you’re ready for more than the headline — see Level 200 for the full scorecard, time windows, skills audit, and a weekly workflow that actually sticks.