How to Check Claude Code Usage and Limits From the Terminal

The fastest way to check Claude Code usage is to type /usage inside a running session. It runs immediately, even while Claude is still responding, and on a Pro, Max, Team, or Enterprise plan it also breaks down what has been consuming your recent allowance, with a tip next to anything that accounts for 10% or more of it.

If you'd rather see the numbers all the time, add a status line. Claude Code pipes a JSON object to your status line script that carries the context window percentage and, for Pro and Max subscribers, how much of the rolling five-hour and seven-day windows you've used plus when each resets. The sections below cover both, then /context, headless runs with claude -p, where transcripts live on disk, and the admin views for Teams and Enterprise.

Check usage inside a session with the usage command#

Commands are only recognized at the start of a message, so type /usage on its own line and press Enter. Most commands you send while Claude is responding get queued until the turn finishes. A few run right away without interrupting the response, and /usage is one of them, along with /status and /tasks. That matters when a long agentic turn is running and you want to know whether it's safe to let it keep going.

What the output contains depends on your plan. On Pro, Max, Team, and Enterprise, the /usage breakdown flags behaviors that account for 10% or more of your recent usage, such as long context or cache misses, and pairs each one with a tip to reduce it. The attribution breakdown also shows the share coming from subagents, which is often the surprise when a session feels heavier than the conversation looks.

On Claude for Teams and Enterprise, each member's Claude Code usage draws from a per-seat allowance that resets on a rolling five-hour window and a weekly window. That allowance is shared with Claude chat and Cowork, and its size depends on the seat tier, Standard or Premium. So the number you see in /usage reflects everything you did across those surfaces, not only the terminal.

If you're not sure which commands your build exposes, type / and start filtering. Claude Code leaves commands that aren't available to you out of the menu, and shows a no-match message when nothing fits.

See what is filling the context window#

Usage and context are related but different questions. /usage tells you how much of your plan allowance you've drawn. /context tells you what's occupying the conversation window right now, which is what drives the per-request cost.

When the window is crowded, you have two cheap exits and one expensive one:

• Clear it with /clear to start fresh on a new task while keeping project memory. This costs nothing.
• Ask on the side with /btw for a question that shouldn't be added to the conversation history.
• Compact it with /compact to summarize and free space. Compaction reads the conversation it summarizes, so compacting a large context is itself a large request. Use it when you need continuity, not as a free reset.

If /context keeps showing the same culprits, the longer write-up on why Claude Code uses so many tokens goes through the fixes one by one.

Put context percentage and limits in the status line#

A status line is a script that Claude Code runs and prints under the prompt. It reads a JSON object from stdin. The fields that matter for usage are:

The rate_limits object is only present for claude.ai Pro and Max subscribers, or behind a Claude apps gateway with spend limits, and only after the first API response. Your script has to tolerate it being absent. Here's a small Bash version that prints context usage always and the two windows when they exist:

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

OUT="[$MODEL] ctx ${PCT}%"
[ -n "$FIVE_H" ] && OUT="$OUT | 5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && OUT="$OUT | 7d: $(printf '%.0f' "$WEEK")%"
echo "$OUT"

The // 0 and // empty fallbacks in jq are what keep the script from printing null on an API key, where the rate limit fields never show up. The status line page has Python and Node.js equivalents and shows how to wire the script into your settings. If you've never edited that file, start with where Claude Code settings.json lives.

To see the logic without a live session, this snippet feeds a sample payload through the same steps and also turns resets_at into a readable time:

import json
import datetime

# Shape of the object Claude Code pipes into a status line script.
payload = json.loads("""
{
  "model": {"display_name": "Opus 5.5"},
  "context_window": {"used_percentage": 42.7},
  "rate_limits": {
    "five_hour": {"used_percentage": 63.2, "resets_at": 1792800000},
    "seven_day": {"used_percentage": 18.9, "resets_at": 1793145600}
  }
}
""")

model = payload["model"]["display_name"]
pct = int(payload.get("context_window", {}).get("used_percentage", 0) or 0)
filled = pct * 10 // 100
bar = "▓" * filled + "░" * (10 - filled)

parts = [f"[{model}] {bar} {pct}%"]
rate = payload.get("rate_limits", {})
for key, label in (("five_hour", "5h"), ("seven_day", "7d")):
    window = rate.get(key) or {}
    used = window.get("used_percentage")
    if used is not None:
        resets = datetime.datetime.fromtimestamp(
            window["resets_at"], datetime.timezone.utc
        )
        parts.append(f"{label}: {used:.0f}% (resets {resets:%b %d %H:%M} UTC)")

print(" | ".join(parts))

Behind a Claude apps gateway, swap the two windows for rate_limits.spend_limit. The docs' sample prints spend: $314.12 / $500 when the gateway reports dollars and falls back to the percentage when it doesn't.

Check usage for headless runs with claude -p#

Scripted runs change the question from "how much have I used today" to "how much did this run cost." Two things from the session docs are relevant here. Sessions created with claude -p or the Agent SDK don't appear in the session picker and are skipped by claude --continue, but you can still resume one with claude --resume <session-id>, and claude -p --continue does include them. So headless usage is tracked per session on disk like any other; it's just hidden from the interactive picker.

For per-run token counts, the JSON output format is the right tool, and the field-by-field walkthrough is in tracking token usage and cost per run with JSON output. Running on a server with cron or CI is covered in how to run Claude Code headless.

Turning token counts into dollars is arithmetic against the published rates. As of October 18, 2026, the Claude pricing page and the models overview list Claude Fable 5.1 at $10 / input MTok and $50 / output MTok, with cache reads at $0.25 USD per million tokens. This calculator shows how much the cache changes the picture for a typical long-context run:

// Cost of one run on Claude Fable 5.1 from token counts.
// Per-million-token rates from the Claude pricing page, October 2026.
const rates = { input: 10, output: 50, cacheRead: 0.25 };

const inputTokens = 1200;      // fresh, uncached input
const cacheReadTokens = 85000; // history served from the prompt cache
const outputTokens = 2400;

const withCache =
  (inputTokens * rates.input +
    cacheReadTokens * rates.cacheRead +
    outputTokens * rates.output) / 1e6;

const noCache =
  ((inputTokens + cacheReadTokens) * rates.input +
    outputTokens * rates.output) / 1e6;

console.log(`with cache hits:    $${withCache.toFixed(4)}`);
console.log(`same tokens, no cache: $${noCache.toFixed(4)}`);
console.log(`cache saved: ${((1 - withCache / noCache) * 100).toFixed(1)}%`);

Where Claude Code keeps session transcripts#

Every interactive and headless session is written to disk, which is useful when you want to audit what a session actually did rather than trust a summary. Claude Code stores sessions per project directory under its config directory, which defaults to ~/.claude. Transcripts go in a projects/<project>/ folder, and the project name is derived from the whole working directory path. Auto memory for that project sits in a memory/ subfolder next to the transcripts.

You can choose the project name yourself with CLAUDE_CODE_PROJECT_DIR_NAME, but only together with CLAUDE_CONFIG_DIR. The sessions page gives this example, which keeps one tenant's data under its own directory and names the project work:

CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude

That launch writes transcripts to /srv/tenant-a/projects/work/ and auto memory to /srv/tenant-a/projects/work/memory/, whatever directory you ran it from. Three constraints apply: set CLAUDE_CONFIG_DIR too or the name is ignored, use 1 to 64 letters, digits, hyphens, or underscores, and set it in the shell environment that starts claude, because an env block in a settings file can't set it. This requires Claude Code v2.1.234 or later.

For browsing rather than file paths, open the picker with /resume. It shows the current worktree's sessions by default; Ctrl+W widens to all worktrees of the repository and Ctrl+A to every project on the machine. claude --resume <session-id> works from any directory and searches the current project first, then every other project.

Check usage cost and stats for a team#

Individual /usage output won't tell an admin what the whole organization is doing. On Claude for Teams and Enterprise, the controls live in the claude.ai admin console, not the Claude Console, and the costs page points to three views:

• Spend report in org analytics shows estimated spend per user and per model, with CSV export, updated daily. It covers usage-credit spend and appears once usage credits are turned on. Usage inside the seat allowance isn't metered in dollars.
• Analytics dashboard at claude.ai/analytics/claude-code shows daily active users, sessions, and contribution metrics, with CSV export of contribution data.
• Enterprise Analytics API returns per-user usage and cost reports across Claude surfaces, including Claude Code, on the Enterprise plan. A Primary Owner creates a key with the read:analytics scope. On the Teams plan, export the spend report CSV instead, which lists token usage and estimated spend per user and per model.

To cap spend, the seat allowance is the default ceiling. Turning on usage credits lets members continue past it, with spend limits at the organization, group, or individual level.

Why usage climbs faster than you expect#

The common complaint is a session that has been open for hours and used far more than the activity suggests. The reasons the docs list:

• Long context. Claude Code sends the full conversation with every request, and each batch of tool results is another request carrying that history. Prompt caching reads it at the cached rate, but a one-line question in an all-day session still draws usage for the whole conversation.
• Cache misses. The first message after a break longer than the cache lifetime reprocesses the full context. The lifetime is an hour on a subscription, drops to five minutes once you're drawing on usage credits, and is five minutes by default on an API key or cloud provider.
• Idle activity. Scheduled tasks fire on their interval even while the session sits idle. Cross-session messages arrive as new turns; set crossSessionInbound to hold to stop that. Goal check-ins on background work start new turns too, capped at three per goal between your prompts from v2.1.246, and CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0 turns them off.
• Subagents, workflows, and teammates. Each one sends its own requests on top of the main conversation, and each active teammate keeps consuming tokens until it exits.
• Compaction. As above, /compact reads everything it summarizes.

If you've already hit the wall, what to do when the Claude Code usage limit is reached explains when the windows come back.

Common mistakes and gotchas#

• Expecting rate limit fields on an API key. The rate_limits object only exists for Pro and Max subscribers or behind a gateway with spend limits. Scripts that assume it will print null or crash. Always use a fallback.
• Reading the status line before the first response. Even on a subscription, rate_limits isn't populated until after the first API response. An empty limits section at session start is normal.
• Treating a percentage as an integer. used_percentage can be fractional. The official scripts cut at the decimal point or round with printf '%.0f'; do the same before doing bar math.
• Reaching for compaction to save usage. /compact is a large request on a large context. When you don't need continuity, /clear is free.
• Setting the project name without the config directory. Claude Code ignores CLAUDE_CODE_PROJECT_DIR_NAME when CLAUDE_CONFIG_DIR is unset, and under the default ~/.claude a fixed name would merge every project's transcripts into one directory.
• Looking for a headless session in the picker. claude -p sessions are deliberately left out of /resume and claude --continue. Keep the session ID and use claude --resume <session-id>.
• Assuming the spend report is live. It updates daily, covers usage-credit spend only, and shows nothing for usage inside the seat allowance.

Quick reference#

I'd start with /usage once a day and a status line showing the five-hour window. That pair catches the two situations that actually cost people time: a window about to run out mid-task, and a bloated context that makes every small turn expensive.

Quick answers