TokenFlow turns local logs from Claude Code, Codex, Cursor, Cline, and Hermes into honest token and cost analytics -12 dashboard views, a native macOS menu bar app, forecasts, and anomaly alerts. Zero dependencies; nothing leaves your machine. Nothing leaves your machine.
Hey PH! I'm Vimox - I build AI products by day and burn an embarrassing amount
of tokens doing it.
TokenFlow started as a weekend question: which of my agents was actually eating
my budget? Every tool I use - Claude Code, Codex, Cursor, Cline, OpenCode —
writes its own logs in its own format, and none of them agree on what a cached
token even is. So I built the thing I wanted: one local engine that reads all
of those logs, normalizes them properly (cache read/write/input as separate,
mutually exclusive buckets; streaming re-reports collapsed; null never coerced
to zero), versions its price table with cited sources, and shows the result in
a dashboard plus a native macOS menu bar app with forecasts and anomaly alerts.
Three principles I refused to compromise on:
- Nothing leaves your machine. No accounts, no API keys, no telemetry.
- Zero runtime dependencies. If it can't be audited, it doesn't ship.
- Unpriced models show as "unknown" with a fix-it action - never a silent $0.
It's MIT, free, and installs in one line:
brew install --cask tokenflow (or npm i -g @vimoxshah/tokenflow)
Today's version has 12 dashboard views, 10 log adapters, and 145 tests running
on macOS/Linux/Windows across Node 22/24. What would make it genuinely useful
for you? I'll be in the comments all day - Windows tray app and a team-rollup
mode are already on my list depending on what you ask for.
Just under two weeks after launch, 1.2.0 is out. Most of it came from one question you asked in different ways: which branch, which PR, which session is burning the budget, and can I catch it while it is still running?
What is new:
- Receipts. Every push can now carry a spend receipt: what the branch cost in AI tokens, how many sessions and turns it took, how it ranks against the repo's median. It travels as a git note, and a GitHub Action posts it as one
comment on the PR. Reviewers see the cost next to the diff.
- Guard. A per-repo policy file sets caps. The Live view and the menu bar show the sessions running right now, today's receipts and the last guard verdict, so a runaway session is visible while it is still running.
- Team ledger. A team server you host yourself. Each machine pushes its rollup, the server joins them, the dashboard reads the result. Still no cloud, still no account, still no telemetry.
- Twenty dashboard views, up from twelve at launch. Six are new: Session anatomy, Cache health, What-if pricing, Rhythm, Compare branches and Annotations. Live was rebuilt around running sessions. Press Cmd+K for a
command palette.
- Capture fixes. Codex sessions now carry their branch. Git worktrees no longer count twice. A new OpenTelemetry adapter reads GenAI spans, including Gemini CLI.
- A design system with a compiler. One token file compiles into the dashboard, the landing page and the Swift menu bar, and fails closed when a contrast gate breaks. Honest notes. Receipts leave your machine only as git notes to your own remote,and only if you install the hook. The team server is yours to run. The Codex guard warns and cannot block, because Codex has no blocking hook yet. Same three principles as day one: nothing leaves your machine, zero runtime
dependencies, and an unpriced model shows as unknown, never as $0. 520 tests run on macOS, Linux and Windows across Node 22 and 24.
Clockwork
Clockwork
Hey PH Folks, Vimox here.
Just under two weeks after launch, 1.2.0 is out. Most of it came from one question you asked in different ways: which branch, which PR, which session is burning the budget, and can I catch it while it is still running?
What is new:
- Receipts. Every push can now carry a spend receipt: what the branch cost in AI tokens, how many sessions and turns it took, how it ranks against the repo's median. It travels as a git note, and a GitHub Action posts it as one
comment on the PR. Reviewers see the cost next to the diff.
- Guard. A per-repo policy file sets caps. The Live view and the menu bar show the sessions running right now, today's receipts and the last guard verdict, so a runaway session is visible while it is still running.
- Team ledger. A team server you host yourself. Each machine pushes its rollup, the server joins them, the dashboard reads the result. Still no cloud, still no account, still no telemetry.
- Twenty dashboard views, up from twelve at launch. Six are new: Session anatomy, Cache health, What-if pricing, Rhythm, Compare branches and Annotations. Live was rebuilt around running sessions. Press Cmd+K for a
command palette.
- Capture fixes. Codex sessions now carry their branch. Git worktrees no longer count twice. A new OpenTelemetry adapter reads GenAI spans, including Gemini CLI.
- A design system with a compiler. One token file compiles into the dashboard, the landing page and the Swift menu bar, and fails closed when a contrast gate breaks. Honest notes. Receipts leave your machine only as git notes to your own remote,and only if you install the hook. The team server is yours to run. The Codex guard warns and cannot block, because Codex has no blocking hook yet. Same three principles as day one: nothing leaves your machine, zero runtime
dependencies, and an unpriced model shows as unknown, never as $0. 520 tests run on macOS, Linux and Windows across Node 22 and 24.
Get it:
What would make the receipt useful on your team's PRs? I am reading every
reply.
Clockwork
Hey PH, Vimox here.
Short update with one concrete thing in it.
The budget check that comments on a pull request is now installable from the GitHub Marketplace.
It reads the receipt a push already attached to the commit as a git note, then posts or edits ONE comment on the PR — never a stack of them.
Set a cap in your workflow or in a committed .tokenflow/policy.yaml:
Go over budget → the job fails → the status check can be required by branch protection before merging.
What landed since 1.2.0:
Cost per ticket. Branches using the same Jira, Linear, or GitHub key are aggregated across repositories. No key means unattributed — we don't guess.
An MCP server with four read-only tools, so the agent spending the money can read its own bill.
A FOCUS-shaped export, making the estimates easier to place alongside real cloud billing data.
Org policy that acts as a ceiling: it can lower an effective cap, never raise it.
21 dashboard views moved into a sidebar, with one filter bar replacing the 18 controls that previously sat above every view.
A few honest notes:
A missing receipt is never a blocker. If no hook is installed, the Action logs one line and exits 0.
The self-hosted GitHub App ships and is documented, but you run it yourself, and I haven't exercised it end-to-end against a live App yet.
The Codex guard warns but cannot block because Codex doesn't provide a blocking hook.
Cost figures are estimates at list price from one developer's logs, not invoices.
npm is still on 1.3.2; this release changed the Action metadata and docs only.
Still zero runtime dependencies - Tokenflow adds exactly one package: its own.
And if you just want to poke around, the browser demo uses synthetic data. Nothing to install:
https://vimoxshah.github.io/tokenflow/demo/