Error / Message
Unexpectedly high token usage
A session using far more tokens than expected is usually explained by large file reads, verbose tool output, or a long conversation that hasn't been compacted.
/cost shows the actual usage for the current session — worth checking directly rather than guessing, since it's easy to underestimate how much a few large file reads or a long back-and-forth actually costs.
Reading several large files early in a session, then continuing to carry that content forward in every subsequent turn, is one of the most common silent multipliers — /compact is the direct fix once that context is no longer all needed in full detail.
Repeatedly re-reading the same file across a session (rather than trusting what was already read) is a smaller but real contributor worth noticing in a long session.
Run /cost to see actual usage, then /compact if a lot of it is old contextFrequently asked questions
What does "Unexpectedly high token usage" mean in Claude Code?
A session using far more tokens than expected is usually explained by large file reads, verbose tool output, or a long conversation that hasn't been compacted.
How do I fix it?
Try: Run /cost to see actual usage, then /compact if a lot of it is old context
Is this something to worry about?
Repeatedly re-reading the same file across a session (rather than trusting what was already read) is a smaller but real contributor worth noticing in a long session.
Is this covered in the Claude Code Toolkit?
Yes — Unexpectedly high token usage and patterns like it are part of the full command, hook, and template pack included with a Claude Code Toolkit subscription.
Want the full command, hook, and template pack?
This is one pattern out of the full Claude Code Toolkit — subscribe for the complete set, plus everything we add going forward.
Subscribe to the toolkit — $79/mo