How AI Coding Token Cost Is Calculated

Verified 2026-08-03. Agent Island's local cost ledger is verified on macOS in v1.7.1. It reads local Claude Code and Codex records and applies an embedded, dated rate table. This page does not claim equivalent Windows UI behavior without current Windows runtime verification.

The formula

For one model event, convert every token count to millions and apply the matching per-million rate:

estimated API value =
  input tokens / 1,000,000 * input rate
  + output tokens / 1,000,000 * output rate
  + cache-write tokens / 1,000,000 * cache-write rate
  + cache-read tokens / 1,000,000 * cache-read rate

The four categories stay separate because their prices differ. One blended price per token will be wrong whenever output or cached activity has a different rate from ordinary input.

Normalize provider records first

Claude Code and Codex do not store usage in identical shapes. Claude records can expose input, output, cache creation, and cache reads directly. Codex records may report cached input inside the input total. A normalizer should produce the same small event structure before pricing:

timestamp
provider
model
inputTokens
outputTokens
cacheCreationTokens
cacheReadTokens

When cached input is included in total input, subtract it before applying the normal input rate:

nonCachedInput = max(totalInput - cachedInput, 0)

Then price nonCachedInput at the input rate and cachedInput at the cache-read rate. Pricing total input and adding cached input again double-counts the cached portion.

Worked example

Assume one event has 2,000,000 non-cached input tokens, 300,000 output tokens, 500,000 cache-write tokens, and 1,200,000 cache-read tokens. Suppose its dated model table lists $3 input, $15 output, $3.75 cache write, and $0.30 cache read per million tokens.

input       2.0 * $3.00  = $6.00
output      0.3 * $15.00 = $4.50
cache write 0.5 * $3.75  = $1.875
cache read  1.2 * $0.30  = $0.36
---------------------------------
estimated API value       = $12.735

The display can round that result, but the underlying categories should remain available for audit. The number answers a counterfactual question: what would these observed tokens be worth under this rate snapshot?

Use a dated rate snapshot

Model names and prices change. Agent Island embeds a price snapshot and canonicalizes dated model suffixes before lookup. An unknown model returns an unpriced result instead of borrowing the price of a similar model. The UI can then warn that some observed usage is not included in the estimate.

A historical report should retain the rate contract used when it was generated. Repricing old activity with a new table can be useful for comparison, but it is a different measurement and should be labeled as such.

Deduplicate before summing

Local rollout and transcript files are scanned repeatedly. Restarts, watcher recovery, and archive discovery must not turn an old token event into new usage. Deduplication belongs before daily, monthly, or per-model aggregation.

Codex also emits cumulative token snapshots in some records. A reader must convert them into non-negative deltas or retain stable event identities. Summing every cumulative total produces rapid overcounting.

Why the result is not your bill

Local records do not contain the full provider billing ledger. They do not prove which activity was included in a subscription, covered by credits, adjusted by an enterprise contract, or excluded from an invoice. They can also be incomplete, and an embedded rate table can become stale.

Use estimated API value for this calculation. Do not rename it spend, savings, subscription cost, or provider bill. Actual billing requires the provider's billing records and the user's commercial terms.

Implementation checklist

1. Read provider-specific local records.
2. Normalize input, output, cache write, and cache read.
3. Convert cumulative counters into deltas where required.
4. Deduplicate replayed events.
5. Canonicalize the model name and use a dated price entry.
6. Flag unknown models instead of guessing.
7. Keep the API-value estimate separate from quota and billing.