← Blog

Claude Code Token Usage: Every Way to Check It

9 min de lecture

Key takeaways

  • Run /cost in Claude Code for an instant per-session token and cost total, with dollar figures on API billing and token counts on subscription plans.
  • A custom statusline script shows context usage and cost live at the bottom of your terminal, but only for the current session.
  • Finished sessions are logged as JSONL transcripts under ~/.claude/projects/, which you can parse with jq for token totals.
  • The Anthropic Console aggregates per-day, per-model spend across all sessions and API keys, and is where you set hard spend caps.
  • Per-terminal checks break down at ten or more parallel sessions; fleet monitoring needs orchestration tooling that tracks state and spend per agent.

You can check Claude Code token usage in under a minute: run /cost mid-session, add a statusline that shows tokens live, review past sessions with /resume or the transcript files, and check the Anthropic Console for API spend. This guide covers each method, when to use it, and how to monitor a fleet of parallel sessions.

How do you check Claude Code token usage in under a minute?

Open Claude Code and type /cost. It prints the session's token usage and cost immediately, no dashboard required. If you want the number always visible instead of on demand, configure the statusline so context and spend sit at the bottom of your terminal while agents run. Anthropic documents the setup in its statusline configuration guide.

That covers one session. The gap appears when you run parallel agents across repos: /cost is per-session, so a fleet of five means five separate checks. That is the problem our own orchestration stories come from, and the rest of this guide walks through each method so you can pick per situation.

How do you show token usage in the Claude Code statusline?

The statusline is the only place where token usage is visible permanently, without typing a command. You enable it by pointing Claude Code at a shell script, and the script decides what appears at the bottom of every session.

Setting up a custom statusline script

Run /statusline inside Claude Code and describe what you want, or write the script yourself. Claude Code passes session data as JSON on stdin, including model name, context window usage, and cost figures for the session. Your script reads that JSON and prints a single line. A minimal setup in your .claude/settings.json looks like:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

The script itself can be a short jq pipeline: pull the model, the context tokens used, and the session cost, then echo them. Keep it fast. The statusline runs your script on every update, so a script that calls the API or sleeps will lag your prompt.

What the statusline shows and how often it updates

The statusline is a snapshot, not an audit log. It shows the current session's context consumption and cost, refreshing as you interact, which is enough to answer "am I about to run out of context?" at a glance. It cannot show spend across parallel sessions, other repos, or yesterday's runs, because each statusline belongs to one session only.

That distinction matters once you run an agent fleet instead of one agent. The Ticksly team described losing track across terminal tabs, with one agent waiting and another burning hours on the wrong thing (https://dev.to/dev1alone/how-we-run-thirty-claude-code-and-codex-agents-on-our-own-servers-and-the-tool-is-now-open-source-5c4e). A statusline per tab does not fix that; you need state tracking above the session layer, which is the problem Aerunit handles for parallel coding agents.

How do you check Claude Code token usage mid-session?

Type /cost in the Claude Code prompt and you get the running total for the current session: input and output tokens, cache reads, and the API cost so far. It takes seconds and works while the agent is mid-run, which is what you want when one of your parallel sessions has been quiet for twenty minutes and you suspect it is chewing through your token budget.

Anthropic documents the full set of slash commands, including /cost and /clear, in the Claude Code CLI reference.

What /cost reports and what it omits

/cost is per-session only. It shows no history across sessions, nothing about other agents running in other terminals, and no breakdown by task or repository. If an agent has been "fixing the wrong thing" for three hours, /cost tells you how much that mistake cost, but only if you ask that specific session.

Subscription plans vs API billing: what each shows

On API billing, /cost reports a dollar figure you can map straight to your invoice. On subscription plans it shows token counts without a dollar amount, since you are not paying per token. For fleet-level spend across sessions, you need the console or external monitoring, and per-agent budgeting strategies are covered in our guide to coding agent costs.

How do you see token usage after a session ends?

Session transcripts and local history

Claude Code writes every session to disk under ~/.claude/projects/, as JSONL transcript files named by session ID. Each line records the message plus a usage block with input tokens, output tokens, and cache reads and writes. To total a finished session, run something like cat ~/.claude/projects/<project>/*.jsonl | jq 'select(.message.usage) | .message.usage' and sum the fields. This works after the terminal closes, but only per machine, and jq wrangling gets old once you run a fleet of parallel agents across repos.

The Anthropic API console for historical spend

The Anthropic Console's Usage page shows per-day and per-model token consumption and cost for your API key, going back weeks. It aggregates across all sessions, so you can see the daily burn but not which agent run caused it. For per-merge-request accounting, teams pair the console with orchestration that tracks state per agent; we cover how tools like Vibe Kanban and Aerunit fit in our cloud coding agents compared overview.

What is the difference between /cost, the statusline, and the console dashboard?

Each method answers a different question. /cost gives a one-off total for the current session, the statusline gives a live per-session readout while you work, and the Anthropic console gives org-wide spend across all sessions and API keys. You will usually run the statusline by default and open the console when a bill looks wrong.

MethodScopeWhen to use
/costCurrent session onlyQuick check before ending a run
StatuslineCurrent session, liveWatching token burn during parallel agents
Console dashboardWhole org, all keysReconciling spend, setting spend limits

The console is also where you set hard spend limits so a runaway agent cannot burn the budget silently; see the Anthropic API documentation on usage and limits. For per-agent visibility across a fleet, session totals alone are not enough, which is why we built instant feedback for coding agents around per-run state tracking.

How do you monitor Claude Code token usage across a team?

Per-terminal checks work up to a handful of sessions. Past ten, the statusline in one tab tells you nothing about the other nine, and the agent that has been quietly rewriting the wrong module for three hours looks identical to the one waiting on your approval.

Why per-terminal visibility breaks at ten or more sessions

Each terminal shows only its own session's state. There is no cross-session view of which agent is idle, which is burning tokens on retries, and which has drifted from its acceptance criteria. Teams running large fleets describe exactly this: with thirty sessions you lose track of which is which, per the dev.to writeup quoted earlier. The fix is a single pane that aggregates state and spend across all running agents.

Central monitoring options: API console, spend caps, orchestration tooling

Three layers, roughly in order of effort:

  1. Anthropic API console. Aggregate spend and per-key usage, but updated after the fact, not live per agent.
  2. Spend caps and workspace limits. Set a hard ceiling so a runaway swarm cannot drain the token budget overnight.
  3. Orchestration tooling. Tools like Vibe Kanban and our own Aerunit track each agent's task, state, and consumption in one dashboard, so you see the three-hour drift while it is happening, not on the invoice.

Why does Claude Code use more tokens than expected?

Four drivers account for most surprise burn: context re-reading, retries, duplicate agents, and conversations that never get compacted.

Context window accumulation and re-reading files

Every turn re-sends the conversation history, so a long session pays for its whole context on each request. Re-reading large files after edits multiplies this. Claude Code's auto-compaction summarises the conversation when it nears the limit, which cuts the per-turn payload but adds a one-off summarisation cost, per Anthropic's Claude Code documentation.

Agents overwriting each other and burning budget arguing

Run four agents in one repo without task separation and they duplicate work, overwrite each other's edits, and spend turns re-fixing code another agent already touched. Each wasted retry is a full context re-read plus new output, so a single conflict can cost several merge requests' worth of tokens. The pattern is easy to miss because every individual step looks productive: an agent reads a file, edits it, runs the tests, and reports success, while a second agent has already replaced the same function with a different signature. By the time the build breaks, both agents have burned their context windows on mutually exclusive versions of the code, and you pay a third time for the session that reconciles them. Git worktrees and explicit acceptance criteria per agent keep the fleet from arguing over the same files.

How do you reduce Claude Code token usage without hurting output quality?

The biggest lever is not a setting. It is what you ask the agent to do. A vague task makes the agent explore, retry, and re-read files you could have named up front. A scoped task with explicit file paths burns a fraction of the tokens and produces a smaller diff to review.

Tighter task stories and acceptance criteria

Write the task like a merge request description: what to change, which files are in scope, which are off-limits, and what "done" means. Three bullet-point acceptance criteria beat a paragraph of intent. The agent stops when the criteria pass instead of wandering the codebase looking for more to fix. This also cuts the retry loop where an agent spends three hours on the wrong thing because nobody told it what right looks like.

Context hygiene: clearing, compacting, and scoping repos

Run /clear between unrelated tasks so each session starts with a small context instead of inheriting the previous one. When a long session gets slow and expensive, use /compact to summarize rather than re-reading history. Across a fleet, keep one agent per git worktree and assign repos explicitly, so two agents never duplicate the same fix and burn your token budget arguing about it. If you run many parallel sessions, Aerunit tracks state per agent so you can spot the one stuck re-reading files and restart it cheaply.

FAQ

Does /cost show token usage on a Claude subscription plan or only on API billing?

Both, but the output differs. On API billing, /cost reports a dollar figure that maps directly to your invoice. On subscription plans it shows token counts without a dollar amount, because you are not paying per token. Either way it stays per-session: no history across sessions and no view of other agents running elsewhere.

Can I set a hard token budget or spend cap so an agent stops automatically?

Claude Code itself has no built-in per-session token budget that halts an agent. The practical control point is the Anthropic Console, where you set hard spend limits on your API keys so a runaway agent cannot drain the budget silently. The cap operates at the key or org level, not per individual agent run, so fleet-level budgeting needs orchestration tooling.

How much does a typical Claude Code session cost at API prices?

There is no single number, because cost scales with context length, model choice, and how many turns the agent takes. A short scoped task with a few file reads costs a small fraction of a long session that re-sends a full context window every turn. Check your own sessions with /cost rather than trusting averages from elsewhere.

Is there a way to export Claude Code token usage to a spreadsheet or dashboard?

Yes, indirectly. Claude Code writes JSONL transcripts to ~/.claude/projects/, each line containing a usage block with input tokens, output tokens, and cache reads. You can parse those files with jq and load the output into a spreadsheet or dashboard. For aggregate API spend, the Anthropic Console provides per-day and per-model consumption data.

Does the statusline token count include cached tokens?

It depends on your script. Claude Code passes session data as JSON on stdin, including context window usage and cost figures, and your script decides what to display. Cached reads reduce billed cost but still occupy the context window, so decide explicitly whether your statusline shows billable tokens, raw context consumption, or both.

Aerunit

Occupez les agents. Gardez la réflexion.

Les inscriptions sont ouvertes — créez un compte et commencez avec des crédits à l'usage. Aucun abonnement, et les équipes partagent une réserve de crédits sans surcoût.

Créer un compte