ai-usage

CLI rollup of local AI harness token usage and API-equivalent cost, in the style of Theo's usage tracker. Prints per-harness tables (Input / Output / Cache Create / Cache Read / Total Tokens / Cost) for today, the last 7 days, month-to-date, and all time.

Example output

A default run prints four tables. This synthetic, abridged example shows the last-seven-days table; model names, token counts, and costs vary with usage.

$ ai-usage

Last 7 days · 2026-07-12 → 2026-07-18
+---------+-----------------------+---------+---------+--------------+------------+--------------+-------+
| Harness | Models                |   Input |  Output | Cache Create | Cache Read | Total Tokens |  Cost |
+---------+-----------------------+---------+---------+--------------+------------+--------------+-------+
| claude  | claude-sonnet-example | 482,500 | 124,000 |       60,000 |  1,253,000 |    1,919,500 | $3.91 |
+---------+-----------------------+---------+---------+--------------+------------+--------------+-------+
| codex   | gpt-codex-example     | 318,000 |  87,500 |            0 |    946,000 |    1,351,500 | $1.39 |
+---------+-----------------------+---------+---------+--------------+------------+--------------+-------+
| TOTAL   | claude-sonnet-example | 800,500 | 211,500 |       60,000 |  2,199,000 |    3,271,000 | $5.30 |
|         | gpt-codex-example     |         |         |              |            |              |       |
+---------+-----------------------+---------+---------+--------------+------------+--------------+-------+

Sources

• Claude Code — ~/.claude/projects/**/*.jsonl assistant-message usage blocks, deduped by (message.id, requestId) across files.
• Codex CLI — ~/.codex/{sessions,archived_sessions}/**/rollout-*.jsonl token_count events (last_token_usage), with the model tracked from turn_context events. input excludes cached tokens; cached tokens are reported as Cache Read (OpenAI doesn't report/charge cache writes).

Either source is optional. If only one has usage, the text report identifies which source was included; missing log directories do not cause an error.

How it works

• Per-file aggregates are cached in SQLite (~/.local/share/ai-usage/usage.db) keyed by (path, mtime, size), so only new/changed logs are reparsed — warm runs take ~20ms.
• Daily totals are persisted with a monotonic max-merge, so all-time numbers survive Claude Code's ~30-day transcript pruning. History accrues from whenever you first run the tool.
• Pricing comes from LiteLLM's model_prices_and_context_window.json, fetched with a 24h cache in ~/.cache/ai-usage/ and falling back to the snapshot bundled at build time (data/pricing-fallback.json, refresh with bun run refresh-pricing). Models without pricing (e.g. codex-auto-review) are flagged with * and excluded from cost.

Costs are API list-price equivalents. Actual spend under a subscription plan (Claude Max, ChatGPT Pro) differs — treat the Cost column as "what this usage would cost at API rates."

Usage

ai-usage                                  # default report
ai-usage --since 2026-07-01 --until 2026-07-15
ai-usage --json | jq .

Build & install

bun run build   # compiles dist/ai-usage
bun run link    # symlinks it into ~/.local/bin