Claude Limits Reverse Engineering Skill — Development skill for Claude Code

claude-limits-reverse-engineering-skill

Reverse-engineering Claude Code usage limits from local JSONL ground truth.

The problem

Claude Max at `$200/month` gives you throughput, then hides the meter. The dashboard shows percentages, throttling can arrive without warning, and Anthropic does not publish the formula that maps token activity to dashboard usage. That makes capacity planning guesswork when you are deciding whether to keep a long session alive, switch models, or stop before the wall.

The common community assumption has been simple: treat `cache_read = 0` and focus on input, output, and cache creation. That assumption is wrong. It misses the token class that dominates real Claude Code traffic, so it understates usage until the dashboard proves otherwise.

The discovery

Current best fit is Formula E. `CU = input * 1 + output * 5 + cache_creation * 1 + cache_read * 0.58`. Weekly limit is about `374,000,000 CU`. The active registry entry in `reference/models/registry.json` was fit on `11` calibration points with `0.57%` MAE and `1.14%` max error. Dashboard percentages are integers, which injects about `+/-0.5%` rounding noise into every calibration point.

The important result is not the formula shape. It is what the weights say about cache reads. They cost about `58%` of fresh input, which matches server-side KV cache memory bandwidth, not free reuse. Formula A, the earlier model with `cache_read = 0`, fit worse because it ignored the dominant token type. Across the current calibration set, that means ignoring roughly `70%` of all tokens.

Calibration point 11 makes the failure mode obvious. Token composition was `cache_read 70%`, `cache_creation 30%`, `output 0.4%`, `input 0.04%`. CU contribution after weighting was `cache_read * 0.58 = 56%`, `cache_creation = 41%`, `output * 5 = 2.7%`. The meter is mostly cache activity, not fresh prompt text.

Install

Clone the repo, enter the root, then install the package editable. The package target in `pypr