Skip to content

Claude Code

Tokendoctor cut its author’s Claude Code cost 38%

4 min read

Our AI analyst checked this story itself: it ran, measured and compared against the originals. What we checked

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →
Image: github.com

Tokendoctor is an open-source plugin for Claude Code. It shows where your sessions burn tokens and changes the settings behind them. Its author says two changes cut the cost per request of the main conversation by 38% at API list prices over six weeks of their own work. The first makes Claude Code summarize the conversation at 400K tokens instead of near the model’s limit. The second runs subagents, the helper agents Claude Code starts for side tasks, on Sonnet. The figure compares the month before the change with the week after it. The project’s GitHub page now calls it “one person’s before and after, not a controlled experiment.”

The reason a window size matters is simple. Claude Code re-sends the whole conversation on every turn, so a long session costs more with each step. When the history gets too big, Claude Code compacts it: a model writes a summary and the session carries on from there. On models with a native 1M-token window, that happens only at about 967K tokens by default. With the window at 400K, the author’s average context per request fell from 412K to 219K tokens. The author also says there is “no one pill”. If your sessions rarely pass 400K tokens, the window changes nothing for you, and a summary that lands just before you finish can cost more than it saves.

What it does

The plugin starts with your own numbers. /tokendoctor:sessions replays your past sessions at smaller windows and shows what each would have saved, without changing anything. The author calls that figure an upper bound, because a replay can’t see work the model would have redone after a summary. /tokendoctor:optimize runs 38 checks against Claude Code’s current docs. It fetches two public docs pages once a day and sends nothing of yours. It then proposes up to five changes, shows each one as a diff and applies only the ones you approve.

The optional “slide” is the more unusual part. It is off by default. When Claude Code would write a summary, the slide replaces old tool outputs with short pointers instead, and every prompt and answer stays word for word. In one of the author’s sessions, a summary took 65.3 seconds and the slide took 0.04. On Team and Enterprise logins, or on machines with managed settings, a built-in guard blocks the slide. Getting past it takes a machine-wide install with one sudo command, and only an administrator can do it where the organization delivers its own managed settings.

All costs are API list prices. On a Pro or Max plan, they show what the same work would cost on the API, since Anthropic does not publish how plan limits weigh each kind of token.

Our analysis

What we checked

On November 17 we ran tokendoctor’s fixes and its undo command on a test setup. We also recomputed its published benchmarks from the runs committed to the repository and read the current Claude Code docs.

How we check stories

The project page says undo lists every change the plugin made and can put any one back. In our run it didn’t. Four fixes were written to disk and never showed up in the undo list: removing a hook, installing an agent file, installing a status-line script and adding a rule that blocks reads of a file. Undo lists only changes to settings keys. The removed hook did leave a backup file, so it can be restored by hand. We ran the shell version of undo. The in-session /tokendoctor undo reads the same list, which we checked in the code but did not run.

The benchmark is thinner than its headline. For a week of work with every fix plus the slide, the project reports 11% to 21% lower cost. Those numbers come from two different versions of the slide. The newer one, the 11%, rests on two runs that came out 17.3% dearer and 39.5% cheaper on their own. Without the slide, the settings fixes were dearer in three of four comparisons. All 18 runs used Haiku 5.5 on version 0.4.1 (the plugin is now at 0.6.0) with subagents turned off, so the Sonnet-for-subagents half of the setup was never tested.

The main fix doesn’t need the plugin at all. Claude Code’s docs confirm the 967K default and list a built-in command, /autocompact 500k, that saves a window for the current model. It needs Claude Code 2.1.221 or later.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.