/usage shows this session's token usage and estimated cost, along with the usage limits of your subscription plan, on one screen. You use it to see how much of your limit is left and what is using the most.
From actually using it
While reworking this site, I opened /usage twice to check usage. In a long session, it helps to check your limit status now and then.
How it works
At the top of the /usage screen is the Session block. It shows token usage statistics and cost for the current session. The cost is an estimate that Claude Code calculates locally from token counts at list price. The official docs also say to see the Usage page in the Claude Console for exact billing.
For Pro and Max subscribers, usage is included in the subscription, so the cost figure in Session is not what you are billed. Instead, you see the plan usage bars, activity stats, and a usage breakdown on the same screen. The plan usage breakdown shows the share by skill, subagent, plugin, and MCP server, along with recommendations for items you could cut back.
/cost and /stats are aliases for this command. /stats opens on the Stats tab. /usage is one of the commands that runs right away, without interrupting, even while Claude is responding.
How to read the screen
- Session block: total cost, API time, and input, output, and cache tokens by model. After /clear it is a new session, so it starts again from 0 (v2.1.211 or later).
- Prompt cache line: shows the share read from cache, cache misses, and whether the cache is still alive (v2.1.251 or later).
- Plan usage bars and breakdown: the d and w keys switch between the last 24 hours and 7 days.
- Recommendations: the percentage at the start of each line is how much of your usage that line accounts for, not the amount it would save. Overlapping lines can add up to more than 100%.
- f key: when "f to fix" appears at the bottom, Claude Code handles the recommendations it can apply (v2.1.305 or later). Lines that name a command, like run /compact, you have to run yourself.
- The figures are approximations calculated from the local session history on this device, so usage on other devices or on claude.ai is not included.
Why usage grows as a session gets longer
The cost docs explain the reason like this. Claude Code sends the whole conversation with every request. Thanks to the prompt cache, that history is read at the cache price, but in a session that has been open all day, even a one-line question is counted against usage as the whole conversation. The first message after a break reprocesses the entire context if the cache lifetime has passed. Subagents, scheduled tasks, and agent teams each send their own requests. /compact is itself a large request that reads the big context.
Ways to bring it down: use /clear between unrelated tasks, add instructions to /compact when needed, pick a model that fits the task, keep CLAUDE.md under 200 lines, and turn off MCP servers you are not using.
If text like "rate limited until" appears in /usage, it means the plan limits could not be fetched again, not that your work is blocked. After that time, press the r key to fetch them again.
Real examples
You worked in the same session all afternoon and your limit seems to be dropping faster than expected
/usage
The plan usage bars and breakdown show which skills, subagents, and MCP servers take a large share. If there is a recommendation in the "clean up context" category, reducing the context with /clear or /compact comes first.
You just finished a long task and want to check the current session's cost before moving on to something else
/cost
The same screen as /usage opens, and the Session block shows the session's total cost and tokens by model. If you run /clear afterward, this total starts from 0 in the new session.
You use an API key and the Session cost looks different from your bill
Compare the Total cost in /usage with the Usage page in the Claude Console
The cost in /usage is a local estimate. Exact billing is based on the Console's Usage page, so check there.
Common mistakes and when not to use it
- Reading the Session cost as your actual bill on a subscription plan. For subscribers it is not the billing figure.
- Trusting the /usage figures as a total across all devices. They are based on the local history on this device, so other devices and claude.ai are left out.
- Reading the percentage in a recommendation as the amount saved. It is only the share of usage it applies to.
- Thinking the previous session's total carries over after /clear. From v2.1.211, the new session's total starts from 0.
- Switching only the model when you hit a limit. Session and weekly limits are shared across models, so changing models does not lift them.
FAQ
Are /cost and /usage different?
/cost and /stats are aliases for /usage. /stats opens on the Stats tab.
Is the cost in /usage accurate?
It is an estimate calculated locally from token counts and list prices. If an admin has set organization rates, those rates are reflected. Exact billing is based on the Usage page in the Claude Console.
What do I do if I go over my usage limit?
Wait until the reset time that is shown, or, if usage credits are turned on, manage them with /usage-credits. The guidance differs by the kind of limit, so read the message on the screen first.
Checked against the official docs on 2026-10-30. Sources: Claude Code docs: Manage costs effectively, Claude Code docs: Commands. How we write