free · about two minutes
Claude Code already keeps a log of your sessions on your own computer. This reads that log and tells you what you spent, what was wasted, and what to do about it. You copy two lines and press enter. That is the whole thing.
Follow the four steps. If you have never opened a terminal before, step 1 shows you how.
Windows: press Windows, type powershell, press Enter. A blue window opens.
Mac: press Cmd + Space, type terminal, press Enter.
That black or blue window is the terminal. You type into it and press enter. Nothing you do here can break your computer.
Node is the thing that runs the script. You probably already have it, because Claude Code needs it. Copy this line, paste it into the terminal, press enter.
node -vIf you see something like v22.1.0, you are ready. Go to step 3.
One line, the same on every computer. Paste, press enter, wait a few seconds.
npx --yes claude-tokenscanYour report prints straight into the terminal, and the full version opens in your browser. Nothing is installed: npx fetches the script, runs it once and throws it away.
This one answers a different question: what every session is carrying before you have typed a single word. Same routine.
npx --yes claude-tokenscan preambleEvery skill you have installed loads its name and description at the start of every session, so Claude can pick between them. That block rides along on every message whether a skill gets used or not. This weighs it.
Want to read the code before you run it? tokenscan.mjs and tokenscan-preamble.mjs are the same two files the command fetches, in plain text, about 250 lines each. No dependencies and no network calls, which you can check yourself. The package is claude-tokenscan on npm.
A real run. Yours will show your own numbers.
Spent at list rates $404.82
on a subscription, this is the allowance you used
Re-reading what is ██████████████████········ 68% $276.69
already in the window
Producing something new ████████·················· 32% $128.13
68% of the money went on carrying the conversation, not on work.
Average context per call: 409,254 tokens.
In plain words: every time Claude uses a tool, it re-sends everything said in that conversation so far. The longer a conversation runs, the more of your spend is just paying to carry it. That is the single biggest thing most people can fix, and it is free to fix.
A fuller version of the same report opens in your browser at the end, with a section called What to do about it. It lists only the problems your own machine actually has. Where a fix is free it says so and points at the free file or the free pack. Where a fix is not free it names the pack and the price, with a button. If you have no problems, it recommends nothing.
You can skip the browser step with --no-open, and widen the window with --hours=168 for a week instead of a day.
The scan drops a file called TOKEN-DISCIPLINE.CLAUDE.md in your home folder. It is a set of house rules for Claude. Copy it into your project folder, rename it to CLAUDE.md, and Claude reads it automatically from then on.
# Token discipline ## Reading - Read with offset and limit. Never print a whole file to find one function. - Grep for the symbol first, then read the lines around the hit. - A wide search goes to a subagent, so its output never lands in this context. ## Sessions - One task, one session. End it when the task ends. - Two windows at most. A window you are not watching still re-sends its context when it acts.
This part costs nothing and it is the half of the problem that needs no tools at all.
Four problems come up most. Three of them are fixed for free. One is not. Here they are straight, so you can see where you land before you spend anything.
The answer needed twenty lines of a file. Claude read the whole thing, and now those two thousand lines ride along in every later message of that conversation.
investigate-first, surgical-patch and lean-build, which are in the free pack. They look narrowly and change narrowly.Long answers, the same explanation re-written every session, and code you never asked for.
caveman and ponytail, in the same free pack. Short answers and the smallest change that works.A window you are not even looking at still re-sends its whole conversation whenever it does something. And skimming a file does not need the most expensive model you have.
Usually the biggest single line on a scan. A conversation pays to carry its own history on every turn, so a long one gets expensive no matter how careful you are. Being tidy does not fix it. The work has to be split up.
subagent-driven-development and dispatching-parallel-agents in the full bundle, $9. They hand a piece of work to a separate helper, so the heavy reading happens over there and only the answer comes back to you.Three of the four are free. We would rather say that than pretend a scan proves you need to buy something.
It reads the session log Claude Code already writes on your computer, prints a report, and writes two files: the house-rules file in your home folder and a report in your temp folder. It makes no network calls at all, which you can confirm by opening the file and reading it. It changes nothing else.
No. npx downloads the package into a cache, runs it once and leaves nothing behind on your PATH. The only things written are the house-rules file in your home folder and a report in your temp folder, both named in the output.
It is what the same usage would have cost at published per-token prices. It is not a bill and there is nothing to pay. Treat it as the size of the allowance you used. The percentages, which are the part you act on, are the same either way.
That is usually the re-reading line. Every tool call re-sends the whole conversation up to that point, so one long session can cost many times what the same work would cost split across short ones. The first fix is free: end a session when its task ends.
No. Three of the four common problems are fixed by the free pack and the free file the scan writes. The one that is not is named above with its price.
The two files are linked above in plain text, and the published package contains exactly those files. If you would rather read first and run second, download tokenscan.mjs and run node tokenscan.mjs instead.