What Should an AI Coding Cost Tracker Actually Measure?

An AI coding cost tracker can answer a useful question: what is the estimated API value of the Claude Code and Codex activity recorded on this machine? It cannot answer a different question without billing data: how much money did the user actually pay?

The distinction starts at collection. A trustworthy tracker needs a measurement contract that names the records it reads, the token categories it preserves, the rate table it applies, and the events it cannot price.

1. Start with provider-specific source records

Claude Code and Codex do not emit identical local records. Claude assistant messages can include input, output, cache creation, and cache-read fields. Codex rollout records can separate model context from later token events and can include cached input inside the input total.

A cost tracker should normalize both providers into a small event model before it calculates anything:

provider
timestamp
model
input tokens
output tokens
cache creation tokens
cache read tokens

This boundary prevents a UI component from guessing what a raw field means. It also allows provider-specific parsing rules to change without silently changing the definition of the final number.

2. Price cache activity without double counting

Cache tokens can dominate local activity, but their rates differ from normal input and output. Claude records cache creation and cache reads separately. For Codex, cached input must be subtracted from total input before the normal input rate is applied.

non-cached input = max(total input - cached input, 0)

estimated API value =
  non-cached input * input rate
  + output * output rate
  + cache creation * cache-write rate
  + cache read * cache-read rate

Pricing total input and then adding cached input again produces a precise-looking overcount. A single generic token multiplier is not enough.

3. Make replay protection part of accounting

Local session files are scanned more than once. Apps restart, watchers reconnect, files are appended, and archived sessions can be rediscovered. The same token event must not become new activity merely because the scanner saw it again.

Stable provider event identifiers should be deduplicated before aggregation. When a format lacks a reliable identifier, the tracker should document the fallback and its uncertainty instead of inventing certainty from file offsets alone.

4. Date the model price table

API prices change and new model identifiers appear before local software knows how to price them. A tracker should ship a dated rate snapshot and surface unknown models as unpriced. Guessing a nearby model family rate makes historical comparisons impossible to audit.

Agent Island labels the result API value. It is a counterfactual calculation under the embedded rates, not evidence of subscription spend, credits consumed, savings, or an invoice total.

5. Keep billing outside the local estimate

Actual spend depends on receipts, provider billing exports, included subscription usage, enterprise contracts, credits, and provider-side adjustments. Local coding-session records do not contain that complete accounting context.

A useful cost screen therefore keeps four answers distinct: provider quota, local token volume, estimated API value, and actual billing. Combining them into one "cost" number removes the very context a developer needs to make a decision.

Cost-tracker evaluation checklist

1. Identify the exact local records used for each provider.
2. Preserve input, output, cache creation, and cache reads separately.
3. Deduplicate replayed events before aggregation.
4. Date the price table and flag unpriced models.
5. Label the result as an estimate, never an invoice.
6. Keep collection local and sharing explicit.

Current verified scope

The usage-ledger and API-value behavior described here is verified on macOS in Agent Island v1.7.1. Agent Island also ships on Windows, but this page does not claim identical cost-tracker surfaces there without current UI verification.