/usage is the built-in Claude Code command that shows how much of your plan you have used and where it went. When a usage limit drains faster than you expect, this is the first place to look.
What it is
A command you type in any Claude Code session. What it shows depends on how you sign in:
- Session block, on every plan: token counts per model for the current session, an estimated cost and a
Prompt cache (main)line with the cache hit ratio and misses (v2.1.251 or later; see Prompt caching). The dollar figure is computed locally from token counts at API list price. On Pro and Max it is not what you pay./clearresets this block. - Plan usage bars, on Pro, Max, Team and Enterprise: how much of your session and weekly limits you have used, and when each resets.
- Usage breakdown, on the same plans:
- Attribution: your recent usage split between skills, subagents, plugins and each MCP server, as a percentage of the total. An MCP server counts only for the requests that used one of its tool results.
- Behavior flags: patterns such as long context or cache misses, shown with a tip when one accounts for 10% or more of recent usage. Since 2.1.299, it also warns about max effort, workflows, context that stays loaded all session and large tool results.
- Loops: a row per heavy
/loopor other scheduled task, with how often it fires, how many times it ran, its total and per-run tokens and when it last ran (v2.1.242 or later).
- Usage-credits row, while usage credits are on: this month’s spend against your spend limit.
Press d or w to switch the breakdown between the last 24 hours and the last 7 days.
What problem it solves
On a subscription you see a percentage, not a bill. When you hit a limit after what felt like an hour of light work, you cannot tell whether it was a forgotten /loop, an MCP server returning huge results, subagents running on an expensive model or one long session paying for its context on every turn. /usage names the culprit, so you fix the habit that costs the most instead of guessing.
How to try it
In any session:
/usageThen press w to see the week. If the usage endpoint is rate limited, /usage shows the last bars it loaded in the past hour with a Showing last-known usage note; press r to retry.
Usage example
Frontend
You work on a React app with a browser-automation MCP server connected, and your session limit is gone by early afternoon. /usage shows that MCP server with a large share of the attribution and a flag for large tool results: every page snapshot it returns lands in the context and is re-sent with each later request. Ask for the screenshot or the one element you need, or disable the server in /mcp when you are not testing the UI.
Backend
A Node service has a /loop that checks a CI build every few minutes. You forgot about it over lunch. The Loops row shows how often it fired and its tokens per run: each run sent the whole conversation, even with no one at the keyboard. Stop the loop, or run it in a fresh session with a small context.
Who it’s for and when
Everyone on a Pro, Max, Team or Enterprise plan, whenever usage feels high or right after you hit a limit. Check it again after you change a habit, to see whether the change helped. On an API key, the Session block is the useful part; the Claude Console has the authoritative billing.
Gotchas
- Only this machine. The breakdown is computed from local session history, so usage on claude.ai or another computer is missing.
- Approximate. The figures are estimates, not an invoice.
- The cost line is not your bill on a subscription. It prices tokens at API rates.
- Main conversation only for the cache line. Subagents are not included in
Prompt cache (main). - Over 100% was a bug. Before 2.1.299,
/usage, the limit warning and the status line could show more than 100%.
Links
- Manage costs effectively: track your costs
- Usage limits
- Statusline: the same limits on screen without typing a command
- Reducing token usage