TokenTab
Live demo → — 100% synthetic data, no store behind it.
What AI actually costs — across providers, projects and machines, with the
flat-rate plans included rather than excluded.
Every usage dashboard you can buy meters API keys. Almost nobody pays for coding
agents that way any more: the spend is a handful of $20–$200 subscriptions, and
a subscription has no per-call price to meter. TokenTab reads the transcripts
the CLIs already write to disk, prices the usage at published list rates, and
splits each flat fee across the projects that consumed it.
No vendor API key. No proxy in front of your agent. No credentials stored.
The three numbers
| Number | Meaning |
|---|
| Cash out | The plan fees you told it about, for the period, added up |
| Allocated cost | A plan's fee split across projects by token share — accounting, not measurement |
| Value | The same usage priced at published API list rates, for subscription and local traffic alike |
A flat plan has no per-call price, so any per-project figure for it is
allocated. The dashboard never presents an allocated number as cash: apply a
project (or repo/model/machine/source) filter and the Cash out card switches to
the allocated figure, turns amber, goes dashed and carries an ALLOCATED badge.
Allocation basis: total tokens (input + output + cache read + cache writes of both durations) per
project, per billing cycle. Billing periods are plan cycles (cycle_day →
same day next month), not calendar months, and fees are never pro-rated.
Accounts
One vendor can bill you several times over — a plan per login. A subscription
is therefore a plan family × account pair, and those pairs are discovered from
the data, not enumerated in config: sign into a new account and its subscription
appears by itself; cancel one and it stops charging. plans.json → plans holds
the family template, accounts holds optional per-account overrides (label,
monthly_usd, cycle_day, active_from, active_to). An account with no entry
bills at its family's default fee and says so in the UI.
Transcripts carry no account identity, so the account is read from each CLI's own
config at scan time — ~/.claude.json → oauthAccount.emailAddress, and the
email claim of the Codex id_token. The token itself is never read further,
stored or logged. A host that switches accounts stamps only what it scans
afterwards; history keeps the account it was scanned under.
Filtering by account keeps Cash out a cash figure — an account's own plan fee is
that account's fee, undivided. Only project/repo/model/machine/source narrowing
switches the card to allocated.
Cancelled on an unknown date: set "active_to": "auto" and the end is inferred
from that account's last usage, displayed with a trailing ? so an inference is
never mistaken for an invoice.
Events that predate account tracking are stamped by tokentab adopt: each
host × source with exactly one known account adopts its orphans, anything
ambiguous is reported and left alone. Without it those rows bill as a phantom
account-less subscription — tokentab verify fails if any remain.
Why not a gateway
Claude Code (Max) and Codex CLI (ChatGPT plan) authenticate by OAuth straight to
their vendor. Repointing them at LiteLLM or any other proxy breaks that auth, and
passing subscription OAuth through third-party infrastructure is a ToS grey zone.
Usage is therefore read from the local transcripts each CLI already writes, and
the cost side is the flat fee. No vendor API key, no network interception, nothing
to keep credentials for.
Sources
| Source | Path | Notes |
|---|
claude_code | ~/.claude/projects/<encoded-cwd>/<session>.jsonl | full usage blocks incl. cache + thinking tokens |
codex | ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl | token_count events; last_token_usage is the per-turn delta |
llama_swap | ~/.config/llama-swap/swap.log | llama.cpp timing lines; see limits below |
A subscription CLI pointed at a local endpoint is reclassified
provider=local, billing=local — that traffic is free and must not consume the
plan's allocation. The model name, not the source, decides billing.
Attribution
By path position, from the session's working directory — no git or filesystem
lookup, so history still resolves after a directory is deleted:
<root>/<project>/<repo>/… -> (project, repo)
<root>/<project> -> (project, project)
<root>/<project>/worktrees/<repo>--<branch>/… -> (project, repo)
anything outside the configured roots -> ('ad-hoc', <basename>)
Roots live in plans.json → roots.paths.
Topology
One host collects; the others push to it over SSH.
laptop ─ launchd com.42labs.tokentab-collect (hourly) ─┐
worksta ─ systemd --user tokentab-collect.timer ────────┼─► ssh ─► server tokentab ingest
server ─ systemd --user tokentab-collect.timer ────────┘ └─► SQLite
tokentab-serve ─► :8899
This is the beginning of the README. Read the rest at the original. Read the full README ↗
