Claude Code Status Line Token Usage: Label Every Counter

A reliable Claude Code status line should not collapse every usage signal into one “tokens” number. Show current context, cumulative session cost, subscription quota, and data freshness as separate scopes. For cumulative session token totals, point to /usage ; modern status line token fields do not provide that total. That distinction matters because the official field contract changed. Since Claude Code v2.1.132, context window.total input tokens and context window.total output tokens describe the current context from the most recent API response. Before that version, the same fields were cumulative session totals. A status line script written against the old meaning can keep running after an upgrade while silently giving the number a false label. The safe default is a line like this: It is less flashy than a single progress bar. It is also much harder to misread. Give each counter one scope Claude Code pipes JSON to the configured statusLine command. According to the official status line documentation, the command runs locally and does not consume API tokens. It runs when a session starts, after a new assistant message, after /compact , when several UI modes change, and on an optional refresh timer. The payload contains several measurements that answer different questions: Question Documented field or command Scope Honest label How full is the active context? context window.used percentage Current context from the latest API response ctx 42% What are the input and output counts in that context? context window.total input tokens , total output tokens Current context on v2.1.132+ context , never session total What has this session cost? cost.total cost usd Cumulative local estimate; resets on /clear in current versions $0.12 est What are the cumulative session token totals? /usage Current Claude Code session tokens use /usage How much subscription allowance is consumed? rate limits.five hour , rate limits.seven day Rolling plan windows for eligible subscribers quota 5h … · 7d … How old is the quota observation? No timestamp in the documented status line object Unknown age unknown There are two traps in that table. First, used percentage is an input context measure. Claude Code calculates it from fresh input, cache creation, and cache read tokens. It does not include output tokens. That makes it useful for deciding whether the active conversation is approaching compaction, but it is not a percentage of session spend or plan quota. Second, rate limits. .resets at is the time when a quota window resets. It is not the time when Claude Code fetched the percentage. The documented status line object has no fetched at field. A reset time cannot prove freshness. The separate /usage screen has a stronger stale data contract. The official cost guide says that if the plan limit request is rate limited, /usage can show a cached snapshot from the past 60 minutes and explicitly mark it as last known usage with its age. The status line payload does not document an equivalent age field. If age affects a decision, open /usage instead of decorating the status line percentage as live. Configure a truth labeled status line Save the following as ~/.claude/usage statusline.mjs : Make the script executable if your platform requires it, then add a command backed status line to ~/.claude/settings.json : The refresh interval is optional. Event driven updates are enough for context changes. A timer is useful when the main session is idle while background work continues, but it does not make quota data fresher than its source. Re running an undated value every 30 seconds still leaves its age unknown. This script also avoids a tempting but unsafe workaround: adding context window.current usage on every status line invocation to reconstruct a cumulative total. The command can run for compaction, permission mode changes, Vim changes, and timers, not only for new API calls. The documented payload does not supply a stable API request identifier beside current usage . Repeated addition can therefore count the same response more than once. Use /usage for cumulative session tokens. Its session block reports usage by model, including input, output, cache read, and cache write totals. The dollar figure remains a local estimate based on standard list rates, so it can differ from a discounted contract, promotional pricing, a cloud provider bill, or a subscription allowance. Test the version and null paths A status line is operational code. Test the inconvenient payloads, not only a populated example copied from documentation. The inspectable artifact for this article replays three fixtures through the renderer: 1. A modern active session has 42% context usage, an estimated session cost, and both quota windows. 2. A modern post compaction session has current usage: null , null percentages, and no quota object. 3. A v2.1.131 session has token fields whose documented meaning predates the v2.1.132 change. The observed output was: All three assertions passed. More importantly, none of the failure paths became zero. That behavior follows the official nullability boundaries. context window.current usage can be null before the first API response and immediately after /compact until another response arrives. Context percentages can also be null early in a session. rate limits appears only for eligible Claude.ai subscription sessions after the first API response, and either window can be absent independently. Rendering those cases as 0% makes three claims that the payload does not support: the context is empty, no quota has been consumed, and the measurement is current. unknown and unavailable are more useful because they tell the operator to wait for the next response or consult /usage . There is one more version boundary worth retaining in the test. Before v2.1.132, the total input and output fields were cumulative session totals. On current versions, they are current context counts. If the version field is missing or old, do not guess which meaning applies. Either branch deliberately for the deployed version or show the semantic state as unknown. Know what the line cannot prove The status line answers a narrow interactive question: what does this local Claude Code session currently expose? It does not establish: the authoritative invoice for API or cloud provider usage; total activity from other machines or claude.ai ; a verified deliverable or useful progress; cost per completed engineering outcome; the age of subscription quota data in the documented status line payload. Those boundaries affect action. High context usage can justify inspecting whether the conversation still serves one task; it does not automatically mean /compact is safe. A high five hour percentage can justify checking /usage ; it does not prove which project or subagent caused it. A rising estimated cost can justify ending an unproductive loop; it does not prove that a costly run failed. Use the line as a router: ctx known routes to a context decision; session … est routes billing questions to the Console and cumulative token questions to /usage ; quota … age unknown routes limit sensitive work to /usage ; unknown or unavailable routes to observation, not a green verdict; any claim that work succeeded routes to a separate deliverable check. Sidewisp treats time and budget as health signals alongside progress and outcomes, but it does not turn one counter into a health verdict. Sidewisp is currently in private preview. Token usage analytics and Claude Code adapters are planned product territory, not a shipped monitoring capability.