Claude Code "What's contributing to your limits usage?": How to Read the /usage Breakdown#
Published by Alex Sorokoletov
"What's contributing to your limits usage?" is the section of /usage that shows what used most of your Claude plan limits. It scans the sessions saved on this machine for the last 24 hours and 7 days and lists each cause with its share, such as cache misses, long context or subagents. Run /usage, press d or w to change the period, and press f to apply the fixes.
From v2.1.312 the heading reads "What's contributing to your usage?". The release notes still use the old name.[1]
What the section shows#
Open /usage (also /cost and /stats) in the terminal. The Usage tab shows the session cost, the plan bars ("Current session", "Current week (all models)" and model-specific weekly rows), and then this section, with the subtitle "Approximate · sessions on this machine only". In v2.1.317 it has three parts:
- Recommendations. Up to 5 rows, largest share first. Each row is a share of your usage and one action, for example
85% Start fresh when you switch tasks · run /clear. A cause appears only when it is 10% or more of the period's usage. - Sources. Top skills, subagents, plugins and MCP servers, each with its share ("% of usage"). Each list shows 8 rows and then "… N more". Before any attributed request is saved, the section says "No attribution data yet · accumulates as you use Claude".
- Loops. One row per
/looptask with its run count and tokens (v2.1.243 or later).[2]
The shares overlap. One request at 160K context that missed the cache counts for both causes, so the percentages do not add up to 100. If nothing reaches 10%, the section says "Nothing over 10% in this period" and suggests the other period.
A comment on issue #105125 shows a typical 7-day result on a Max plan: 92% from general-purpose subagents, 85% at long context, 40% from sessions active 8 hours or more, 24% while up to 7 sessions ran at once, and 15% from cache misses.
How the share is weighted#
The section does not count raw tokens. Each request is weighted by its token type and model:
| Token type | Weight |
|---|---|
| Cache read | 1 |
| Uncached input | 10 |
| Cache write | 12.5 |
| Output | 50 |
The sum is then multiplied by a model factor: Haiku 1, Sonnet and other models 3, Opus 5, Fable 10. One Opus request that writes 100K tokens to the cache therefore weighs as much as about 6 million Haiku cache reads.
When each cause is flagged#
All rules are for v2.1.317. The 24-hour and 7-day periods use the same rules.
| Row title | Cause | Rule | Fix it suggests |
|---|---|---|---|
| Compact before you step away | Cache miss | A request with more than 100,000 input tokens not read from the cache (uncached input, plus cache writes that replace context which was cached before) | /compact |
| Start fresh when you switch tasks | Long context | A request with more than 150,000 input tokens | /clear |
| Give simple subagents a cheaper model | Subagent-heavy sessions | A session with 3 or more subagent requests, or where subagents are more than 50% of the session's usage | A prompt that gives search and lookup agents a cheaper model |
| Run fewer sessions at once | Parallel sessions | 4 or more sessions with a request in the same 5-minute window | None (shows the peak, "up to N at once") |
| Stop sessions you no longer need | Long-running sessions | A session with requests in 8 or more different clock hours | None |
| Switch from max to high effort | Max effort | A request sent at max effort | /effort with a lower level |
| Save workflows for big tasks, or Turn off ultracode | Workflows | A request made inside a workflow | /effort ultracode off when ultracode is on |
| Trim CLAUDE.md, Turn off skills you don't use, or See what fills your context | Always-on context | The main conversation starts with more than 40,000 tokens before your first message | A prompt that shortens the largest CLAUDE.md or turns off unused skills, MCP servers or agents; else /context |
| Read FILE in parts, or Shorten the output of "COMMAND" | Large tool results | A tool result of more than about 10,000 tokens that stays in the context | A prompt that adds a CLAUDE.md rule for that file, command or MCP tool |
Skill, subagent, plugin and MCP-server rows join the list when one source is 10% or more, with a prompt such as "Run /NAME on a cheaper model" or "Turn off NAME when you don't need it".
How the fix key works#
When a row has a fix that can run in the session, the footer shows f with "fix this", "fix both" or "fix all N". Pressing f queues messages in the current conversation: any /effort command first, then one prompt for the rest, which starts "Fix what /usage flagged. Show me each change before you make it." Claude then proposes each change for you to accept. With Remote Control on, nothing is sent and Claude Code says "Turn off Remote Control to use fixes." The fixes arrived in v2.1.305.[3]
Where it shows and what turns it off#
The section needs every condition in this table. There is no setting or environment variable that turns it off for one user.
| Condition | Default | What changes it |
|---|---|---|
| Signed in with a Claude subscription (Pro, Max, Team or Enterprise) | n/a | An API key, Bedrock, Vertex, Foundry or a Claude apps gateway shows the session cost (or the gateway spend limit) without this section |
| Plan usage loaded | n/a | If the usage endpoint fails with no saved data, /usage shows an error and r to retry instead |
| Organization allows the transcript scan | Allowed | The organization policy allow_usage_transcript_scan (v2.1.248 or later). When it is denied, the section shows the reason, for example "Not shown under your organization's policy: this breakdown is built by scanning the session transcripts saved on this machine." |
| Session transcripts on this machine | Saved under ~/.claude/projects | Only .jsonl files changed in the last 7 days are read, subagent transcripts included |
claude -p "/usage" prints the same section as text, with "Last 24h" and "Last 7d" blocks. The SDK gets the same data from the get_usage control request, which takes skip_behaviors: true to skip the scan (v2.1.261 or later). In VS Code, the Account & usage dialog shows the same breakdown (v2.1.174 or later).[4]
Timeline: shipped before it was announced#
The breakdown, its heading and its causes each landed in a different release. Most of them did not have a release-notes entry at the time.
| Version | Published | Change |
|---|---|---|
| v2.1.108 | 2026-04-14 | "What's contributing to your limits usage?" appears in /usage with five causes: cache misses over 100K tokens, context over 150K, subagent-heavy sessions, 4+ parallel sessions, and sessions active 8+ hours. Not in the release notes. |
| v2.1.121 | 2026-04-27 | Shares per skill, subagent and plugin. Not in the release notes. |
| v2.1.149 | 2026-05-22 | MCP servers join the lists, and the first release-notes entry describes the per-category breakdown of skills, subagents, plugins and MCP servers.[5] |
| v2.1.174 | 2026-06-11 | The same breakdown in the VS Code Account & usage dialog.[4] |
| v2.1.243 | 2026-08-24 | A Loops breakdown for /loop tasks.[2] |
| v2.1.248 | 2026-08-27 | The allow_usage_transcript_scan organization policy can hide the section. Not in the release notes. |
| v2.1.299 | 2026-10-14 | New causes: max effort, workflows, always-on context and large tool results.[6] |
| v2.1.305 | 2026-10-20 | Each cause becomes a one-line fix that names its source, and f applies the fixes.[3] |
| v2.1.311 | 2026-10-26 | Cache misses on a subscription now show. Before, only uncached input counted, and a miss on a subscription is mostly a cache write, so the row almost never appeared.[1] |
| v2.1.312 | 2026-10-27 | The heading becomes "What's contributing to your usage?". Not in the release notes. |
Does it explain fast-draining limits?#
Since mid-October, several issues report weekly limits that drain faster with the same work: #105125 (Opus, 72% of the week after 2 days, 15 reactions), #103376 (0% to 54% in 22 hours, 16 reactions), #101937, #105122 and #105240. The breakdown answers part of the question:
- It shows local causes. If a share is high for subagents, long context, parallel sessions or cache misses, that is where your usage went, and the fix row tells you what to change. Before v2.1.311 a subscriber's cache misses were missing from the list, so run the scan again on v2.1.311 or later.
- It does not show a change in how Anthropic counts usage. All shares are relative to the weighted usage on this machine. If your workflow and your shares did not change but the plan bars rise faster, the breakdown cannot tell you why. It also does not include other machines, Claude Desktop chat or claude.ai.
- It does not include requests that are not saved locally. Cloud sessions and sessions on other devices are not counted.
For a drain report, a paste of the 7-day result from v2.1.311 or later, as in the #105125 comment, gives the most useful data.
Should you act on every row?#
Act on the rows with a large share and a cheap fix: /clear between tasks when long context is high, /compact before you leave a large session, and a cheaper model for search subagents. Treat "Run fewer sessions at once" and "Stop sessions you no longer need" as a check, not a rule: parallel or long sessions can be the work you want. Read each change that f proposes before you accept it, because the prompts edit CLAUDE.md, agent files and settings.
FAQ#
Q: What does "What's contributing to your limits usage?" mean in Claude Code?
A: It is the section of /usage that shows which causes used most of your plan limits in the last 24 hours or 7 days, from the sessions saved on this machine. Since v2.1.312 it reads "What's contributing to your usage?".
Q: Why don't I see the breakdown in /usage?
A: It shows only when you are signed in with a Claude subscription and the plan usage has loaded. An API key, Bedrock, Vertex, Foundry or a gateway does not get it, and an organization can hide it with the allow_usage_transcript_scan policy.
Q: Why do the percentages add up to more than 100%?
A: The causes overlap. One request can be a cache miss, long context and a subagent request at the same time, and it counts in each row.
Q: Is the breakdown accurate?
A: It is approximate. It weights local token counts by type and model, and it includes only sessions on this machine, not other devices or claude.ai.
Q: What does the f key do in /usage?
A: It sends the suggested fixes to the current conversation: /effort changes first, then one prompt that asks Claude to show each change before it makes it. It needs v2.1.305 or later and does not work over Remote Control.
Q: Can I turn off the transcript scan?
A: Not with a user setting or environment variable. Organizations can turn it off with the allow_usage_transcript_scan policy. SDK callers can skip it with skip_behaviors: true on get_usage.
Q: Which version added it?
A: v2.1.108, published April 14, 2026. The release notes first mention it in v2.1.149 and first name the heading in v2.1.311.
Sources: [1] Claude Code changelog, v2.1.311 | [2] Claude Code changelog, v2.1.243 | [3] Claude Code changelog, v2.1.305 | [4] Claude Code changelog, v2.1.174 | [5] Claude Code changelog, v2.1.149 | [6] Claude Code changelog, v2.1.299
Related: Claude Code environment variables glossary | Prompt cache 5m instead of 1h | Context Window Management Guide | Claude Code v2.1.108 analysis | Claude Code v2.1.305 analysis | Claude Code v2.1.311 analysis | Claude Code v2.1.312 analysis