claude-costs

CLI tool to track Claude Code token usage and costs from local session data.

Inspired by ai-token-monitor (macOS Tauri app) -- this is a cross-platform Python port of the statistics engine, with corrected pricing.

Requirements

• Python 3.12+
• No external dependencies (uses stdlib tomllib)

Usage

python claude_costs.py                  # Summary report
python claude_costs.py --daily          # Day-by-day table
python claude_costs.py --daily --days 7 # Last 7 days

Summary

  Today (2026-03-21):    $28.67
  This week:            $422.60
  This month:           $963.58
  All time:           $1,181.18  (since 2026-01-09)

  By model (all time):
    claude-opus-4-6                 $1,108.93  (93.9%)
    claude-haiku-4-5-20251001          $31.54  (2.7%)
    claude-sonnet-4-6                  $18.36  (1.6%)
    claude-sonnet-4-5-20250929         $11.81  (1.0%)
    claude-opus-4-5-20251101           $10.54  (0.9%)

  Tokens (all time):
    Cache read        1,328,258,641  (95.7%)
    Cache write          54,404,325  (3.9%)
    Output                4,518,536  (0.3%)
    Input                 1,261,361  (0.1%)

  Total messages: 15,177

  Costs shown at Anthropic API per-token rates (pricing.toml).
  On a Pro/Max subscription you pay a flat monthly fee, not per-token.

Daily table

  Date           Messages   Sessions       Cost
  ------------ ---------- ---------- ----------
  2026-03-17          616          -     $60.43
  2026-03-18        1,301          -     $86.95
  2026-03-19          170          -     $31.32
  2026-03-20          522          -     $62.82
  2026-03-21          240          -     $28.67
  ------------ ---------- ---------- ----------
  Total             2,849               $269.19

How it works

Parses Claude Code session files at ~/.claude/projects/**/*.jsonl, extracts type: "assistant" entries with token usage data, deduplicates by message ID, and calculates costs using per-model pricing from pricing.toml.

Each JSONL file contains streaming chunks for each assistant response. The tool keeps the last chunk per message (identified by message.id + requestId), which has the final output token count.

Session counts

The daily table includes a Sessions column. Session counts come from Claude Code's internal ~/.claude/stats-cache.json file, not from the JSONL session files themselves. Claude Code maintains this cache through its own mechanism, and it may not stay current -- on our test machine it stopped updating in February 2026. When no session data is available for a given day, the column shows -. Token counts and costs are unaffected since those come directly from JSONL parsing.

Pricing

Costs are calculated at Anthropic API per-token rates. On a Pro/Max subscription you pay a flat monthly fee, not per-token.

Rates from Anthropic's official pricing (per million tokens):

Model	Input	Output	Cache Read	Cache Write (1h)
Opus 4.5/4.6	$5	$25	$0.50	$10
Opus 4.0/4.1	$15	$75	$1.50	$30
Sonnet	$3	$15	$0.30	$6
Haiku 4.5	$1	$5	$0.10	$2

Edit pricing.toml to update rates when Anthropic changes pricing.

Note: The original ai-token-monitor uses $15/$75 for all Opus models. That rate only applies to Opus 4.0/4.1. Opus 4.5 and 4.6 are $5/$25 -- a 3x difference that significantly inflates reported costs.

Token count validation

We investigated whether the tool counts tokens correctly by comparing its output against Claude Code's internal ~/.claude/stats-cache.json, which tracks usage through a separate mechanism.

What we verified

Input, cache read, and cache write tokens are set once per API call and are identical across all streaming chunks for a given message. The dedup strategy (first vs last chunk) does not affect these counts. Our all-time totals are in the same order of magnitude as the stats-cache figures for the overlapping date range.

Output tokens grow during streaming as the response is generated. We initially kept the first streaming chunk per message (which has a partial output count). After discovering this, we switched to keeping the last chunk, which corrected a ~2.8x undercount on output tokens. Since output is a small fraction of total cost (~3% for heavy Opus usage), the dollar impact was modest.

Remaining ambiguity

The stats-cache.json modelUsage totals do not exactly match our parsed totals. We believe this is because the stats-cache is computed by Claude Code internally through a different mechanism than JSONL file parsing -- possibly server-side usage tracking. Without access to Anthropic's billing data, we cannot obtain a ground-truth comparison.

The tool correctly parses what the JSONL files contain. Whether those files capture the complete picture of all token usage is an open question.

Files

claude_costs.py     # The tool (single file, no install needed)
pricing.toml        # Editable pricing config