Claude Code usage, explained

Usage is one word for at least four different numbers: how many tokens a session moved, how many of those were cache, what those tokens would have cost at list price, and how many times you actually pressed Enter. Two honest trackers can report totals an order of magnitude apart for the same week simply because they headline different columns. This page takes the numbers apart — what each one counts, which are measured and which are estimated, and where to look for a per-day, per-week or per-agent view. For the shortest route to a figure on your own machine, see the step-by-step walkthrough.

The four counters behind every total

Each assistant response Claude Code appends to its transcript carries a usage record, and ccclub's collector lifts four fields out of it: input tokens, output tokens, cache-creation tokens, and cache-read tokens — plus the subset of cache writes made with a one-hour lifetime, where the record reports one. Those columns are stored exactly as found and then summed; every token figure ccclub displays anywhere is a sum of them and nothing else. A fifth counter, reasoning tokens, exists for agents that report thinking separately. Claude Code's records do not, so for Claude Code that column is always zero.

The buckets behave nothing alike. Output tokens are the model writing. Input tokens are the genuinely new part of a request. The two cache counters are your conversation being re-sent: written once, then read back on every turn that follows. Past the first few exchanges of a session, they are most of the traffic.

Why cache tokens dominate Claude Code token usage

A coding agent re-sends its whole working context on each turn — instructions, file contents, tool results, the transcript so far. Prompt caching means that bulk is charged at a fraction of the input rate rather than the full one, but it is still counted, and it is counted again every turn. A total-tokens headline therefore grows with the length of the session squared, while the part you would recognise as your own typing barely moves at all.

That is why ccclub keeps two token views instead of one. The default total includes cache; ccclub --no-cache in the terminal, and the Include cache switch on a group's dashboard, drop to input plus output. Neither is the honest one and the other a fiction — those cached tokens really were sent. They answer different questions. The cache-inclusive total tracks what a bill would reflect; the non-cache total tracks how much distinct material actually passed through the model, which is the fairer comparison between someone running one long session and someone running twenty short ones.

Tokens, cost and turns measure different things

A ccclub leaderboard row carries all three on purpose. Tokens measure volume. Cost converts that volume to dollars at public list prices, which makes it an estimate rather than a statement of what anyone was charged — how that figure is built is its own subject. Turns count the messages a person typed: ccclub counts human turns inside each 30-minute block, not the model's replies and not its tool calls, which is why a row can show millions of tokens against a dozen turns. The column that divides the first by the third — $/Turn in the CLI, Avg Turn on the web dashboard — is the closest thing on the board to a measure of how expensive one unit of intent has become.

A usage dashboard for today, 7 days, 30 days or all time

Everything in ccclub is scoped to a period. Bare ccclub prints today; ccclub -d 1 is yesterday, -d 7 the last seven days, -d 30 the last thirty, and -d all everything that has ever been synced. The same five periods appear as a selector on each group's web page at ccclub.dev/g/CODE, next to an activity chart. Boundaries follow your machine's timezone, which the CLI sends with the request, so "today" means your today rather than UTC's.

For a longer horizon there is ccclub activity: a GitHub-style heatmap of the last 53 weeks, computed entirely from local logs. It makes no network call, so it works before you have joined any group and keeps working offline.

A per-agent breakdown when you run more than one

Most people tracking this now have more than one agent installed. ccclub reads Claude Code, Codex, OpenCode, Amp, Grok and Pi from their local logs by default, and Cursor through an explicit opt-in, because Cursor writes no local usage files at all. Each usage block is tagged with the agent that produced it, so the board can show an Agents column with each member's mix and a split of who is currently active in which tool. That tagging is also what makes ccclub --no-cache behave correctly across agents: the non-cache figure follows each source's own output and reasoning conventions instead of assuming everyone reports tokens the way Claude Code does.

What Claude Code reports about itself

/usage inside Claude Code is the first-party view, and Anthropic's command reference lists /cost and /stats as aliases that open the very same screen, described there as session cost, plan usage limits and activity stats. (code.claude.com/docs/en/commands, read 2026-09-19.) Paid plans get one thing more: recent consumption attributed to skills, subagents, plugins and individual MCP servers. That answers a question none of the columns discussed here do — not how much, but which part of your setup is responsible for it.

Two qualifications, both from the cost documentation rather than the command reference. It calls its figures approximate rather than exact. And the breakdown is derived locally, from the transcripts on one computer, so a second machine or anything done in the Claude app is simply outside its field of view. (code.claude.com/docs/en/costs, read 2026-09-19.)

Where the raw records live

Claude Code keeps one JSONL transcript per session under ~/.claude/projects/, one directory per project, as its own file-layout reference sets out. Those files hold the entire conversation — that is the point of them — which is why local reporting tools parse the usage fields and leave the message bodies untouched. ccclub aggregates its four counters into 30-minute blocks before anything is uploaded, together with model names, the cost estimate, and call and turn counts. ccclub show-data prints that payload on your screen before it is sent anywhere, and is the honest way to check the claim rather than take it.

Comparing your usage with other people's

A single-machine figure tells you how much, never whether that is a lot. The official answer for organisations is the admin analytics that come with Team and Enterprise seats. The informal answer is a shared board: everyone runs npx ccclub init or join, and the group sees one ranking of tokens, estimated cost and agent mix, updated without anyone exporting anything. It is built for curiosity among people who know each other, not for reporting — token counts measure activity and spend, and nothing about whether the work was any good.

Last updated 2026-09-29. Corrections welcome on GitHub.