v1.0 · local-first · MIT · zero dependencies

Know where every AI token goes.

TokenFlow reads the logs your tools already write and turns them into honest analytics across Claude Code, Codex, OpenCode, Cursor and more. Zero dependencies. Nothing leaves your machine.

Download for macOS Try the live demo Explore features

145 tests on every push · macOS, Linux, Windows · no API keys, no telemetry

Features

Everything a token dashboard should do. And the parts most skip.

12+

Analytics views

Daily series, composition, provider and model intelligence, interfaces, hour and weekday patterns, calendar heatmap, peaks, efficiency ratios and more.

$ est + $ real

Honest cost

Estimated cost from a versioned price table with sources printed, cross-checked against measured gateway costs where they exist.

5h

Session blocks

Claude and Codex style five hour session windows modelled from your activity, with reset countdowns right in the menu bar.

TokenFlow menu bar popover — light TokenFlow menu bar popover — dark
The native macOS popover — by provider, by source (Claude Code, OpenCode, Hermes…), by model — plus an appearance toggle.

ETA

Limits and forecasts

Declare caps in config and get capacity meters, burn rates, exhaustion ETAs, linear forecasts with stated confidence, and anomaly alerts with arithmetic shown.

r = ?

Work correlations

Pearson correlation between token spend and git activity, labelled as correlation with n stated, never dressed up as productivity.

1 file

Offline export

The whole dashboard inlines into one HTML file: CSS, chart code and data. Opens from disk forever, no server needed.

Δ compare

Period compare

Diff any two time windows metric by metric, plus first-seen models, streaks and milestone tracking.

3 skins

Aurora · Terminal · Editorial

Each in dark and light, colour-blind validated per mode so switching themes never changes what a colour means.

Under the hood

How deep does it go?

Every layer is built for honesty: adapters that only read, accounting that never double counts, prices with receipts, and tests that enforce all of it.

TokenFlow architecture: local logs → engine → dashboard, menu bar, CLI

10

Adapters

Anthropic, Codex, OpenCode, Hermes, Cline, Cursor, gateway overlays, git, generic CSV/JSONL/SQLite import — incremental and resumable at the byte offset.

145

Tests + lint invariants

Cache-bucket exclusivity, stream dedup, null-vs-zero semantics and pricing rules are asserted on every push across three OSes.

12

Analytics views

KPIs, composition, provider/model intelligence, time patterns, peaks, efficiency, cost with coverage, correlations, compare, explorer, data health.

3

Surfaces

A loopback web dashboard, a native Swift menu bar app with capacity forecasting, and a scriptable CLI — all reading the same pre-aggregated cube.

Why TokenFlow

Built for correctness first. That is the whole point.

Most token dashboards sum whatever they find. On real data that inflates usage by orders of magnitude. TokenFlow was built backwards from the mistakes, and every fix is enforced by tests.

45×

Streaming done right

Streaming logs re-report growing usage. Summing them read one real day as 82.8B tokens instead of 1.8B. TokenFlow collapses each monotonic run to its maximum, verified against an independent gateway billing log.

4 ≠ ∞

Tokens that add up

Fresh input, cache read, cache write and output are mutually exclusive buckets summing to the total. Cache refresh and reasoning are subsets, never added twice. Vendors disagree about input; both conventions are handled.

null ≠ 0

Missing is not zero

A source that does not report a field stores null, not zero. Sums skip nulls and carry a not-available counter, so averages are never dragged down by data that does not exist.

0 deps

Auditable by design

No runtime dependencies, no network client anywhere in the codebase, server bound to loopback only. One grep proves it. Your raw logs never leave the machine.

Global activity

The shape of your AI activity.

Local logs contain no request IPs, so TokenFlow never invents geography. The map places each provider you actually used on its vendor-published datacenter regions — and shows your own location only if you explicitly opt in with map.showMyLocation. Nothing is captured per request; nothing is published.

Your AI usage tells a story. TokenFlow reads it honestly.

How it works

Three commands, no configuration.

1

Detect what you already have

npm run setup asks each adapter to find its own logs in conventional locations. Nothing is discovered by scanning your disk.

2

Ingest incrementally

tokenflow refresh resumes each file at a byte offset. Unchanged files are skipped entirely, so the second run takes seconds.

3

Open the dashboard

npm start serves everything at loopback:7799, or exports one self-contained HTML file that opens anywhere, offline forever.

Install

Up and running in under a minute.

⌘

macOS menu-bar app (Homebrew)

brew tap vimoxshah/tap https://github.com/vimoxshah/tokenflow
brew install --cask tokenflow

›_

CLI + dashboard, any platform (npm)

npx @vimoxshah/tokenflow@latest setup

↓

Or grab the DMG

Download from the latest release.

Intelligence

It doesn't just count. It tells you things.

Weekly digest

Your AI week — requests, tokens, cost, peak day, week-over-week spikes — generated on a launchd schedule and delivered to your Telegram, inbox, or webhook. Opt-in per channel; always archived locally.

Budget alerts

Set a monthly cap once. TokenFlow projects month-end spend from your real velocity and warns you before you cross it — approaching, projected-over, and actual-over states, each alerting exactly once.

Model comparison

Which model actually costs you what? Cost per request, tokens per request, cache-hit rate — computed from your own transcripts, never vendor marketing.

Prompt analytics

Strictly opt-in. Prompts become one-way hashes grouped into categories — code review, debugging, docs — so you see where the money goes without ever storing what you typed.

Multi-machine sync

Laptop plus desktop? Sync daily totals through any folder you already share (iCloud, Dropbox, Syncthing). Daily numbers only — never prompts or code. Off by default.

Team view

Per-developer usage from the same shared folder — but a name shows up only if that developer chose to publish it (sync.developerName). Anonymous machines stay in team totals, out of per-person rows. Opt-in per person, by design.

Diagnostics

tokenflow diagnostics shows version, providers, data freshness, and every feature state locally. Nothing is transmitted; sharing an export is always your call.

Sources

It speaks to what you already use.

Claude Code / Agent SDK~/.claude*/projects/** full per-request tokens including long TTL cache writes
Codex CLI / IDE / Desktop~/.codex/sessions/** per-turn tokens, OpenAI inclusive input handled correctly
OpenCodeopencode.db per-request tokens plus gateway routing
Hermes~/.hermes/state.db per session per model tokens and measured cost
Clinesessions dir activity only; missing token counts stay missing, never zero
Cursorai-code-tracking.db AI authored edits with per commit attribution
Gatewayse.g. Headroom JSONL measured cost as overlay records, excluded from token totals
Anything elseCSV · JSONL · SQLite a saved field mapping, no adapter needed

Questions

Fair questions, straight answers.

Is my data sent anywhere?

No. There is no HTTP client in the codebase at all. Adapters read token counts and metadata and discard prompt text, source code and file contents. Everything lives in ~/.tokenflow which you can back up or delete.

Why does macOS warn on first launch?

The app is unsigned because there is no Apple Developer account behind this free project. Right click the app, choose Open, then Open again. That gate appears once only.

Does the menu bar app need the terminal?

No. The DMG build embeds everything it needs and can drive refresh, watcher and dashboard itself. The CLI path exists for people who prefer it and for Linux and Windows.

What about tools that report no tokens?

Sources like Cline get activity metrics only. Missing token fields stay null rather than zero, so averages are never dragged toward zero by data that does not exist.

Can I trust the cost estimates?

Every built-in rate records its source URL and fetch date. Service tiers are applied as multipliers per request. Models without a published rate show blank with a reason.

Point it at your logs. Know your numbers.

Free and open source under MIT. Your tokens never leave your machine.

Download for macOS Try the live demo Read the docs