Claude Code, Codex and Cursor all write a transcript of every session to your disk, and every one of those transcripts records exactly what was billed. tokentax reads them and tells you the number nobody shows you: what you spent, where it went, and which prompt was the expensive one.

It runs entirely on your machine. There is no account, no API key, no telemetry and no network code in this repository at all.

$ npx tokentax

  tokentax  2026-06-22 → 2026-08-20
  ────────────────────────────────────────────────────────────────

  $327 spent
  2,267 API calls · 89 sessions · 37 active days · 239.6M tokens

  per day               $8.84       per session           $3.67
  cache saved you       $1,156      without cache         $1,483
  spent by subagents    $38.11      12% of the bill

  Daily spend
  ▁▁▁▃▃▄▁▂▁▁▄▁▅▂▅▁▁▅▇▃▂▇▁▁▃▃▅▂▃▁▁▅▄▇▇▁▁▁▁▂▅▂▅▁▁▄▁▁▅▃▁▁▅▁█▄
  06-26                                             08-20
  worst day: 2026-08-19 at $20.21

  Where it went
  data-pipeline                 $186  ████████████··········  57%  742 calls
  checkout-service              $108  ███████···············  33%  898 calls
  marketing-site              $27.47  ██····················   8%  391 calls
  mobile-app                   $5.58  ······················   2%  236 calls

  Most expensive sessions
             $13.73  data-pipeline · 45 calls · 1.1h
                   "the nightly dbt run has been failing since Tuesday, find out w"

Try it with no data of your own

The repository ships a generated sample project tree, so you can see real output on a clean machine before you point it at anything private:

npx tokentax --demo

That is also what the GIF above records, via the committed demo.tape — so the demo is reproducible rather than a screenshot of somebody's good day.

Install

npx tokentax                 # no install
npm i -g tokentax            # or keep it around

Docker

docker run --rm -v ~/.claude:/root/.claude:ro mohitagw15856/tokentax

Or with compose, if you want the ledger to persist:

docker compose up

The three things it makes

| Command | What you get | |---|---| | tokentax | the terminal summary above | | tokentax --html | a self-contained dashboard — one file, no JavaScript, no remote requests | | tokentax --card | an SVG receipt sized for posting |

Your history is being deleted right now

Claude Code prunes old transcripts. While building this tool the count on the author's machine went from 128 files to 25 in a single afternoon — two months of spend, gone, unrecoverably.

So tokentax keeps its own append-only ledger of daily totals:

tokentax snapshot            # fold today's transcripts into ~/.tokentax/ledger.json

Snapshotting is idempotent, so running it twice a day costs you nothing and running it on a cron means your history outlives the transcripts it came from:

# crontab -e
0 * * * * npx tokentax snapshot

Reports merge the two automatically: live transcripts win for any day they still cover, and the ledger fills the gaps.

Import from ccusage

Already been running ccusage? Keep the history:

ccusage daily --json > ccusage.json
tokentax --import ccusage.json snapshot

Options

--since <30d|3m|2026-01-01|all>   default: 30d
--until <date>
--project <substring>             only projects whose name contains this
--source <claude-code|codex>      one agent only
--top <n>                         rows per table (default 10)
--no-subagents                    exclude sidechain/subagent traffic
--no-ledger                       ignore saved history, read transcripts only
--import <ccusage.json>           fold in ccusage output
--price <in,out>                  override $/MTok, for negotiated rates
--demo                            run against the bundled sample data

How the numbers are worked out

Every assistant message that hit the API carries a usage block. That block — not an estimate, not a tokenizer approximation — is what gets priced:

| Bucket | Multiplier | |---|---| | fresh input | 1× input rate | | 5-minute cache write | 1.25× input rate | | 1-hour cache write | 2× input rate | | cache read | 0.1× input rate | | output | output rate |

Model prices are matched by longest prefix, so claude-opus-4-1-20250805 is priced as Opus 4.1 rather than falling through to a generic default. Unknown models fall back to a Sonnet-ish rate and are labelled as such.

A few honest caveats:

• These are list prices. If you are on a subscription plan, this is what your usage would have cost on the API — which is exactly the number you want when deciding whether the subscription is worth it.
• Transcripts written by a session that is still running are read as-is; the current session's last few calls may not have landed on disk yet.
• Codex reports cumulative counters per session, so tokentax differences them. If a rollout file is truncated, that session under-reports rather than over-reports.

What it is not

This is a spend dashboard. If you want to know why a session was expensive — which tool calls bloated the context, which files got re-read, where the cache broke — that is a profiler's job, and the author wrote one of those too: drainspotting.

Contributing

New source adapters are the most useful contribution. A source is one file in src/sources/ that exports collect() returning turn records; see src/sources/codex.mjs for the shortest complete example.

npm test

MIT. Fork it, rename it, ship it.