Headroom

How to check your Claude Code usage with /usage

Type /usage in Claude Code to see plan limits, a breakdown of what used them, and a usage-credits row. Here is what each part shows and what the dollar figure means.

· 6 min read

Type /usage at the Claude Code prompt. On a Pro, Max, Ultra, Team or Enterprise plan it shows your plan usage limits, activity stats and a breakdown of what counted against those limits, according to the Claude Code commands reference. /cost and /stats are aliases for the same screen, and /stats opens on the Stats tab.

This post walks through what is on that screen, the keys that change it, and the one number on it that does not matter if you pay for a subscription.

What /usage shows

For subscribers, Anthropic's cost documentation says the screen holds a Session block plus "plan usage bars, activity stats, and a usage breakdown". In practice that means four things:

  1. The Session block. Token counts and a dollar figure for the current session. More on that figure below.
  2. Plan usage bars. These are your plan's limits: the session limit and the weekly limits, with when each resets. They describe the whole account, so they include usage from claude.ai and other devices, not only this terminal. If you are unsure what each window means, see the difference between the session and weekly limits.
  3. Activity stats. A summary of your Claude Code activity.
  4. A usage breakdown. Recent usage attributed to skills, subagents, plugins and individual MCP servers, each as a percentage, plus recommendation rows and, from version 2.1.242, rows for the heaviest /loop and other scheduled tasks.

Anthropic does not publish how many tokens or messages sit behind a bar reaching 100%, so the bars are the only measure you get. Exact on-screen labels can change between versions, so treat the wording in this post as a guide rather than a promise.

The breakdown and recommendation rows

Alongside the attribution, /usage can show recommendation rows. Each row starts with the share of your recent usage it applies to, at least 10%. The docs give the example 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request, which tells you a long instruction file is sent with every request.

Two details matter when you read them. The share says how much of your usage the row applies to, not how much the change would save. And one request can count toward several rows, so the shares can add up to more than 100%.

These rows are worth reading before you change habits. They point at what is actually expensive in your setup instead of what you guess is expensive.

An important detail from the same page: the breakdown is approximate and computed from local session history on this machine. Usage from other devices or from claude.ai is not included in it, even though it is included in the plan bars.

Keys inside /usage

Key What it does
d Shows the last 24 hours
w Shows the last 7 days
f Acts on the recommendations it can, when the footer shows a hint such as f to fix 2 of 3 (version 2.1.305 or later)
r Retries loading plan limits if the request failed

Pressing f is not a blind rewrite. Per the docs, Claude Code runs any /effort command a row names, then gives Claude one prompt covering the other rows it can act on, and that prompt asks Claude to show you each change before making it. Rows that end in run and a command, such as run /compact, are left for you to run yourself.

The dollar figure is not your bill

The Session block at the top of /usage includes a cost in dollars. Anthropic says this block "is intended for API users". Pro, Max and Ultra subscribers have usage included in the plan, and the docs state that the session cost figure "isn't relevant for billing purposes".

So if you see a number like a few dollars after a long session and worry about a charge, you can stop worrying. Claude Code computes the figure locally from token counts at list price, so it is an estimate of what the same tokens would cost on the API. For subscribers the thing to watch is the percentage on the plan bars. The Session totals start again at $0 when /clear starts a new session.

The exception is usage credits. While they are on, /usage adds a usage-credits row. On Pro, Max and Ultra it shows this month's spend against your monthly spend limit, or just "Unlimited" when you have not set a limit. On Team and Enterprise it shows your own spend against any limit that applies to you. Usage credits are real money, billed separately from the subscription.

When the bars do not load

If the request for plan limits fails, usually because the usage endpoint is rate limited, /usage shows the last bars it loaded on this machine within the past 60 minutes with a "Showing last-known usage" note. Press r to retry.

You may also see a message such as rate limited until 3:14am. The docs are explicit about it: this means Claude Code cannot fetch your plan limits again until then, not that your work with Claude is limited. It is about the usage lookup, not about your quota.

What /usage is not for

  • Confirming the account and credential. The documented place to see which account is signed in, and whether a login or an API key is in use, is /status. See /status vs /usage.
  • Other accounts. /usage reports the account that session is signed in to. If you have a personal login and a work login in separate folders, you have to open each one in turn.
  • Your API bill. If an ANTHROPIC_API_KEY is routing your requests, you are on API billing and the plan bars do not apply. The Session block's dollar figure is then the relevant number, but it is still a local estimate; the Claude Console is where the actual charges are.

Checking without opening Claude Code

/usage needs a running Claude Code session. On the web, Claude Desktop and mobile, Settings > Usage shows "Current session", the weekly limits and usage credits, per the Help Center. That reflects the same plan limits.

For several Claude Code accounts on one Mac, Headroom is a free menu bar app that shows the session and weekly percentages for each signed-in account without starting a session. It is an independent app from Everyday Mac Tools, not made or endorsed by Anthropic. It reads the sign-in Claude Code already saved on your Mac and never sends a prompt, so checking does not use your limits. You can download it here.

Quick answers

Why do the breakdown percentages not match my bar? They measure different things. The breakdown shows shares of your recent usage on this machine, and recommendation rows can overlap. The bars show how much of the account's limit is used, across every device and claude.ai.

Is the Help Center wrong that /status shows my allocation? The Help Center still says to monitor your allocation with /status, while the Claude Code docs put plan limits under /usage. Use /usage for limits.