Claude API Cost Tracking#

Decant computes session cost at ingest time and reconciles it against current pricing on every sync, writing the result to the estimated_cost_usd column on the session row. Four project-specific mechanics govern accurate cost accounting for Claude sessions: per-block usage deduplication, TTL-split cache write pricing, per-request model and tier pricing, and additive schema migrations that carry new token dimensions without breaking existing archives. 1

Per-Block Usage Deduplication#

Claude Code journals emit one JSONL line per content block in an assistant turn — thinking, text, tool-use — and repeat the full usage object on each line. Without deduplication, a three-block turn would triple the billed token count.

The fix lives in billAssistant() in src/sources/claude.ts. It maintains a billed map keyed by the billable turn identifier: the top-level requestId field (also request_id), with fallback to message.id when requestId is absent 2. The newer Claude Code journal format omits requestId entirely, making the message.id fallback the common path.

When a duplicate key is seen, billAssistant applies a max-output supersede strategy 3:

• If the new record's output token count is not greater than the previously recorded one, the new record gets usage: null — it's preserved in the transcript but excluded from billing.
• If the new record has more output tokens (e.g., the text block after a thinking block), the earlier record is nullified and the new one takes over.

All content blocks are kept in the message list regardless; only the usage field is suppressed on duplicates. The deduplication was introduced in commit 997d961 alongside INGEST_PIPELINE_REVISION = 2 4, which triggers a one-time re-ingest of previously-processed Claude source files so historical costs are corrected automatically on the next decant sync. 1

Cache Write Pricing#

Claude bills cache creation tokens at two TTL tiers — 5-minute (1.25× input rate) and 1-hour (2× input rate) — which must be priced separately. 1

estimateCostParts() in src/cost.ts handles this by:

1. Reading cacheCreation (total) and cacheCreation1h (1-hour portion) from the TokenUsage object.
2. Clamping the 1-hour figure so it cannot exceed the total 5.
3. Deriving the 5-minute portion as creationTotal − creation1h 6.
4. Multiplying each portion by its respective per-Mtok rate (cacheWritePerMtok and cacheWrite1hPerMtok).

The 1-hour cache creation tokens are stored separately in session.total_cache_creation_1h_tokens (added in migration 12, described below) so that sync can reprice correctly from archived session data without re-reading source files. 7

If a model slug is unrecognized or explicitly unpriceable (e.g., codex-auto-review), estimateCostParts returns all-zero cost parts rather than guessing a neighboring model's rate. 1 8

Per-Request Model and Tier Pricing#

Session cost is not computed from session totals at the session's dominant model. Each billed request is priced at the model that served it and at its price tier, so a session that switches models is priced per model.

Usage is split by model and tier in the session_model_usage table (schema v25), with one row per (session_id, model, tier) holding the request count and token totals. The rows are derived from the per-request usage already stored on each message, so no transcript is reread and sessions whose source files have been pruned are covered.

• Ingest writes the split for each session and prices estimated_cost_usd from it.
• Sync backfills missing or outdated rows from the archive (materializeMissingModelUsage()) before repricing.
• Repricing of session costs, activity costs, and the model breakdown all use the split at current rates. stats --by model and /api/stats/by-dimension?dim=model still count each session once under its label, but tokens and cost follow the model behind each request, with each session's cost divided among its models in proportion to their cost at current rates.

Tiers applied per request:

• Claude Haiku 5.5 long prompts. Prompts over 100,000 tokens use a long-prompt rate five times the short-prompt rate.
• Fast mode. Requests with fast-mode speed cost 2× on Opus 5.5, Opus 5, and Opus 4.8.

Claude Sonnet 5.5 cache reads are priced at $0.10 per million tokens, down from $0.20; see docs/pricing.md for the current rates.

Sources that log no per-request model (such as Codex) and sessions whose per-request usage does not add up to their totals are still priced from session totals at the session's model.

Additive Schema Migrations#

New token and cost dimensions are added via ALTER TABLE … ADD COLUMN migrations (or, for the per-model split, a new table) in src/db.ts, never by dropping or rewriting columns. Each migration is gated by a hasColumn check for idempotent replay. 9

Relevant migrations:

Archives at schema v8–v24 migrate forward automatically on open; the next decant sync backfills the new columns for unchanged sessions. 12 Archives older than v8 must be rebuilt from source logs.

Cost Reconciliation and Repricing#

Sync reconciles stored session and activity costs against the current pricing table on every run, including unchanged and archived sessions whose source files are no longer available. refreshSessionCosts() reads each session's per-model usage rows from session_model_usage (falling back to session totals at the session's model when a session has no rows), applies estimateCostParts() with the live pricing table, and updates estimated_cost_usd and cached activity cost components (session_economics.vector_json) in one transaction.

Stale session costs and activity cost components update atomically. Recommendations and server economics caches refresh after repricing, even when ingested is zero. Matching costs are left untouched, and transcripts and user metadata (archive/delete state, recommendation status) are preserved. This eliminates the rebuild requirement when rates or pricing logic change.

The sync report includes repriced when stored cost estimates changed without requiring re-ingest.

Key Files#