open source · single file · stdlib-only python · no API keys

Track your tokens, feature by feature.

Make sure you track your Return On Token Spend (ROTS).
# every branch. every agent. every machine. posted on the PR.

~/anywhere — zsh

$ pipx install tokenchecker # or: uv tool install tokenchecker $ tokenchecker install --global # done. every repo on this machine now reports token usage on push.

● LIVE incoming pull requests — token usage attached

github.com/acme/voicebox — pull requests ⛁ ROTS MONITOR

#482

⊙ Open @sana-dev wants to merge feature/streaming-tts +1,204 −87

🤖 tokencheckerBOT commented just now

🤖 AI token usage for `feature/streaming-tts`

Tool	Model	Sessions	Msgs	Input	Cache read	Cache write	Output	Total	Est. cost

ROTS

how it works

No database. No SaaS.
Just git refs.

Your agents already log every token to disk. tokenchecker parses those logs, dedupes them, and publishes per-machine totals to custom git refs on origin — then a hook or Action renders the table on the PR.

 your laptop                          origin (GitHub)                 PR
┌──────────────────────┐             ┌───────────────────────┐
│ claude / codex /     │  git push   │ refs/token-usage/     │   GitHub Action:
│ gemini / cursor logs │ ──────────► │   laptop-a1b2c3d4     │   fetch refs/token-usage/*
│         │            │ (pre-push   │   desktop-e5f6a7b8    │   aggregate head branch
│         ▼            │  hook runs  │   coworker-c9d0e1f2   │   upsert PR comment
│ tokenchecker sync    │  `sync`)    └───────────────────────┘
└──────────────────────┘

collect

Scans local logs of all four agents, keeps records matching the current repo, and normalizes them into dedupable records under .git/tokenchecker/.

push

Publishes to refs/token-usage/<machine-id> on origin. One ref per machine — zero conflicts, zero external storage, never double-counts.

hook

A pre-push hook runs sync automatically, so usage data lands on origin together with the branch you're pushing. No CI or repo files required.

comment

The hook (via gh) or the optional tokenchecker@v0 Action upserts a sticky PR comment with per-tool, per-model totals and estimated cost.

supported agents

Reads the logs your agents already write.

Parsed straight from local session files — no API keys needed. Branch attribution is exact where recorded, and reconstructed from your HEAD reflog where it isn't.

Claude Code

~/.claude/projects/<project>/*.jsonl

Per-message usage blocks. Branch attribution: exact — gitBranch recorded per message.

Codex CLI

~/.codex/sessions/Y/M/D/*.jsonl

token_count events. Branch attribution: recorded in session metadata.

Gemini CLI

~/.gemini/tmp/<sha256(cwd)>/chats/

Per-message tokens. Branch attribution: inferred from HEAD reflog at message time.

Cursor

state.vscdb (bubble records)

Per-message tokenCount. Branch attribution: inferred from HEAD reflog at message time.

design goals

Paranoid about correctness.

Never double-counts

Every record has a stable id (message / session / bubble). Streaming snapshots, re-collection, and multi-machine overlap all collapse to the max-total record. Idempotent by construction.

Real cost estimates

Four token buckets priced at each model's API list rates — cache reads counted separately from fresh input (they're billed differently and dominate agent usage). Prices via LiteLLM's community table, a pinned file, or an embedded fallback — every report says which.

Whole team, every machine

Each machine owns one ref: refs/token-usage/<machine-id>. Laptop, desktop, coworkers — all aggregate into a single PR comment with a per-machine breakdown.

Zero infrastructure

Single-file, stdlib-only Python 3.9+. Storage is plain git refs on origin. Cleanup is git push origin --delete refs/token-usage/<id>. Nothing else is stored anywhere.

commands

Five verbs. That's the whole tool.

tokenchecker --help

$ tokenchecker sync# collect + publish (what the hook runs)

$ tokenchecker collect --dry-run# preview per-branch usage, write nothing

$ tokenchecker status# when did it last run, what's synced where

$ tokenchecker report# all branches, all machines, with costs

$ tokenchecker report --branch feature/x --markdown# PR-comment format

$ tokenchecker comment# post/update the PR comment for this branch

deploy

Know what every feature
actually cost.

Two commands. Every repo on your machine. Forever.

STAR ON GITHUB