How to track your Claude Code usage in real time

First, know what you’re tracking

On Claude subscription plans (Pro and Max), Claude Code usage is metered against a rolling session window of roughly five hours, plus weekly caps on top. Heavy API users have a different concern — dollars rather than windows — but the tracking tools below cover both. The common failure mode is the same: you find out about a limit at the exact moment it stops you.

Method 1: The built-in /usage command

The zero-install answer. Inside any Claude Code session, run:

/usage

You get your position against your plan’s session and weekly limits. Its sibling /cost shows token spend for the current session, which is the number that matters if you’re API-billed instead of on a subscription.

The catch: it’s a snapshot on demand. You have to remember to run it, it occupies your terminal, and it can’t warn you at 80%.

Method 2: ccusage — the CLI analyst

Claude Code writes usage metadata (tokens, timestamps, models) to local JSONL files on your machine. The open-source ccusage CLI reads those files — no API calls, no account — and turns them into reports:

npx ccusage@latest          # daily usage and estimated cost
npx ccusage session         # per-conversation breakdown
npx ccusage blocks --live   # live-updating window dashboard

It’s the best tool for questions like “what did this month actually look like?” and “which project eats my tokens?”. Costs are estimates computed from token counts and model pricing, but they’re consistently useful for trends.

The catch: it lives in a terminal. Great for analysis, not for ambient awareness.

Method 3: A menu bar app — ambient, real-time

If the goal is never being surprised, the answer is something that’s always visible. That’s why I built Claude Pulse: a free, lightweight macOS menu bar app that keeps your Claude usage in the corner of your eye — tokens, conversations and usage limits, updating in real time, one glance up from whatever you’re doing.

Like ccusage, it works by reading the usage data already on your Mac. It makes no network calls and never sees your code or conversations — there’s no login and nothing to configure. Download it, and a quiet number sits in your menu bar.

Claude Pulse isn’t alone in the category — several open-source menu bar trackers exist. Whichever you pick, apply the same two tests: does it run entirely locally, and does it avoid asking for credentials it shouldn’t need?

Using OpenCode instead of (or alongside) Claude Code? OpenCode Pulse is the same idea for OpenCode.

Method 4: The Anthropic Console (API users)

If you use Claude Code with an API key rather than a subscription, the Anthropic Console is the source of truth for actual billing — real dollars per model and per key, plus configurable spend limits and workspace budgets. It’s authoritative but retrospective; pair it with one of the local tools above for the in-the-moment view.

Which one should you use?

Tool	Real-time	Install	Best for
/usage command	On demand	None — built in	A quick check mid-session
ccusage	Live mode available	npx ccusage	History, trends, per-project analysis
Claude Pulse	Yes — always visible	Free macOS download	Ambient awareness; never hitting the wall
Anthropic Console	No	None — web	Actual API billing and spend limits

In practice they stack: a menu bar app for the ambient view, /usage when you want the official number, and ccusage when you’re curious where last week went.

Frequently asked questions

How do I check my Claude Code usage limits?

Run /usage inside Claude Code. It shows where you sit against your plan's rolling session window and weekly limits. For historical analysis, run npx ccusage in a terminal; for always-visible tracking, use a menu bar app like Claude Pulse.

What's the difference between /usage and /cost?

/usage reports your position against subscription plan limits (session and weekly windows). /cost reports token spend for the current session, which mainly matters for API-billed usage rather than subscriptions.

Do usage trackers see my code or conversations?

Local tools shouldn't need to. ccusage and Claude Pulse read the usage metadata Claude Code already writes to your machine — token counts, timestamps, models. Nothing is sent anywhere. Be warier of trackers that ask you to log in or paste API keys.

Does tracking usage cost anything?

No. Reading local usage logs consumes no tokens and makes no API calls. The /usage command is free to run, ccusage is open source, and Claude Pulse is a free download.

What happens when I hit a Claude Code limit?

Claude Code tells you and pauses until the rolling window resets — the message includes the reset time. Weekly caps behave the same on a longer horizon. Real-time tracking exists precisely so this never surprises you mid-task.

---