DEV Community

Raunak Pathak
Raunak Pathak

Posted on

Where my Claude Code quota actually went (208 sessions of logs)

#ai #python #claudecode #productivity

cc-quota-doctor output on 208 sessions

My Claude Code limits kept running out faster than I expected, and the usage counter only told me how much I'd used, not where it went. Claude Code already keeps a transcript of every session on disk, in ~/.claude/projects. So I built a small tool, with the help of an AI agent, that reads those files and summarizes them. Then I ran it on my own history.

This post covers what the logs showed, what the docs say about it, and the habits I changed.

The numbers (208 sessions)

This is an anonymized and rounded run on one developer's history (mine):
Sessions 208
Longest session 9,849 turns, 68 compactions
Cache rebuilds after > 60 min away 280, ~81.6M cache-write tokens
Cache rebuilds after > 5 min away (only matters on the 5-min TTL) 417, ~112.8M
Mid-session model switches 37, ~9.07M tokens re-read uncached
Average context re-read per turn ~374k tokens
Output / cache write / cache read 24.6M / 260M / 12.5B
Subagents 24% of raw tokens
Largest CLAUDE.md ~3k tokens

One caveat before anything else: cache reads are 98% of the raw tokens here, but that is not 98% of my quota. Cache reads are cheap per token, and Anthropic doesn't publish how each token type counts against plan limits. These are raw token counts. The only honest way to measure a change is to compare /usage before and after.

Three things I had wrong

All three are covered in the official doc How Claude Code uses prompt caching.

1. The cache lifetime isn't always 5 minutes. On a Claude subscription, within plan usage, the main conversation's cache lasts 1 hour. Subagents, compaction and other requests get 5 minutes. With an API key, usage credits or a cloud provider, everything is 5 minutes. And once you go over your plan limit and draw on usage credits, the main conversation drops to 5 minutes too.

2. After a long break, /compact is the expensive option. Once the cache has expired, the next request recomputes the full context. The summarization request behind /compact reprocesses the whole history uncached, "which is why /compact costs the most when you resume an old session" (from the doc). My 280 rebuilds after more than an hour away were exactly this pattern: coming back to a huge session and carrying on.

3. Switching /model mid-session re-reads everything. Each model has its own cache, so after /model the next request re-reads the entire history with no cache hits. I did this 37 times. Changing effort level mid-session does the same on most models.

Habits I changed

  • Coming back after a break longer than your TTL: start a fresh session and paste a short summary of where you left off. Or /rewind to an earlier, already-cached point if you're abandoning a path. Don't /compact first.
  • Compact while the cache is warm. While the cache is warm, /compact reads your prefix from cache and is relatively cheap. Run it at natural breaks between tasks rather than waiting for auto-compaction mid-task. /recap shows a summary without replacing history.
  • One task per session, and /clear between unrelated tasks. A 9,849-turn session re-sends a lot of context every turn.
  • Pick the model and effort level at the start of a session, not halfway through.
  • Keep CLAUDE.md lean. It's part of every request; I aim for under ~1,500 tokens. Editing it mid-session doesn't break the cache, but the edit doesn't apply until /clear, /compact or a restart. Run /context in a fresh session to see what actually loads.
  • Keep tool output small. Read files with offsets and limits, grep before reading, and pipe commands through head, tail or grep.
  • Use subagents deliberately. Each subagent builds its own context and uses the 5-minute TTL. Narrow prompts, short requested outputs.
  • Check your hit rate. /usage shows a Prompt cache (main) hit ratio (v2.1.251+).

Run it on your own logs

cc-quota-doctor is MIT-licensed, standard-library Python (3.9+), and works on Windows, macOS and Linux. It makes no network calls and uploads nothing.

pip install git+https://github.com/raunakpathak20/cc-quota-doctor-.git
cc-quota-doctor
Enter fullscreen mode Exit fullscreen mode

Useful flags:

cc-quota-doctor --top 10              # more projects/sessions
cc-quota-doctor --json > usage.json   # machine-readable
cc-quota-doctor --idle-minutes 5      # API key / usage credits (5-min TTL)
Enter fullscreen mode Exit fullscreen mode

It reports tokens per project and session, the subagent share, startup context size, which CLAUDE.md files load, idle cache rebuilds at both TTLs, model switches and compactions, the largest tool outputs, and a top-3 list of fixes for your own usage.

What it does not do: it doesn't bypass, reset or raise any limit, and it can't show your plan %. The transcript format is undocumented and may change, and some sizes are estimates (characters / 4). If your numbers look off, please open an issue.

Repo: https://github.com/raunakpathak20/cc-quota-doctor-

How it was built

I built it with an AI agent, reviewed it, and ran it on my own history. v0.2 was corrected after a QA pass against the official docs (the TTL details above were the main fix).

If you'd rather have the fixes ready-made, there's an optional $15 Pro kit (a CLAUDE.md-slimmer skill, warning hooks, a weekly report and a playbook that cites the docs): https://buy.polar.sh/polar_cl_69l29e1HavMF0OIreYDVgqTqPzCPoZjy3QAvI4ZK6Jb. The free CLI is the complete diagnostic.

I'm curious: how many idle rebuilds does yours show?

Top comments (0)