Cost Tracker

Entity ID: ent-20260410-88248f7f0e55
Type: service
Scope: shared
Status: active
Aliases: cost tracking, token usage, /cost, model pricing

Description

The cost tracker (src/cost-tracker.ts) tracks token usage and estimated USD cost per session, broken down by model. It accumulates per-model usage (input, output, cache read, cache creation, web search), calculates costs using a tiered pricing model, persists session costs for resume, and reports via OpenTelemetry counters. Accessible via the /cost command.

How it works

Cost accumulation

addToTotalSessionCost(cost, usage, model) is called after every API response: 1. Calls addToTotalModelUsage() to accumulate per-model token counts 2. Calls addToTotalCostState() to update the global session cost 3. Emits OpenTelemetry counters: getCostCounter()?.add(cost, attrs) and getTokenCounter()?.add(...) with types input, output, cacheRead, cacheCreation 4. Tracks fast mode: if isFastModeEnabled() && usage.speed === 'fast', adds speed: 'fast' to telemetry attributes 5. Recursively processes advisor usage, logging tengu_advisor_tool_token_usage with cost_usd_micros: Math.round(advisorCost * 1_000_000)

Per-model tracking

Each model accumulates: inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens, webSearchRequests, costUSD, contextWindow, maxOutputTokens.

Pricing tiers

Tier	Models	Input	Output	Cache Write	Cache Read	Web Search
`COST_TIER_3_15`	Sonnet	$3/Mtok	$15/Mtok	$3.75/Mtok	$0.30/Mtok	$0.01/req
`COST_TIER_5_25`	Opus 4.5/4.6	$5/Mtok	$25/Mtok	$6.25/Mtok	$0.50/Mtok	$0.01/req
`COST_TIER_15_75`	Opus 4/4.1	$15/Mtok	$75/Mtok	$18.75/Mtok	$1.50/Mtok	$0.01/req
`COST_TIER_30_150`	Opus 4.6 fast	$30/Mtok	$150/Mtok	$37.50/Mtok	$3.00/Mtok	$0.01/req
`COST_HAIKU_35`	Haiku 3.5	$0.80/Mtok	$4/Mtok	$1.00/Mtok	$0.08/Mtok	$0.01/req
`COST_HAIKU_45`	Haiku 4.5	$1/Mtok	$5/Mtok	$1.25/Mtok	$0.10/Mtok	$0.01/req

Formula: (input/1M * inputRate) + (output/1M * outputRate) + (cacheRead/1M * cacheReadRate) + (cacheWrite/1M * cacheWriteRate) + (webSearchRequests * 0.01)

Unknown models default to COST_TIER_5_25 and set a hasUnknownModelCost flag.

Session persistence

saveCurrentSessionCosts(fpsMetrics?) saves to project config: lastCost, lastAPIDuration, lastToolDuration, lastDuration, lastLinesAdded, lastLinesRemoved, lastTotalInputTokens, lastTotalOutputTokens, lastTotalCacheCreationInputTokens, lastTotalCacheReadInputTokens, lastTotalWebSearchRequests, lastFpsAverage, lastFpsLow1Pct, lastModelUsage, lastSessionId.

restoreCostStateForSession(sessionId) restores if the stored session ID matches, enabling accurate cost display on session resume.

Display

formatCost(cost, maxDecimalPlaces=4) — costs above $0.50 use 2 decimal places, below use 4.

formatTotalCost() outputs: total cost, API duration, wall duration, lines changed, per-model usage breakdown, and optional x402 payment summary.

Trade-offs

Estimated, not exact — costs are calculated client-side from token counts and pricing tables. Actual billing may differ (e.g., rounding, beta pricing changes).
Unknown model fallback — defaults to Opus 4.5/4.6 pricing ($5/$25) for unrecognized models. Could over- or under-estimate depending on the actual model.
Per-session persistence — costs survive session resume but not across different sessions. No historical cost tracking.
Micros for telemetry — cost_usd_micros (millionths of a dollar) avoids floating point issues in aggregation but requires conversion for display.

Depends on

telemetry-system — OpenTelemetry counters for cost/token metrics
Model pricing tables in src/utils/modelCost.ts

Key claims

6 pricing tiers covering all Claude model families
Unknown models default to COST_TIER_5_25 ($5/$25 per Mtok)
Session costs persist and restore on resume via project config
Advisor usage tracked recursively with separate telemetry events

Relations

used_by agent-lifecycle (cost tracking per agent)
depends_on telemetry-system
related_to token-estimation-service

Sources

src-20260409-a5fc157bc756, source code analysis of src/cost-tracker.ts, src/utils/modelCost.ts