Rate-limit window — why you hit your Claude Code limit on Thursday and what actually spent it

Definition

A rate-limit window is the rolling period your AI coding subscription measures your usage against before your allowance refills. It is not a monthly bill and not a hard monthly quota. It is a moving span of time: usage from inside the span counts against you, and usage that falls out the back of it stops counting.

Claude Code meters you against two at once, and they behave nothing alike:

• The short window, measured in hours. Hit it and you wait. Annoying, visible, and self-correcting, since you go get coffee and it refills.
• The long window, measured across the week. This is the one that ruins a Thursday. It refills slowly, it is spent gradually across days of ordinary work, and nothing about any individual session tells you that you are burning it faster than you can afford.

Codex and other subscription agents apply the same basic idea with different spans. The mechanic is what matters, not the specific numbers.

Why running out feels random

Nothing about hitting a weekly window feels connected to what you did. That is not your imagination. It is a real property of how the windows work.

The spend is invisible at the moment you make it. A session that quietly carries a bloated context across forty turns costs many times one that does the same work on a lean window. Both look identical while you are in them. Neither prints a number. The expensive one only announces itself days later, as an allowance that ran out earlier than you expected.

The cause and the symptom are separated by days. By the time you hit the wall on Thursday, the habits that put you there happened Monday and Tuesday. There is no feedback loop tight enough to learn from, so the same pattern repeats next week.

Volume is a bad proxy for spend. "I used it a lot this week" is much weaker than it sounds. Two people doing the same amount of work can differ several-fold in what they spend, entirely on habit: how much context they carry, how often the agent re-reads a file it already had, and whether routine work went to an oversized model.

What actually spends the window

Almost none of it is the thing people assume, which is the volume of code generated. Output tokens are usually a small share. The window mostly goes to:

• Context carry: a model has no memory between turns, so the whole conversation is re-sent every time. Carried context is billed at cache-read rates where the prompt cache holds, which is roughly a tenth of fresh input, and at above full price on the turns where it breaks. This is normally the largest line item and the one nobody sees.
• Cache invalidation: editing a file already in context, going idle past the cache expiry, or compacting all rebuild that cache. The same tokens swing more than tenfold in price depending on whether the prefix still matches.
• Re-reads: the agent reading a file it already has in context. Pure waste, since you pay again for something you already bought.
• Oversized models on routine work: a trivial task routed to a top-tier model costs several times what it needed to. See model right-sizing.
• Standing config: your CLAUDE.md, skills, plugins, and MCP servers are charged on every turn, before you have even stated the task.
• Grind: the third, fourth, and fifth attempt at something that was not going to work on the second.

What you can actually do about it

The useful move is not "use it less." It is to find which of the above is yours, because they are not equally distributed. Most people have one dominant habit rather than a bit of all six.

That is measurable from data already on your machine. Claude Code writes a session transcript for every session it runs, and those transcripts contain the token accounting, the tool calls, and the file paths. Reading them back tells you where the week went, without needing to have instrumented anything in advance.

You can do this for free, on your own machine, with no account:

npx @promptster/cc-audit

It reads the transcripts already in ~/.claude/projects, prints the breakdown to your terminal, and sends nothing. It never reads the contents of your files. The analysis runs on token accounting, tool calls, and paths, so nothing about the code you are working on is examined.

What a rate-limit window is NOT

• Not a monthly quota: it rolls. Usage ages out of the window continuously rather than resetting on a calendar date.
• Not a measure of how much work you did: it measures tokens, and tokens track habit at least as much as output.
• Not something you fix by writing shorter prompts: your prompts are a rounding error next to what the window carries on every turn.
• Not a penalty: hitting it is information about your workflow, not a verdict on your effort.

Related reading

• Context compaction — what the agent does when the window fills, and what it costs you.
• Model right-sizing — the cheapest single fix for most people.
• Context efficiency — the discipline behind carrying less.