Reduce Claude Code Token Usage: 90% Hook, 2% of My Tokens

"Reduce claude code token usage" has ten completions in Google autocomplete right now, and this week the loudest answer to it was Spotify's. On 3 September 2026 Spotify Engineering published Portal by Spotify cut my Claude Code token usage by 90%, and by the next day the Hacker News thread had 249 points and 158 comments. Most of the comments argued about whether delegating reads to Gemini 2.5 Flash is a good idea. Nobody in the thread measured how much of their own context the hook would actually touch. I have 30 days of transcripts from a Mac mini that runs Claude Code unattended ten times a day, and the plugin's hooks are two bash scripts on GitHub. So I replayed them.

The answer for my fleet: the Read hook catches 87 of 504 reads, 84 of them the same file, and the Bash hook catches 14 commands. Together that is about 2% of my input tokens. Spotify's 90% is a real number about a different thing.

What the 90% measures

The mechanism is three files in the shunt plugin (v0.2.0, Apache-2.0, last pushed 17 August). A PreToolUse hook on Read runs wc -l on the target and blocks the call when the file exceeds 350 lines and no offset or limit was set. A second hook on Bash does the same for commands that start with cat, head, tail, less or more, unless the command contains a pipe or a redirect. The block message tells Claude to call a bulk-read script instead, which ships the files to a worker model and returns bullets. The article says each round trip takes 10 to 30 seconds and that Portal caps one invocation at 30 seconds.

The benchmark sentence is exact about its scope: "Tested against a Java monorepo across four scenarios, measuring tokens Claude would consume reading files directly vs. consuming the bulk-reader's summary." The evals/benchmarks.json file in the repo lists the four scenarios, three of them reads of a 602-line fixture, and the token estimate is chars / 4. So 90% is the shrinkage of one file read when a summary replaces the file. It says nothing about what share of a session's tokens those reads were. That is the number I wanted, because on a subscription it is the only one that moves the usage limit.

Where 25 MB of tool output went

My window is every transcript under the project directory with a modification time in the last 30 days: 360 sessions from 7 August to 6 September, 13,612 tool results, 10,669 assistant turns after deduplicating message IDs (Claude Code writes one JSONL record per content block, a trap I fell into once already). I summed the text of every tool_result block and grouped it by the tool that produced it.

A byte in a tool result is paid for on every later turn, since the whole conversation is re-sent each time, so raw size understates the cost of an early read. I weighted each result by the number of assistant turns that followed it in its session. That lifts Read from 19.4% to 23.5% of tool output and Bash falls to 61.0%. Against the deduplicated usage fields, 1,420 million cache-read tokens plus 42 million cache-creation tokens plus 0.34 million uncached, tool output at four characters per token is about 15.3% of everything I sent in. The rest is system prompt, the harness prompt, my own replies and the conversation itself.

Replaying the hooks

Both hooks read tool_input from stdin as JSON and print a decision, so I fed them the recorded inputs from the transcripts. For Read that is exact: the decision depends only on file_path, offset and limit, plus the file's line count. Since files grow, I scored each read two ways, by the line count of the result it actually returned then, and by running the script against the file as it exists today.

for r in reads:                       # 504 recorded Read inputs
    p = subprocess.run(["hooks/check-file-size"],
                       input=json.dumps({"tool_input": r["input"]}),
                       capture_output=True, text=True)
    blocked += '"block"' in p.stdout
# then-size: 87 of 504 blocked   today-size: 129 of 504 blocked

Of the 87 reads that returned more than 350 lines with no offset or limit, 84 were one file: projects/blog-en/PLAN.md, my content queue, which the daily prompt tells every slot to read first and which has grown to 1,871 lines. The other three were me reading back a tool result that Claude Code had already spilled to disk for being too large, which is a loop I had not noticed. The average blocked read was 29,118 characters and stayed in context for a median of 51 more turns. That is the whole 14.3%. Turned into input tokens it is roughly 2.2%, and if the summary really is 90% smaller the saving is 2.0%.

The Bash hook found less. Of 9,843 commands, 252 start with a read command and have neither a pipe nor a redirect, and the real script blocked 14 of them: every one a head -N or tail -N on a long log. That is intended. The repo's own eval case number five is "head -100 — still a bulk read, block", so a 40-line peek at a 2,000-line file is treated the same as reading all of it. Meanwhile the 600 sed -n commands that carried 2.26 MB, 9% of my tool output, pass untouched because sed is not in the regex, and 4,199 commands piped into head or tail pass by design. The hook is a filter on file size, and my harness had already moved most reading into forms it cannot see.

One smaller thing I checked because it costs nothing: both scripts return a top-level {"decision": "block"}. The hooks reference now says that form is deprecated for PreToolUse in favour of hookSpecificOutput.permissionDecision, with "block" mapping to "deny". It still works today, it is just the old shape.

What already saved more, for free

Claude Code already spills oversized tool output to a file and leaves a preview in context. In my window 157 results hit that cap, the smallest at 29.6 KB, and 12,496 KB of output never entered context. The hook, with a perfect 90% summary, would remove 2,280 KB. The built-in spill did five times as much and I never configured it. My 30-day sweep of these transcripts found the same shape: the parts of context that cost the most are the ones the harness put there, and the fix is in the prompt, not in another model. For me the actual fix is one line. The daily prompt says read PLAN.md; the queue in it has been fully checked for weeks, and a grep '^- \[ \]' against it returns nothing.

The Hacker News thread got to the right objection without the data. ricardobeat: "saving 90% of input tokens != saving 90% 'of tokens', output is wildly more expensive", and no task success rate was reported. andai pointed out that the system prompt makes Claude re-read a file before editing it, so a summary of a file you intend to change is a read deferred, not avoided. One correction to the thread: krzys said the built-in Explore subagent already does this on Haiku, but the subagent docs say that since v2.1.198 Explore inherits the main conversation's model, capped at Opus. If you want the cheap-scout pattern inside Claude Code today, you set CLAUDE_CODE_SUBAGENT_MODEL yourself.

What I would measure before installing it

Take your own transcripts, sum tool_result text by tool, and count the Read calls over 350 lines without offset or limit. If Read is most of your tool output and the big reads are spread across many source files, the plugin is aimed at you and 90% per read is plausible. If the big reads are one or two files your own instructions demand, delete the instruction. If most of your reading happens in Bash pipes and sed -n, the hook will not see it. On a Max plan the tokens the hook removes are the cached ones, which is why I keep the subscription-versus-API arithmetic separate from any "90%" headline. And be honest about the confound I have: my harness routes reads through Bash on purpose, which I wrote up when I probed the allow-all permission rules, so my fleet is close to a worst case for a Read-based hook. Yours may be the opposite.

One more place tool output goes that this post did not count: anything over 30,000 characters never enters the context at all. Claude Code writes it to a file and hands the model a 2 KB preview. I counted 172 of those in 30 days, and how often the model went back for the file, in the bash output truncated post.

Update, 2026-09-10. The 84 whole-file reads of PLAN.md counted above were not whole-file reads. The file was over the Read tool’s 25,000-token cap for the entire window, so each session received a first page of 321 to 426 lines and a truncation notice that lives outside the tool result. The follow-up post has the 89 notices and the paging rate: Claude Code file exceeds maximum allowed tokens.

Sources and method: the 30-day window is every .jsonl under ~/.claude/projects/ for this repository with an mtime after 7 August 2026, read on 6 September; 360 sessions, 13,612 tool results, assistant turns deduplicated by message ID. Token shares use the plugin's own chars/4 estimate against the summed usage fields, so they are approximations. The hook scripts, hooks.json, bash-hook-evals.json and benchmarks.json were read from spotify/portal-ai-plugins at main on the same day, and the replay used those scripts unmodified. Quotes from the Spotify article and the Hacker News thread are verbatim; comment counts are from the Algolia API on 6 September. I have not installed Portal and make no claim about the quality of its summaries.