Claude Code usage means one of three things: plan quota consumed against a rolling 5-hour window and a weekly window, raw token counts by category, or dollar cost. Run /usage to see quota bars and this session's tokens; /cost is an alias for the same command as of August 2026. Full history lives in the JSONL transcripts under ~/.claude/projects/, which are deleted after 30 days by default.
- Quota is what stops you working. On a subscription it is the only number that can.
- Tokens are the underlying unit and the only thing measured exactly.
- Cost is tokens times a rate, and on a subscription no money moves.
/usageanswers all three inside the CLI./costis now an alias for it.- History comes from the JSONL transcripts on disk, which expire after 30 days by default.
Three numbers, three meanings
Every argument about Claude Code usage is really an argument about which of these three numbers someone means. Sort that out first and the rest is mechanical.
What each number measures and when you should care.
| Number | Measures | Where it lives | Matters if |
|---|---|---|---|
| Plan quota | Consumption against the 5-hour and weekly windows | /usage, and the status line JSON | You are on a subscription |
| Tokens | Input, cache write, cache read, output | JSONL session transcripts on disk | You want to understand or optimise |
| Cost | Tokens priced at model rates | Derived, shown by /usage per session | You are on an API key |
What /usage shows in 2026
The built-in command has grown considerably, and most guides on the internet describe the 2025 version of it. As of August 2026, /usage is one screen with two halves, and /cost is documented as an alias for it rather than a separate command.
The two halves of the /usage screen.
| Half | Shows | Who it is for |
|---|---|---|
| Session block | Tokens and a dollar figure for this session, by model | API users; a proxy for intensity on a plan |
| Plan usage | Progress bars for your 5-hour and weekly limits | Pro, Max, Team, and Enterprise |
| Attribution | Share of recent usage by skill, subagent, plugin, and MCP server | Anyone trying to find the waste |
| Behavior flags | Long context, cache misses, flagged at 10 percent or more | Anyone whose usage climbs faster than expected |
- Press
dorwto switch the breakdown between the last 24 hours and the last 7 days. - The session dollar figure is computed locally at standard list rates, so it ignores contracted discounts and will not match an invoice.
- Session totals reset when
/clearstarts a new conversation. - The breakdown is computed from local session history on this machine, so work from another laptop or from claude.ai is not in it.
The two windows that can stop you
Subscription limits are enforced on two windows at once, and they behave differently enough that watching only one is how people get surprised.
The windows, as documented by Anthropic support in August 2026.
| Window | Resets | Fills over | Typical surprise |
|---|---|---|---|
| 5-hour session | Rolling, five hours from your first message | Hours | One heavy morning |
| Weekly | A fixed day and time assigned to your account | Days | Five ordinary days in a row |
Where the numbers actually live
There are four distinct places usage data exists, and knowing which is which explains every gap you will hit in tooling.
| Source | Contains | Read by |
|---|---|---|
/usage screen | Live plan bars plus session tokens | You, interactively |
| Status line JSON on stdin | rate_limits.five_hour and rate_limits.seven_day percentages and reset times | Any status line script |
~/.claude/projects/*.jsonl | Every request, model, and token count, timestamped | ccusage and other parsers |
~/.claude/stats-cache.json | The aggregated token and cost counts /usage displays | Claude Code itself |
~/.claude/projects/
-Users-you-code-my-project/
3f2a....jsonl one file per session
3f2a.../subagents/ subagent transcripts
3f2a.../tool-results/ large tool output spilled to diskThe four token categories
Every assistant message in the transcript carries a usage object with four counters, and they are priced very differently. Adding them together as if they were one number is the most common way to get a wrong answer.
Relative pricing, from Anthropic's published API rates.
| Category | Meaning | Relative price |
|---|---|---|
input_tokens | New, uncached input after the last cache breakpoint | Base input rate |
cache_creation_input_tokens | Written to the prompt cache | Above base input |
cache_read_input_tokens | Re-read from the cache | About 10 percent of base input |
output_tokens | Generated, including thinking tokens | Around 5x base input |
On a healthy long session, cache reads are usually the largest column by volume and a small share of the cost. If cache reads are not dominant, either your sessions are very short or something is invalidating the cache on every turn, which is exactly the behavior the /usage screen flags for you.
Why usage climbs in a long session
The most common complaint about Claude Code usage is that a quiet afternoon consumed a lot of it. That is usually not a billing error. It is one of five mechanics, all documented, and each has a different fix.
The five reasons a session costs more than your activity suggests.
| Cause | What happens | Fix |
|---|---|---|
| Long context | The full conversation is sent with every request, and each tool use sends another request carrying its results | /clear between unrelated tasks |
| Cache misses | The first message after a break longer than the cache lifetime reprocesses the whole context | Resume from a summary, or start fresh |
| Scheduled tasks | A scheduled task fires on its interval even while the session is idle, sending the full context each time | Remove the ones you are not reading |
| Agent teammates | Each active teammate runs its own context window and keeps consuming until it exits | Small teams, cheaper models, shut them down |
| Compaction | /compact reads the conversation it summarises, so compacting a large context is itself a large request | Use /clear when you do not need continuity |
The /usage breakdown flags whichever of these accounts for 10 percent or more of your recent usage, which makes it the fastest diagnosis available. Agent teams are the extreme case: Anthropic puts them at roughly 7x the tokens of a standard session when teammates run in plan mode.
Which number you should be watching
| If you are | Watch | Because |
|---|---|---|
| On Pro or Max | Quota headroom, both windows | Only interruption can hurt you |
| On an API key | Daily cost | Only the bill can hurt you |
| Deciding on a plan | Cost at API-equivalent rates | It is the comparable number |
| Optimising a workflow | Tokens by category | It shows you where the waste is |
| Running a team | Cost per person and per repo | It shows where the value is |
The mistake worth avoiding is watching cost on a subscription and concluding you are being expensive. You are not being billed for it. The number is useful as a comparison against the API and as a proxy for how fast you are consuming quota, and for nothing else.
Questions people ask
Run /usage inside an interactive Claude Code session. It shows this session's tokens and cost plus progress bars for your 5-hour and weekly plan limits, with a breakdown you can toggle between 24 hours and 7 days using d and w.
There is none any more. As of August 2026 the Claude Code commands reference lists /cost as an alias for /usage, so both open the same screen.
The /usage breakdown covers the last 24 hours or last 7 days from local history on that machine. For longer history, parse the JSONL transcripts under ~/.claude/projects/ or run a tool such as ccusage that does it for you.
It draws on the same allowance. Anthropic support states that usage across claude.ai, Claude Desktop, and Claude Code counts toward the same 5-hour and weekly limits, so heavy chat use reduces the headroom available to your agent.
In JSONL session transcripts under ~/.claude/projects/, one directory per project and one file per session, plus an aggregate in ~/.claude/stats-cache.json that backs the /usage screen.
Transcripts are deleted on startup once they are older than cleanupPeriodDays, which defaults to 30 days. Raise that setting or archive the directory if you want a longer baseline.
Usually deduplication. The same logical request can appear more than once across files after resumes and retries, so a tool that sums every usage object overcounts. Correct implementations deduplicate on the message ID and request ID pair.
Not as a bill, because the fee is flat. It is still useful as a measure of intensity, as a proxy for how fast you are burning quota, and as the number that tells you whether an API key would have been cheaper.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.