← posts / ai integrations

Why your Claude Code limit disappears: read the /usage cache line and fix the five biggest token leaks

Claude Code now shows a Prompt cache line in /usage. How to read it, and five habits from Anthropic's cost docs that stop long sessions burning through your limit.

if.codesNov 20, 2026 · 5 min read#claude code#tokens#cost#hooksAI-assisted

A thread going around says Claude Code limits "leak" because every message re-sends the whole conversation. The mechanics are real, and Anthropic's cost documentation confirms them: usage climbs in long sessions because the full conversation goes along with each request, and cache misses happen after a break longer than the cache lifetime. What is new is that you can now see it. This post reads the line, then goes through five fixes the docs recommend.

Read the Prompt cache line

Run /usage. On Claude Code v2.1.251 or later, once the main conversation has its first API response, the Session block includes a Prompt cache line. The docs show this sample:

Visualizing the flow of cached tokens in a session.
Visualizing the flow of cached tokens in a session.
Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

What each part means, per the docs:

  • Hit share: the percentage of input tokens served from cache. Higher is better.
  • Misses: requests that re-processed content the cache already held, with the time of the last one and how many tokens were written back to cache. From v2.1.260 the line can name a likely cause, such as changed tool definitions.
  • Expected rebuilds: misses Claude Code caused itself, by compaction or by clearing old tool results. Counted separately.
  • Warm or cold: whether the cached prefix is still inside its lifetime. When cold, the line shows how long the session has been idle.

Two limits to know. It covers the main conversation only, not subagents, and /clear resets it. The 91% and 310.2k figures above are the page's example, not benchmarks. Dollar totals in the Session block (the page's sample shows a $0.55 total) are estimates computed locally from token counts, and the page says that block is intended for API users; subscribers see plan usage bars instead.

A habit that costs nothing: glance at the line before you walk away. If it says warm with a short TTL left, a quick follow-up is cheap. If it says cold, the next message rebuilds the prefix.

Fix 1: clear between tasks

The docs: use /clear to start fresh when switching to unrelated work, because stale context wastes tokens on every later message. Name the session first with /rename and come back with /resume if you need it. Compaction is not free either: /compact reads the conversation it summarises, so compacting a huge context is itself a large request. When you want a fresh start rather than continuity, /clear costs nothing.

Fix 2: keep CLAUDE.md small, move workflows into skills

CLAUDE.md is loaded at session start, so its tokens ride along even for unrelated work. The docs advise keeping it under about 200 lines with essentials only, and moving detailed workflows (their examples are PR reviews and database migrations) into skills, which load only when invoked. If you are on a plan, /usage can also show rows like "Trim your CLAUDE.md" with its token cost per request.

Keeping configuration files lean prevents unnecessary token bloat.
Keeping configuration files lean prevents unnecessary token bloat.

Fix 3: pick the model and effort on purpose

The docs say Sonnet handles most coding tasks well and costs less than Opus, which they reserve for complex architectural decisions or multi-step reasoning. Switch with /model or set a default in /config. Extended thinking is on by default and thinking tokens are billed as output tokens, so lower the effort with /effort for routine work. On models with a fixed thinking budget you can set MAX_THINKING_TOKENS (the page's example is 8000); adaptive-reasoning models ignore nonzero budgets, so use effort levels there. For simple subagent tasks, set model: haiku in the subagent's configuration.

Want AI wired into the systems you already run?I build LLM integrations with costs and quality you can see. The estimate is free.

Fix 4: cut noisy tool output with a hook

Test runs and log dumps fill context fast. The docs' example is a PreToolUse hook that trims test output to its last 100 lines. Register it in settings.json:

Filtering noisy tool output reduces the amount of data sent to the model.
Filtering noisy tool output reduces the amount of data sent to the model.
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

Then create the script (it needs jq installed). This is my version of the idea; the docs describe the behaviour (match npm test, pytest or go test, append tail -n 100 through updatedInput) and I have kept to it:

mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/filter-test-output.sh <<'EOF'
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
if [[ "$cmd" =~ ^(npm\ test|pytest|go\ test)( .*)?$ ]]; then
  new="$cmd 2>&1 | tail -n 100"
  jq -n --arg c "$new" '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: {command: $c}}}'
else
  echo '{}'
fi
EOF
chmod +x ~/.claude/hooks/filter-test-output.sh

Verify it: run /hooks and confirm the hook is listed under PreToolUse, or start claude --debug-file ./claude-debug.txt, ask for npm test and look for a "modified tool input keys" line in the log. If the log does not show it, the script's JSON shape is the first place to look. The docs also suggest a hook that greps a large log for ERROR instead of letting Claude read it, which they say cuts context from tens of thousands of tokens to hundreds.

Fix 5: push verbose work into a subagent

Running tests, fetching documentation or processing logs can consume significant context. Delegate it to a subagent: the verbose output stays in the subagent's context and only a summary returns. Subagent requests still count toward usage, and the Prompt cache line does not cover them; plan users see subagent usage in the /usage attribution breakdown. Also run /context to see what is using space, and /mcp to disable servers you do not use.

A five-minute checklist

  1. Run /usage, note hit share and misses.
  2. /clear when the task changes.
  3. Count CLAUDE.md lines; move workflows to skills.
  4. Check /model and /effort match the job.
  5. Add the test-output hook; use subagents for logs and docs.

I have not measured the savings from these changes; they depend on your sessions. The Prompt cache line is how you measure your own before and after.

Sources

if.codesI build RAG, AI integrations and agent pipelines on Go and Python backends — and write about it here.
// keep reading

More posts on AI and backends.

// free quote

Read something you need? I’ll quote it for free.

RAG, AI integrations, agents or the backend underneath — tell me what you have and what should change. I read every request myself.

Free · no commitment

Tell me what you have. I’ll tell you what it takes.

1Describe the projectA few sentences is enough — about two minutes.
2I review itI read it myself and may ask a follow-up question.
3You get a free quoteScope, approach and estimate — yours to keep, no strings.
What kind of project is it?
Free and without obligation. Your details are used only to reply — see the privacy policy.