"How much Claude Code have I used?" sounds like a single measurement. It is not.
The percentage beside a five-hour reset answers a different question from the token count in a local session log. Applying API prices to those tokens produces a third value. The provider's billing page is a fourth source.
Putting all four behind one label such as "cost" makes the interface simpler and the answer less trustworthy.
Start with the quota clock
On macOS, Claude Code currently reports five-hour and weekly usage windows. Each window has a used percentage and a reset time.
That is capacity planning data. It tells you whether the current window is nearly exhausted. It does not identify the model behind the activity or explain an invoice.
The UI can show used or remaining percentage, but the underlying provider value stays the same.
Build the local ledger from events
Token activity belongs to the sessions stored on the machine. A useful ledger keeps these categories distinct:
input tokens
output tokens
cache creation tokens
cache read tokens
The timestamp on the event determines its day and week. The time a scanner happens to revisit the file does not.
Replay protection matters too. A restart or watcher refresh can scan the same JSONL record again. Without a stable event identity, every rescan inflates the report.
Price estimates need a date and a label
For a known model, a tracker can apply a dated price snapshot:
estimated API value =
input × input price
+ output × output price
+ cache creation × cache creation price
+ cache reads × cache read price
The result is an estimate of API value. It is not Claude Code subscription spend, savings, or an exact reconciliation with the provider.
Unknown model identifiers should remain unpriced. Silently mapping them to a convenient rate trades visible uncertainty for a false number.
Keep actual billing outside the estimate
Subscription terms, included usage, provider accounting, price changes, and incomplete local logs can all separate the estimate from the amount paid. The provider's billing surface remains the source for actual charges.
This separation gives each number one job:
- quota windows: capacity and reset planning;
- local events: token and model activity;
- dated API prices: estimated API value;
- provider billing: actual charges.
Privacy is part of the measurement model
Agent Island reads session records locally and computes its ledger on the Mac. It does not upload transcript content to an Agent Island service, and it does not require an Agent Island account. A weekly or monthly card leaves the app only after an explicit copy or share action.
I help run Agent Island. The usage, cost, and report behavior described here is verified on macOS in v1.7.1. I am not claiming Windows parity for these usage surfaces.
The canonical guide includes the full checklist and the two-window example:
