Track Claude Code Usage Without Turning Four Signals Into One Number

"How much Claude Code have I used?" sounds like one question. It is usually four: how close am I to a provider limit, how much local token activity did my sessions produce, what would those tokens be worth at a dated API price, and what did I actually pay?

A tracker becomes misleading when it merges those answers. A quota percentage is not a token counter. A token counter is not a bill. An API-price calculation is not a subscription charge.

1. Read quota as a reset window

On macOS, Agent Island can display the Claude Code 5-hour and weekly usage windows reported for the signed-in account. Each tile combines a used percentage with its reset time. The display can also flip to percentage remaining without changing the underlying value.

This view answers a planning question: can you keep working inside the current window? It does not explain which model produced the usage, how many cached tokens were read, or what a subscription invoice will contain.

2. Build the token ledger from local events

Token activity comes from the coding sessions already stored on the machine. A reliable ledger reads provider-specific event fields, keeps input, output, cache creation, and cache reads distinct, and attributes an event to its own timestamp rather than the time the file happened to be scanned.

It also needs replay protection. Session files can be scanned again after a restart or watcher refresh. Counting the same usage event twice makes a polished report less trustworthy than no report at all. Stable event identity and bounded local scans are part of the measurement system, not implementation trivia.

3. Label API value as an estimate

Agent Island can multiply token categories by an embedded, dated model-price snapshot. For a priced model, the calculation is:

estimated API value =
  input tokens × input rate
  + output tokens × output rate
  + cache creation tokens × cache-write rate
  + cache read tokens × cache-read rate

The result is an estimated API value. It is not a claim that Claude Code billed those tokens at API rates, and it is not guaranteed to match a provider dashboard. Subscription terms, included usage, unknown model identifiers, pricing changes, and provider-side accounting can all create differences.

4. Keep the collection boundary visible

A local tracker should say where the data comes from and where it goes. Agent Island reads local session records for its ledger and does not upload transcript content to an Agent Island service. No Agent Island account is required. Sharing a weekly or monthly card is a separate, explicit action.

A practical Claude Code usage checklist

1. Use the 5-hour and weekly tiles for reset-window planning.
2. Use the local ledger for token and model activity.
3. Treat API-value calculations as dated estimates.
4. Use the provider's billing surface for actual charges.
5. Keep source freshness and re-authentication errors visible.

Current verified scope

The usage, cost, and report-card behavior described here is verified on macOS in Agent Island v1.7.1. Agent Island also ships on Windows, but this article does not claim Windows parity for these usage surfaces. Live session status and your-turn alerts are a separate cross-platform capability.