ai-usage-mcp

Ask your coding agent what it has cost you — and where the money went. An MCP server that answers from the data Claude Code and OpenCode already wrote to your machine. Nothing is uploaded, and there is no API key or account.

> Where are my tokens going, and what should I change?
> Where did this session lose its prompt cache?
> Which of my projects is getting more expensive, day by day?
> What would last week have cost on Sonnet instead of Opus?

Three things it does that reading the transcripts cannot:

• It keeps your history. Claude Code deletes transcripts after 30 days (cleanupPeriodDays). Every turn is copied into a local SQLite database as it is seen, so last quarter is still there after the source files are gone — and merges two machines into one total.
• It finds where the cache broke. Cache tokens are where the money is — 94.7% of all tokens on the development machine. cache_health finds the turns where a session lost its cached prefix and paid to re-write the whole context, names the likely cause (a model switch, idling past the 5-minute TTL, an edited CLAUDE.md) and prices the premium.
• It proves its numbers. Claude Code writes one JSONL line per content block, each repeating the same usage object, so summing lines inflates every figure 2–3×. ai-usage verify re-reads both sources with a second, independent implementation that shares no reduction code with the collectors, and diffs the result against its own database.

$ ai-usage verify

== claude-code ==
  MATCH    claude JSONL, deduped by stop_reason line (independent rule)
  INFO     claude JSONL, naive sum of every usage line (NOT used -- shows the double count)
           delta:  cache-read 990,824,820 ...

RESULT: every client reconciles exactly against at least one independent read of its source.

Also: counterfactual_cost (these exact tokens at another model's rates), budgets with run rate and forecast, project × day breakdowns, and CSV/JSON export. It supports Claude Code and OpenCode, and exposes eleven MCP tools plus resources, prompts and a debug CLI that prints the same text the tools return.

It never fabricates a number. If a source does not record something, it is reported as unavailable — not as zero.

$ ai-usage stats --today
Usage summary -- today (local time)
Subagent/sidechain turns: INCLUDED (3 main + 1 subagent turns).

Records: 4   Sessions: 2

Tokens (all clients):
  Input:        1,871
  Output:       16,909 (16.9K)
  Cache read:   2,452,000 (2.45M)
  Cache write:  37,300 (37.3K)
  Reasoning:    2,600
  Total:        2,508,080 (2.51M)

  Cost (reported by client, exact): $0.41  [1 records]
  Cost (estimated, API-equivalent):  $1.50  [3 records]

By client:
  claude-code  --  3 records, 1 sessions
    Cache read:   2,238,000 (2.24M)
    Total:        2,280,001 (2.28M)
    Cost (estimated, API-equivalent):  $1.50  [3 records]

  opencode  --  1 records, 1 sessions
    Cache read:   214,000 (214.0K)
    Total:        228,079 (228.1K)
    Cost (reported by client, exact): $0.41  [1 records]

ai-usage or ccusage?

ccusage is the established tool, and a good one: it covers far more agents, and its Claude Code token counts agree with this package's exactly — every token class, every day, checked against ccusage 20.0.26 on the development machine for 21–25 September 2026. For a quick report across many agents, use it.

Use this one when you want what a report over the current transcripts cannot give: history that outlives Claude Code's 30-day cleanup, cache breaks found and priced, counterfactual pricing, budgets, cross-dimension breakdowns, reported and estimated cost kept apart, and token totals proved against a second read by verify.

Install

Requires Node.js 22.13+. No compiler, build tools or particular npm version needed: storage uses Node's built-in node:sqlite, which is unflagged from 22.13.0 onward. There is no mandatory native dependency.

_{better-sqlite3 remains an optional fallback for hosts whose Node predates that. It is never required — if it cannot be built, npm skips it and the server still runs.}

Claude Code

As a plugin — recommended. Run these two inside Claude Code:

/plugin marketplace add MohitBansal321/ai-usage-mcp
/plugin install ai-usage@ai-usage-mcp

That wires up the MCP server and installs the three prompts as real slash commands — /ai-usage:daily-review, /ai-usage:why-was-today-expensive, /ai-usage:project-cost — which most clients never surface from MCP prompts alone. If the install summary says Run /reload-plugins to activate., run that. The equivalent from your shell is claude plugin marketplace add MohitBansal321/ai-usage-mcp.

_{The plugin declares npx -y ai-usage-mcp as its server, so the server itself still comes from npm and re-resolves on each cold start. Updating the plugin and updating the server are therefore independent — see Updating.}

Or as a plain MCP server, if you would rather not add a marketplace. Nothing to install first — npx fetches it on demand:

claude mcp add ai-usage -s user -- npx -y ai-usage-mcp

On native Windows (not WSL), wrap it in cmd /c instead:

claude mcp add ai-usage -s user -- cmd /c npx -y ai-usage-mcp

_{Why: on Windows npx is npx.cmd, and the MCP TypeScript SDK spawns servers with shell: false. Node cannot execute a .cmd file that way — its docs say such files "can be invoked using child_process.spawn() with the shell option set … or by spawning cmd.exe and passing the .bat or .cmd file as an argument". cmd /c is that second form. This applies to every SDK-based client below, not just Claude Code.}

-s user makes it available in every project. Drop it to add the server to the current project only. Then run /mcp inside Claude Code to confirm it connected.

{
  "mcpServers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

{
  "mcpServers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

OpenCode

opencode mcp add ai-usage       # choose a local server, command: ai-usage-mcp

Or add it to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "ai-usage": {
      "type": "local",
      "command": ["npx", "-y", "ai-usage-mcp"],
    },
  },
}

Confirm with opencode mcp list.

Other MCP clients

The client you ask from does not have to be a client you measure. This server reports on the Claude Code and OpenCode data already on your disk no matter who asks for it — so if you spend your day in Cursor but your tokens go through Claude Code, ask Cursor and you still get the real numbers.

Cursor, Google Antigravity, Windsurf and Claude Desktop all take the same block. Only the file path changes:

{
  "mcpServers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

For Claude Desktop, that button creates the file if it does not exist and opens it either way, which is more reliable than editing by hand:

Claude Desktop on Linux is in beta and Anthropic publishes no config path for it, so use the Edit Config button rather than guessing one. Fully quit and relaunch afterwards — the file is read at startup.

Two clients need a different shape:

Codex uses TOML, not JSON. Easiest is the CLI:

codex mcp add ai-usage -- npx -y ai-usage-mcp

Or add the table by hand to ~/.codex/config.toml (or a project-scoped .codex/config.toml):

[mcp_servers.ai-usage]
command = "npx"
args = ["-y", "ai-usage-mcp"]

Confirm with codex mcp list.

GitHub Copilot CLI uses ~/.copilot/mcp-config.json, where the top-level key is servers, not mcpServers:

{
  "servers": {
    "ai-usage": {
      "command": "npx",
      "args": ["-y", "ai-usage-mcp"]
    }
  }
}

On native Windows, use the cmd /c form in any of these — "command": "cmd" with "args": ["/c", "npx", "-y", "ai-usage-mcp"], or command = "cmd" with args = ["/c", "npx", "-y", "ai-usage-mcp"] for Codex. See the note under Claude Code for why.

_{Provenance, 2026-09-08: Cursor, Windsurf, Codex and Claude Desktop paths are from each vendor's own documentation. The Antigravity and Copilot CLI paths and key names were read off installed copies of those apps on Linux, since neither publishes the path — including Copilot CLI's servers key, which differs from every other client here.}

The debug CLI

The MCP server needs no install. To also get the ai-usage CLI on your PATH:

npm install -g ai-usage-mcp
ai-usage status

Or run it without installing:

npx -y -p ai-usage-mcp ai-usage stats --today

Windows: no longer needs a particular npm. The node-gyp failure that used to break this install came from the native better-sqlite3 dependency, which is now optional and unused on Node 22.13+. If npm still reports a build failure for it, that message is a skipped optional dependency, not a failed install — ai-usage status will show SQLite driver: node:sqlite and everything works.

Verified against Claude Code 2.1.251 and OpenCode 1.18.25.

Updating

npx -y ai-usage-mcp — the form the instructions above use — re-resolves the version every time your client cold-starts the server, so it keeps itself current. Restart the client to pick up a new release.

A global install is pinned until you update it by hand:

npm install -g ai-usage-mcp@latest
ai-usage --version

ai-usage status tells you when you are behind:

Update available: 0.1.0 installed, 0.2.0 latest -- npm i -g ai-usage-mcp@latest

The MCP server says so too, because most people never run the CLI. When the server finds a newer release it says it once per process, through whichever channel comes first: a line added to the instructions it returns at handshake time, or a one-off note attached to the next tool result. It is a separate content block, so the numbers a tool returns stay exactly what the CLI prints for the same query, and it never repeats itself on later calls. The same line goes to the server's stderr log, and @usage://status shows the state on demand.

The advice differs by how you installed it, and the notice says the right one:

That check is one of the package's two network requests (the other downloads prices for new models -- see New models are priced automatically): a version lookup against the npm registry, at most once a day, cached in <config dir>/update-check.json, skipped when CI is set, and silently abandoned after 1.5s if you are offline. It sends no usage data and no identifier -- just a GET for a version string. Set AI_USAGE_NO_UPDATE_CHECK=1 to turn it off everywhere, CLI and server alike; that switch turns off the price download too. In the server it runs after the handshake, never during it, so it cannot slow down a client starting up.

Ask it things

Once connected, ask in plain language:

How many tokens have I used today?
Show my usage for this session.
Which model consumed the most tokens?
How much did Claude Code cost me today?
Show all usage from the last 7 days.
Which repository is my spend going to?
Break my last 7 days down day by day.

MCP tools

Start here: usage_report

On a Pro, Max or Team plan the price is fixed, so "what did it cost" is the wrong question. The useful one is how much of your limit went to real work. usage_report (or ai-usage report) answers it for the last 7 days by default:

Verdict: High waste -- a large share of this usage re-read or rebuilt old context.

Where it went (share of usage, weighted by API-equivalent price):
   37.1%  re-reading context above 100k tokens (1,021 turns; largest context 735.2K)
   10.2%  rebuilding a lost cache (12 times, 12 after an idle break)

What to change:
  1. Compact earlier. ... 5 session(s) grew past 200k tokens of context ...
  2. Don't resume a session that has gone cold. ...

Heaviest sessions:
   47.7%  Admission transfer tariff services and roles linking  [development, claude-code]

It measures two kinds of waste from token counts alone. Context carry exists because every message re-sends the whole conversation, so a turn at 300k context re-reads 300k tokens to take one step; the part above 100k is what compacting earlier would not have carried. Cache rebuilds are turns where the cached prefix was lost and the whole context was re-written (the same detection as cache_health). Sessions are named by the title the client gave them and the git branch they ran on. Neither kind of waste is claimed as wholly avoidable, and the shares are a guide to where usage went, not exact limit consumption: Anthropic does not publish how subscription limits weight each token type.

Every period-based tool takes projectPaths (a list) to narrow the report to one or more projects. The pre-0.8.0 singular projectPath is still accepted.

An argument a tool does not declare is rejected by name, not ignored. Before 0.9.0, { "period": "today" } was silently stripped and answered with all-time totals; every tool now advertises additionalProperties: false.

counterfactual_cost answers "would a cheaper model have cost less for this?" — it re-prices the exact token counts that were recorded, grouped by client, model and speed so the fast-mode premium and the two clients' different reasoning-token conventions are both handled. It is a counterfactual, not a saving: the same task on a different model generally takes a different number of turns carrying a different context on each, and nothing on disk can say what that would have been. The caveat ships with the numbers.

cache_health finds the turns in a session where the prompt cache stopped working: cache writes spike and cache reads fall below half of what the previous turn had cached, so the whole context was re-written at cache-write prices. A write spike alone -- reading one large file -- is not a break, because the existing prefix was still read back. Each break names a likely cause (a model or speed switch, idling past the 5-minute cache TTL, or an early-context change such as an edited CLAUDE.md) and its write premium, priced from the same versioned table as every other estimate. Main and subagent turns keep separate caches, so subagents are excluded by default and baselined separately when includeSubagents is set.

Resources and prompts

Three resources can be pulled into a conversation with an @ mention, instead of asking for a tool call:

Three prompts appear as slash commands in a client that surfaces them:

Each prompt names the tools to call and carries the reported-vs-estimated cost rule with it, so a paraphrased summary cannot quietly merge the two cost bases.

Most clients do not surface MCP prompts, which is why the Claude Code plugin ships the same three as real slash commands (/ai-usage:daily-review and friends). They are the same feature through two surfaces, and a test asserts the two lists cannot drift apart.

Debug CLI

Same service layer, different frontend — so the two can never disagree.

ai-usage report      # start here: verdict, where usage went, what to change (last 7 days)
ai-usage status      # collectors, data stores, db path, record counts, last sync
ai-usage sync        # run the collectors
ai-usage stats       # totals   (--today, --days N, --since/--until)
ai-usage models      # per-model
ai-usage clients     # per-client
ai-usage projects    # per-project  (--limit N)
ai-usage sessions    # recent sessions
ai-usage session ID  # one session in detail
ai-usage daily       # per-day breakdown
ai-usage counterfactual  # these tokens on another model (--target-models a,b)
ai-usage verify      # re-read the sources and diff them against the local database

Add --json to any command for machine-readable output.

Narrowing to several projects, models or clients

--client, --model and --project are repeatable and comma-separated, and each matches any of the values given:

ai-usage models   --model claude-opus-5,claude-sonnet-5
ai-usage daily    --project /work/api --project /work/web    # same as a comma list
ai-usage stats    --client opencode

Different scopes combine with AND: --model claude-opus-5 --project /work/api is Opus turns in that project.

A value that matches no record anywhere in the database is called out rather than answered with an empty report, because a typo and a quiet week otherwise look identical:

WARNING: no record anywhere in this database has model "claude-opus". An empty result below
is that, not a quiet period. Run `ai-usage models` to see the ids actually present.

Note that --model (which turns to include) and --target-models (which rates to price them at, on counterfactual only) are different things, and usable together: ai-usage counterfactual --model claude-opus-5 --target-models claude-sonnet-5 asks what the Opus turns would have cost on Sonnet.

Getting the data out

ai-usage export --days 30 > usage.csv        # one row per stored turn
ai-usage export --format jsonl               # JSON Lines
ai-usage export --project /work/api --model claude-opus-5

Every scope and period filter applies. The column set is a stable, documented contract — deliberately not SELECT *, so the table can grow a column without breaking every downstream spreadsheet, and no column can silently change meaning:

id, timestamp, client, provider, model, session_id, project_path, turn_kind, speed,
input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cache_write_5m_tokens,
cache_write_1h_tokens, reasoning_tokens, total_tokens, cost_basis, cost, estimated_cost, currency

cost and estimated_cost are separate columns carrying cost_basis alongside, for the same reason every report keeps them apart. A value the source did not report is an empty cell, never 0 and never null — a figure nobody produced must not arrive in a spreadsheet as a number that gets summed with the real ones.

Rows stream to stdout rather than being built in memory, so exporting a large database costs one row at a time. A --limited export says on stderr how many rows it left behind, which keeps stdout pipeable.

(Previously the only route to the records was sqlite3 usage.db '.mode csv' 'SELECT * FROM usage_records', which bypasses the product and depends on a schema the docs explicitly call internal and unversioned.)

Retention and merging two machines

The database grows forever unless you tell it not to. Pruning is a command, not a policy — a retention setting that silently deleted last quarter on some future run is a worse tool than one that never deletes, because the data is gone and nothing asked. Put it in a cron if you want a policy:

ai-usage prune --before 2026-01-01          # DRY RUN: says what would go, deletes nothing
ai-usage prune --before 2026-01-01 --yes    # actually delete
ai-usage vacuum                             # reclaim the disk

--before is exclusive, like every other bound here: --before 2026-01-01 removes 2025 and keeps New Year's Day. Scope filters apply, so a prune cannot be broader than the report that justified it. vacuum measures the database's whole footprint — the .db plus its -wal and -shm companions — because this package always opens in WAL mode, where freshly written data lives in the -wal until a checkpoint folds it back. Measuring only the .db would report reclaiming nothing while most of the bytes sat next door.

Two machines, one total:

# on the laptop
ai-usage export --format jsonl > laptop.jsonl

# on the desktop
ai-usage import laptop.jsonl

Merging is idempotent. Record ids are derived deterministically from source identifiers, so the same turn — imported twice, or collected on both machines — upserts to one row rather than double counting. The output says how many rows were updated in place rather than added, so you can see that happening.

A row that does not fully parse is rejected with its line number and the import exits non-zero. Importing a half-valid row would write a turn with invented zeroes, and a merged database that quietly under-counts is worse than a failed import.

Cache economics

Cache tokens are where the money is — on the development machine cache-read is 94.7% of all tokens, and for Claude Code it outweighs plain input by roughly 33,000×. Raw counts alone cannot say whether that cache is paying for itself, so stats and clients derive the figures that can:

claude-code  --  8,486 records, 86 sessions
  Cache hit rate:    97.12%
  Reads per write:   33.7  (1 write : 33.7 reads)
                     Break-even is 0.28 reads per 5-minute write and 1.11 per 1-hour write,
                     so this cache is paying for itself.

Break-even is derived from the pricing table's own multipliers, not hardcoded: a 5-minute write costs 1.25× input, so 0.25× extra, and each read saves 0.9× — hence 0.25 / 0.9 = 0.28 reads per write. Change the multipliers (or use a provider whose cache discount differs) and the threshold moves with them.

A hit rate is absent, not 0%, when there was no cache traffic at all — those are different statements. A genuine 0% (writes that were never read) is reported, because it is the worst case for the write premium and exactly what you would want to see.

counterfactual adds what the same tokens would have cost with no caching at all:

Those same tokens with NO prompt caching at all:
  claude-opus-5       $5252.61  vs     $861.31 actually estimated  ->  cache saved $4391.29 (83.6%)
  claude-sonnet-5      $117.37  vs      $22.20 actually estimated  ->  cache saved $95.17 (81.1%)

This is the one scenario in the tool permitted to state a saving, and the reason is worth knowing. A model counterfactual cannot: the same task on a different model takes a different number of turns with a different context on each. Here the token counts genuinely are invariant — cache-read tokens are the context re-sent each turn, so without a cache they would have been sent as ordinary input one for one, and the write premium would simply not have been paid. The remaining assumption (that a cacheless run would have made the same requests) prints with the numbers.

A negative saving is reported as such rather than clamped: burning the write premium on sessions too short to reuse it is precisely what this is for.

Budget, run rate and forecast

ai-usage budget --amount 500 --basis estimated            # this calendar month
ai-usage budget --amount 20  --basis reported --period week

Budget -- September 2026 (local), estimated cost basis

  Budget:             $500.00
  Spent so far:       $505.86   101.2% of budget
  OVER BY:              $5.86
  Elapsed:       16.5 of 30 days   55.0% of period

Run rate and projection to period end:
  Per calendar day       $30.65/day  ->      $919.65   OVER by $419.65
                     (over 16.5 elapsed calendar days)
  Per active day         $42.15/day  ->     $1264.65   OVER by $764.65
                     (over 12 day(s) with any recorded activity)

Two projections, never one. Extrapolating month-end spend by hand meant picking a denominator — calendar days or active days — and on a machine used on weekdays only those differ by more than 2×. Showing one would be making that modelling choice silently on your behalf; the gap between them is the size of the assumption.

--basis is required, with no default. Reported and estimated cost are never summed, so a budget with no stated basis is a budget against nothing in particular:

• reported — what a client actually charged. Claude Code reports no cost at all, so its usage is not counted on this basis.
• estimated — API-equivalent list price. On a Claude Pro/Max subscription your marginal cost per request is $0, so this is a shadow price for comparing workloads, not a bill. The figure to watch on a subscription is usage against your plan limits, which this tool cannot see. The output says so every time.

Calendar periods only (month, week). A projection needs a period end to aim at, which a rolling window has not got.

Exit 1 on a fact, not on a forecast. budget exits 1 when spend already exceeds the target. It does not fail on a projection — that would page somebody about arithmetic rather than about spend. To threshold a projection deliberately, compose with --field:

ai-usage budget --amount 500 --basis estimated \
  --field projections.perActiveDay.projected --fail-over 500

Using it in a script or an alert

ai-usage stats --today --field overall.cost.estimated
# 18.067632500000002

ai-usage stats --today --field overall.cost.estimated --fail-over 25 || notify "over budget"

--field prints one value and nothing else — no header, no label, no JSON — so a shell can read it without jq. --fail-over turns that same value into an exit code: 1 when it is strictly greater than the threshold, 0 otherwise. stdout still carries the value, so a script can branch and capture it in one run.

Two deliberate refusals:

• --fail-over requires --field. There is no default, because reported and estimated cost are separate figures that are never summed — "fail if cost exceeds $25" has no single answer, and a default would silently ignore every record priced the other way.
• An unknown field is exit 2, never exit 0. A threshold check against a silently-missing field would pass forever, which is the worst failure an alert can have: it looks like everything is fine. The error names the fields that do exist at that level.

Crossing two dimensions

projects gives a total with no trend; daily --project X gives one series. Answering "which of my projects is getting more expensive" therefore meant enumerating projects, issuing one call per path, and joining the results — an N+1 that is not feasible as a single tool call at all. breakdown crosses the axes in one query:

ai-usage breakdown --by project,day --days 30
ai-usage breakdown --by model,day --days 7 --sort estimated-cost
ai-usage breakdown --by client,model,hour-of-day

project                                day         turns  total tokens  reported  estimated
-------------------------------------  ----------  -----  ------------  --------  ---------
/home/you/centralized_backend          2026-09-16    230    20,040,546        --     $22.23
/home/you/centralized_backend          2026-09-15    161    19,803,069        --     $18.58
/home/you/Videos/ai-usage              2026-09-17     82    24,592,585        --     $18.07

Axes: client, model, provider, project, session, day, hour, hour-of-day — up to three, each at most once. Time axes bucket in local time, identically to daily.

Two things it deliberately does not do. Combinations with no activity are absent rather than returned as zero rows: a project × day grid is mostly empty and filling it would bury the rows that matter. And a -- in a cost column means no record in that row is priced on that basis — it is not $0, which would be a different claim.

--sort, --limit and --offset work here as on any other list.

Reading a trend

daily shows every bucket in the window, including the ones with no activity:

2026-09-17      52 turns  total 14,187,806 (14.19M)  (estimated $11.27)
2026-09-16     333 turns  total 33,849,492 (33.85M)  (estimated $33.56)
2026-09-15     161 turns  total 19,803,069 (19.80M)  (estimated $18.58)
2026-09-14       0 turns  total 0   --
2026-09-13       0 turns  total 0   --
2026-09-12       0 turns  total 0   --
2026-09-11     123 turns  total 12,157,650 (12.16M)  (estimated $10.89)

Rows marked -- had no recorded activity. They used to be omitted, which made a trend actively misleading rather than merely incomplete: the gaps were invisible, so the 11th rendered immediately below the 15th and any eye reading down the column saw a continuous series that did not exist. A zero row is not a fabricated number — it says what the absence of a row already meant. In JSON each carries zeroFilled: true, so a consumer can tell a constructed zero from an observed one.

--grain changes the bucket:

ai-usage daily --days 7  --grain hour          # a finer timeline
ai-usage daily --days 30 --grain hour-of-day   # every day on one 24-hour clock

hour-of-day is the one that answers when you burn tokens, as opposed to how much:

10:00     185 turns  total 43,016,467 (43.02M)   (estimated $42.61)
11:00     526 turns  total 113,820,907 (113.82M) (estimated $99.95)
12:00   1,413 turns  total 280,913,509 (280.91M) (estimated $213.99)
...
19:00       0 turns  total 0   --

All buckets are local time, matching the period filter, and localtime reads the OS timezone database so they stay correct across DST.

Comparing two periods

stats --compare previous reports the equal-length window immediately before, and the delta:

ai-usage stats --days 7 --compare previous
ai-usage stats --today  --compare previous     # vs yesterday

Compared with the 7 days before that
  (2026-09-03T18:30:00.000Z -> 2026-09-10T18:30:00.000Z)

  Records:                      -847   -55.9%
  Total tokens:         -201,112,497   -71.5%
  Cost (estimated):         -$160.06   -68.3%
  Cost (reported):             $0.00   n/a, previous was zero

Three rules it keeps:

• The two cost bases are deltaed separately and never summed, for the same reason they are reported separately.
• There is no percentage change from zero. $0 → $5 is a new thing happening, not a rise of 100%, so the percentage is reported as n/a rather than invented.
• The previous window is aligned to the same local midnights the period uses. --days 7 compares against the seven whole days before, not "the 156 hours before" — which is what subtracting an open window's elapsed length gives, and which changes every time you run it.

--compare needs a period of fixed length: --days, --today, or --since and --until together. An open-ended period — all time, or --since or --until on its own — has no equally long window before it, so the comparison is refused (exit 2) rather than silently left out of an otherwise ordinary report.

Ordering and paging a list

sessions, models, projects and clients accept --sort, --limit and --offset:

ai-usage sessions --sort estimated-cost --limit 5     # the costliest, not the latest
ai-usage projects --sort estimated-cost
ai-usage sessions --limit 100 --offset 100            # page two

There is deliberately no plain --sort cost. Reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis as though it were $0. The flag refuses the ambiguous form and names the two to pick from, and whichever you pick, the output says how many rows it could not speak for:

Showing 5 of 366 sessions (offset 0), sorted by estimated-cost.
More available: re-run with --offset 5 for the next page.
NOTE: 280 of those sessions carry no estimated cost at all, so they sort as $0. They are not
cheap -- they are priced on the other basis, or not priced at all.

That footer is why --limit is now safe to pass: it says what you did not see. Before, the most expensive session was visible only if it also happened to be recent, and --limit made it less likely to be.

In --json and MCP structuredContent this is a page object carrying total, offset, hasMore, nextOffset, sort and rowsWithoutSortValue — enough to walk a list to the end and know when you are done.

ai-usage stats --today returns exactly what the usage_summary tool returns; a test in tests/mcp/parity.test.ts asserts they are byte-identical.

How cost is reported

Cost is never a single blended number. Every figure carries a basis:

Alongside those, every report counts records whose model has no pricing-table entry, so a model that is genuinely free is distinguishable from one nobody has priced. A client that reports its own cost files a perfectly ordinary $0 for an unpriced model, which otherwise reads exactly like free:

opencode  --  6,841 records, 280 sessions
  Cost (reported by client, exact): $0.48  [6,841 records]
  No estimate attempted for 6,813 record(s) -- no price in table builtin-2026-09-26 for
  that model: big-pickle, gpt-5.5, z-ai/glm-5.2 and 16 more. Any $0 above covers only what
  was reported, not those records.

In --json and in MCP structuredContent these are cost.unpricedRecords and cost.unpricedModels. Both are absent rather than 0 when the caller supplied no list of priced models: "not asked" is not the same as "none".

The Claude Code figure is an "API-equivalent estimated cost" — what those tokens would cost at Anthropic API list prices. If you are on a Claude Pro or Max subscription, your marginal cost per request is $0, and this number is not what you paid. It is useful for comparing workloads, not for reconciling a bill.

Reported and estimated costs are shown on separate lines and must not be added together.

Cache tokens are priced properly rather than lumped in with input:

• cache read bills at 0.1× the input rate on most models, 0.05× on Opus 5.5 and 0.025× on Fable 5.1 / Mythos 5.1
• cache write bills at 1.25× (5-minute TTL) or 2× (1-hour TTL)

The two cache-write TTLs are tracked separately because both occur heavily in practice — on the machine this was developed against, 18.0M of 27.2M cache-write tokens used the 1-hour TTL, so averaging the rates would have understated cost substantially.

Which models ship with prices

Pricing is versioned data (src/pricing/tables/), one file per provider, each keeping its own capture date:

They are composed into one table, reported by ai-usage status as builtin-<date> with every provider's provenance behind it. Two tables may not price the same model id — that raises an error at build time rather than silently applying one vendor's rates to another's tokens.

A Claude model released after that capture date is normally priced within a day anyway -- see the next section. Anything that neither covers has no estimate, and the reports say so explicitly rather than showing $0. Add it yourself with an override.

New models are priced automatically

A pricing table captured on one date cannot price a model released on the next, so every Claude Code turn on a new model used to report its cost as unavailable until a release caught up. Now the MCP server downloads LiteLLM's community price list in the background, at most once a day, and uses it for the Claude models the built-in table does not have yet:

• It only fills gaps. A model the built-in table prices keeps the built-in price; the community list never changes a number this package ships.

• It takes a model only if every rate is there -- input, output, cache read, both cache-write TTLs. A missing rate is not borrowed from a default, because newer models are exactly where the defaults go wrong (Opus 5.5 reads cache at 0.05×, not 0.1×). A model with a long-context price tier, which the table cannot express, is left unpriced.

• It is labelled. Estimates it contributes to cite a table version like builtin-2026-09-26+litellm-2026-10-02, and ai-usage status lists the models it priced:

  text

  Pricing table:  builtin-2026-09-26+litellm-2026-10-02  (Anthropic first-party ...; plus 1 model(s) ...)
    Community:     1 model(s) the built-in tables lack, from LiteLLM's price list fetched 2026-10-02: claude-opus-6
  

• Earlier turns are priced too. Records stored as unavailable before a price existed are priced as soon as one does -- from the community list, a release, or your own override -- on the next sync, with no sync --full needed. Only unavailable records change; a cost a client reported itself is never touched.

It is one plain GET of a public ~3 MB file, carrying no usage data and no identifier. The converted prices are cached in <config dir>/pricing-community.json; a failed download keeps the previous copy. The CLI's ai-usage sync refreshes it as well. Turn it off with AI_USAGE_NO_PRICING_REFRESH=1 (or AI_USAGE_NO_UPDATE_CHECK=1, which turns off both network requests); prices are then exactly the built-in tables plus your override. AI_USAGE_PRICING_URL points it at a mirror.

The OpenAI numbers are the Standard tier, short context rates. OpenAI also publishes long-context, Batch, Flex and Fast-mode rates, and nothing in a stored record says which applied — so a long-context turn is understated rather than guessed at. Providers whose published pricing this table cannot express exactly (DeepSeek, for instance, bills different rates at peak and off-peak hours) are deliberately not shipped; supply them yourself, with whichever rate is true for you.

Adding or correcting prices yourself

Drop a JSON file at:

~/.config/ai-usage-mcp/pricing.json      # or $AI_USAGE_PRICING_FILE

It is overlaid onto the built-in table, keyed by model id — so adding one model keeps every built-in price. (Before 0.8.0 it replaced the table wholesale, which meant the only way to add a missing provider was to lose every price you already had.)

{
  // Required. Names YOUR table; this is the string reports will cite.
  "version": "my-prices-2026-09-16",

  // Optional. Shown by `ai-usage status`, with the built-in provenance appended.
  "provenance": "DeepSeek off-peak list pricing, captured 2026-09-16",

  // Optional. The default cache rates for models that do not carry their own.
  // Omit to inherit the built-in defaults (read 0.1, write5m 1.25, write1h 2.0).
  "cacheMultipliers": { "read": 0.1, "write5m": 1.25, "write1h": 2.0 },

  // Required. Keyed by the model id EXACTLY as your client records it --
  // `ai-usage models` lists the ids actually present in your database.
  "models": {
    "deepseek-v4-pro": {
      "input": 0.66, // USD per 1,000,000 input tokens
      "output": 1.98, // USD per 1,000,000 output tokens

      // Optional: premium rates, applied when the source recorded `speed: "fast"`.
      // Only Claude Code records a speed at all.
      "fast": { "input": 1.32, "output": 3.96 },

      // Optional: cache rates for THIS model, when the provider's differ from the
      // table default. DeepSeek's cache-hit rate is 0.02x its input rate, not 0.1x.
      "cache": { "read": 0.0333, "write5m": 1.0, "write1h": 1.0 },
    },
  },
}

Units. input and output are USD per 1,000,000 tokens — the same unit every provider's pricing page publishes, so you can copy the number straight across. The three cache* values are multipliers of that model's input rate, not prices: read: 0.1 means a cache read costs a tenth of an input token. If your provider publishes an absolute cached-input price, divide it by the input price to get the multiplier.

What is required. version and models; within each model, input and output. Everything else is optional. currency and unit are ignored if present — USD per million tokens is the only supported combination, and accepting a value that does nothing would be worse than ignoring it.

Replacing rather than overlaying. Set "replace": true to discard the built-in table entirely. That form additionally requires cacheMultipliers.{read,write5m,write1h}, because there is no built-in default left to inherit.

An override entry replaces that model's price wholesale, not field by field: if the built-in entry has fast rates and yours does not, the model has no fast rates. A half-inherited price is a figure nobody could reason about.

A malformed override raises an error naming the offending field rather than silently falling back — quietly using different prices than you think are in effect would be worse than failing:

Pricing override at /home/you/.config/ai-usage-mcp/pricing.json is invalid:
models["deepseek-v4-pro"].output must be a number >= 0 (USD per 1,000,000 tokens).

For the same reason, an AI_USAGE_PRICING_FILE that points at a file which does not exist is an error, not a fallback to built-in prices — otherwise a typo in the path would look exactly like the override working. Only the default ~/.config/ai-usage-mcp/pricing.json may be absent, because not having one is the normal case.

ai-usage status always shows which table is in force, and whether it is built-in, an overlay, or a full replacement.

Why token counts here are trustworthy

Both source formats are internal and undocumented, and both contain traps that produce badly wrong numbers if taken at face value. What this tool does about them:

• Claude Code writes one line per content block, repeating the same usage object with a cumulative output_tokens. Summing those lines inflates every figure by 2.15×-3.05× depending on the token class (measured). Records are deduplicated on requestId + message.id, taking the maximum of each field.
• usage.iterations[] is already included in the top-level totals and is never summed.
• Subagent turns live in separate files (<session>/subagents/…), not behind the isSidechain flag — which is never set in practice. They are classified by path.
• <synthetic> is not a model and is excluded.
• OpenCode's session rollup columns can be stale. They are a cached aggregate; on the development machine they had lost 545,977 input tokens across 4 sessions. This tool reads the message grain instead, which is corroborated byte-for-byte by the independent part table.
• Reasoning tokens mean different things per client. In Claude Code, thinking tokens are inside output_tokens; in OpenCode, reasoning is a sibling of output. Totals are computed per client accordingly, so reasoning is never double-counted.
• Cache tokens dwarf everything else (800M cache-read vs 24K input is a real ratio), so token classes are always broken out and never presented as one blended total.

Run ai-usage verify to check this yourself. It re-reads both sources with a second, independent implementation that shares no reduction code with the collectors, and diffs the result against the database:

== opencode ==
  MATCH    opencode.db message grain (what we collect)
  MATCH    opencode.db part/step-finish grain (independent corroboration)
  INFO     opencode.db session rollup grain (what `opencode stats` headline shows)
           delta:  input -545,977 ...

== claude-code ==
  MATCH    claude JSONL, deduped by stop_reason line (independent rule)
  INFO     claude JSONL, naive sum of every usage line (NOT used — shows the double count)
           delta:  cache-read 990,824,820 ...

RESULT: every client reconciles exactly against at least one independent read of its source.

verify syncs first and compares only activity before a shared cutoff — both clients append to their stores while we read them, so without a cutoff the source always looks a few requests ahead.

It compares only sessions the source still holds. Both clients delete their own history -- Claude Code removes transcripts after cleanupPeriodDays, 30 days by default -- while the local database keeps what it collected, so after a month the database legitimately holds more than the source. Those sessions are listed on a separate Retained, not compared line instead of being counted as a mismatch. Any source record missing from the database still fails the check, because the source side is never narrowed.

Subagent turns

Included by default, because they are real spend. Every report says which way it went, and --no-subagents / includeSubagents: false excludes them. session_usage always shows the main/subagent split separately.

What stays on your machine

Everything. Your usage data never leaves the machine.

• No telemetry, no analytics, no crash reporting, no phone-home.
• No cloud sync, no accounts, no API keys — the tool never calls an LLM API.
• Two outbound requests exist, both plain GETs of public files that send no usage data and no identifiers, both at most once a day, and both disabled by AI_USAGE_NO_UPDATE_CHECK=1:
  • the update check asks the npm registry for the latest published version number (ai-usage status, and the MCP server in the background after its handshake);
  • the price refresh downloads LiteLLM's public price list, so models released after the built-in table are priced (ai-usage sync, and the MCP server in the background after its handshake). AI_USAGE_NO_PRICING_REFRESH=1 turns off just this one.
• No conversation content is read into the database. The collectors extract token counts, model ids, timestamps, session ids and project paths. Prompts, completions, tool inputs and file contents are skipped.
• Source data is opened read-only. A running OpenCode is never disturbed: the collector opens its database with a read-only connection, and falls back to a temporary snapshot copy (.db + -wal + -shm) only if that fails.
• Everything is stored in one local SQLite file:

~/.local/share/ai-usage-mcp/usage.db          # override with AI_USAGE_DB

Delete that file to erase everything the tool knows.

Note: the database path deliberately ignores XDG_DATA_HOME. A sandboxed launcher (the VSCode snap, for example) exports its own XDG_DATA_HOME, which is exactly how OpenCode's history ended up split across two databases on the development machine. The MCP server and the CLI must always agree on one file.

Troubleshooting

ai-usage status says a collector is unavailable

It prints the reason and every path it looked at. Point it at the right place:

Numbers look lower than opencode stats

Expected, and opencode stats is the one that's off. Its headline block reads OpenCode's session rollup columns, which can be stale, while its own per-model block reads message grain. The two halves of its output do not agree with each other. This tool matches the message grain — the number corroborated by two independent tables. Run ai-usage verify to see all three grains side by side.

ai-usage status reports additional stores

You have more than one OpenCode database — usually because a sandboxed launcher exports its own XDG_DATA_HOME. Only the store OpenCode itself resolves is collected by default. Each extra store may be genuinely separate history or just a stale copy. Records are keyed by source record id, so merging is safe:

ai-usage sync --all-stores

Claude Code cost seems enormous

Read it as API-equivalent list price, not as money you spent — see the cost section above. On a Pro/Max subscription the marginal cost per request is $0.

claude: command not found

You do not need the CLI. Claude Code's extensions read the same configuration files, so you can register the server by creating .mcp.json in your project root, or by adding an mcpServers block to ~/.claude.json — see the collapsed section under Install. If you do want the CLI, npm install -g @anthropic-ai/claude-code provides it.

/mcp shows ai-usage as failed

The server is spawned by Claude Code, so it has to be resolvable from the environment Claude Code runs in. npx -y ai-usage-mcp is the most portable form and is what the instructions above use.

If it still fails, your editor was probably launched without your shell's PATH (common with Snap or Flatpak builds on Linux, and with launching from a desktop icon on macOS). Point the config at absolute paths to bypass PATH lookup entirely:

{
  "mcpServers": {
    "ai-usage": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/lib/node_modules/ai-usage-mcp/dist/mcp/server.js"]
    }
  }
}

Get both paths with command -v node and npm root -g after npm install -g ai-usage-mcp. This pins the Node version, so prefer the npx form unless you need it.

node-gyp rebuild errors during install

On Node 22.13+ this no longer fails the install. better-sqlite3 is an optional dependency, so npm reports the build failure and carries on; storage falls back to Node's built-in node:sqlite. Confirm with:

ai-usage status        # expect: SQLite driver: node:sqlite

If that line instead reads better-sqlite3, your Node is older than 22.13.0 and the native module is genuinely required — upgrade Node, which is the simplest fix. Historically this bit Windows on npm 10, which ignores better-sqlite3's gypfile: false flag and compiles from source even though a usable prebuilt binary is bundled; npm install -g npm@11 fixed that, and remains the fix if you are pinned to an older Node and need the fallback to build.

A model shows cost as unavailable, or "no estimate attempted"

That model is not in the pricing table. A new Claude model is normally picked up within a day from the community price list -- the Community: line of ai-usage status says whether it is on, when the list was last downloaded, and what it priced. If it is off, or the list does not have the model yet, add it via a pricing override file. Either way, records already stored are priced on the next sync. The tool will not guess a price.

ai-usage models --json lists the model ids exactly as your clients recorded them, which are the keys your override file needs.

Totals changed after re-syncing

They should not. Records are keyed deterministically by source identifiers and upserted, so re-syncing is idempotent — ai-usage sync --full re-reads everything and must leave totals unchanged. A test asserts this. If it happens, please file an issue with ai-usage verify output.

Sync feels slow

Only the first sync reads everything (~2.5s for 87MB of transcripts plus a 900MB database on the development machine). After that, unchanged transcripts are skipped by size + mtime and OpenCode is read incrementally from a saved cursor. --full ignores the cursors.

Development

npm install
npm run check          # typecheck, lint, format check, build, tests -- what CI runs

Individually:

npm run typecheck      # tsc, covering src and tests
npm run lint           # eslint (type-aware)
npm run format         # prettier --write
npm run build          # emit dist/
npm test               # 81 tests: collectors, services, formatter, MCP integration, parity
npm run test:coverage  # with coverage report

Architecture — the one rule that matters is that MCP never knows where data comes from:

MCP tools ─┐
           ├─> UsageService ─> collectors ─> Claude Code JSONL / OpenCode SQLite
debug CLI ─┘        │
                    └─> local SQLite

Business logic lives in src/services/. The MCP handlers and the CLI commands are both thin frontends over UsageService, and they render through the same formatter.

See docs/DATA_SOURCES.md for the verified on-disk formats of both sources, including everything that had to be corrected by inspecting real data, and docs/PUBLISHING.md for the release process.

Contributing

Issues and pull requests are welcome. Two expectations specific to this project:

1. Never fabricate a number. If a source does not record something, it must surface as unavailable, not as zero.
2. If your change touches a collector, ai-usage verify must still report a zero delta, and if it changes how an on-disk format is understood, update docs/DATA_SOURCES.md in the same change. Both source formats are internal and unversioned, so that file is the only record of what was actually observed.

npm run check runs everything CI runs.

Links

• CHANGELOG.md — release history
• docs/DATA_SOURCES.md — verified on-disk formats, and the documented assumptions that proved wrong
• docs/PUBLISHING.md — release process
• SECURITY.md — threat model and how to report a vulnerability

License

MIT — see LICENSE.