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.
Your AI coding agents bill you monthly and tell you nothing. TokenFlow reads the logs Claude Code, Codex, Cursor and Cline write on your machine, prices every branch, and posts the cost on the pull request as a comment plus a status check โ so a change over its declared budget fails before it merges. A guard hook brakes a session while it is still running, and an MCP server hands the same numbers to the agent spending the money. Local-first, zero dependencies, MIT. Nothing leaves your machine.
Hey PH, Vimox here ๐
My own landing page once said a 102-line bug fix cost $2,499 in AI tokens.
It cost $16.
The other $2,483 came from the same branch over the next six days โ a stale checkout that kept the branch name after the PR had already merged.
No console showed me the difference.
Mine didn't either.
So I published the wrong number.
That mistake became rule #2 of TokenFlow:
A pull request owns the AI turns up to its merge โ and nothing after it.
It also convinced me that I didn't need another AI cost dashboard.
I needed cost controls closer to where the code is actually being written.
### What TokenFlow does
Every push attaches a cost receipt to the commit as a Git note.
A GitHub Action turns that into a PR comment + status check, so a change that exceeds its declared budget can fail before merge:
```yaml
- uses: vimoxshah/tokenflow@v1.3.5
with:
max-usd: '50'
```
Thereโs also:
โ A guard hook that prices the live agent session and warns or blocks when it hits your cap.
โ MCP support so the agent itself can see what it has spent while working.
โ Ticket-level costs that connect branches referencing the same Jira, Linear, or GitHub issue.
โ FOCUS-shaped exports that let you put estimated AI spend next to your actual cloud bill.
### What 9 weeks of my own agent logs taught me
I analyzed $26.7K of estimated agent spend:
* 86% went to re-sending context rather than fresh work.
* 93% of spend came from the top 1% of sessions.
* The median session cost just $0.02.
* After roughly turn 50, a turn became ~15ร more expensive.
That last number matters.
That's where the brake belongs.
One developer. Nine weeks. Estimated using published list prices.
You can reproduce the analysis on your own logs:
```bash
tokenflow receipt --sessions
```
### A few things I'm deliberately being honest about
TokenFlow is about honest numbers, so:
* Costs are estimates at published list prices, not invoices. Unpriced models show as `unknown`, never `$0`.
* Missing receipts never block your workflow. If no hook is installed, the Action logs one line and exits 0.
* The self-hosted GitHub App ships and is documented, but I haven't personally exercised it end-to-end against a live App yet.
* The Codex guard can warn but cannot block because Codex doesn't expose a blocking hook.
* The macOS app is unsigned because I don't have an Apple Developer account. First launch requires Open Anyway.
Free. MIT licensed. Zero runtime dependencies.
`npm install @vimoxshah/tokenflow` adds exactly one package: itself.
841 tests. Green on macOS, Linux, and Windows across Node 22 and 24.
```bash
brew tap vimoxshah/tap https://github.com/vimoxshah/tok...
brew install --cask tokenflow
npx @vimoxshah/tokenflow@latest setup
```
Want to try it without installing anything?
Run TokenFlow in the browser with synthetic data:
https://vimoxshah.github.io/toke...
I'll be in the comments all day.
What would make AI cost control genuinely useful in your workflow?
Clockwork