free · about two minutes

Find out where yourtokens are going

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.

nothing is uploaded
no sign-up, no key, no account
no experience needed
copy, paste, enter

Do this

Follow the four steps. If you have never opened a terminal before, step 1 shows you how.

1

Open the terminal

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.

2

Check you have Node

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.

any computer
node -v

If you see something like v22.1.0, you are ready. Go to step 3.

If instead it says not recognized or command not found, you do not have Node yet. Get it from nodejs.org, take the big green LTS button, click through the installer, then close the terminal and open it again before trying once more. That last part catches most people.
3

Run the scan

One line, the same on every computer. Paste, press enter, wait a few seconds.

any computer
npx --yes claude-tokenscan

Your 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.

Paste in the terminal is not always Ctrl + V. In PowerShell, right-click pastes. On Mac it is Cmd + V as usual.
4

Run the second one

This one answers a different question: what every session is carrying before you have typed a single word. Same routine.

any computer
npx --yes claude-tokenscan preamble

Every 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.

What you will see

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 free file it writes for you

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.

What the scan finds, and what fixes it

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.

Reading whole files to find one linefree

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.

Fixed by investigate-first, surgical-patch and lean-build, which are in the free pack. They look narrowly and change narrowly.
Three hundred lines back for a three line jobfree

Long answers, the same explanation re-written every session, and code you never asked for.

Fixed by caveman and ponytail, in the same free pack. Short answers and the smallest change that works.
Too many windows, everything on the expensive modelfree

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.

Nothing to buy. Two lines in the free file above, and it is the cheapest win on this list.
One conversation that never ends$9

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.

Fixed by 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.

Common questions

Is this safe to run?

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.

Does this install anything?

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.

I am on a subscription, so what does the dollar figure mean?

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.

It says I spent far more than I expected.

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.

Do I have to buy anything?

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.

How do I know what it is running?

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.