TokenLedger

# TokenLedger

A desktop app (Tauri v2) for macOS, Windows, and Linux that tracks token usage
and estimated cost across the AI coding agents and assistants on your machine —
**Claude Code**, **Codex CLI**, **Gemini CLI**, **Hermes**, **Grok Build**,
**Google Antigravity**, **Goose**, **OpenCode**, **Cline**, **Kilo**, **Zed**, **pi**, **WorkBuddy**, and **CodeBuddy** — by parsing each tool's local logs into a
normalized SQLite ledger.

**Status: 0.3.0.** Driven daily on macOS. Windows and Linux build and pass the
full test suite in CI (run on demand), but have had no real-world use yet —
expect rough edges there, and please report them.

![TokenLedger's Overview](docs/screenshot.png)

## What it does

- **Zero-effort tracking** — reads local logs automatically, no manual entry
  and no API keys. Scans on launch and on a configurable timer (off / 10s /
  30s / 60s / 5m, default 30s, or any whole number of seconds from 5s to 24h).
  Off stops only this window's own re-reads — background capture carries on,
  and Rescan still works.
- **Per-request token detail** — input, output, cache write (5m / 1h TTL
  split), and cache read, normalized so the four categories are mutually
  exclusive across every source.
- **Where the context went** — not just how many tokens, but what they were:
  messages, system prompt, and reasoning, with tool calls, subagents, MCP
  servers, and skills broken out beneath them, down to which tools and which
  Bash commands. Reported for Claude Code, Codex, and pi; the sub-figures are
  size estimates, labeled as such, while the headline splits are exact.
- **Estimated cost** from public API list prices (LiteLLM's pricing
  database), with a bundled offline snapshot and user-editable per-model
  price overrides for self-hosted models (entered as `$ / 1M tokens`).
- **Durable history** — the SQLite database is a permanent ledger. It
  outlives the source logs (Claude Code prunes transcripts after ~30 days by
  default), so once ingested, history is retained even after the originals
  are gone.
- **Always at hand** — a Menu Bar Extra carries today's tokens and cost beside
  its icon, and the panel behind it reads out a window you pick (today,
  yesterday, or the trailing 30 days). Closing the window leaves TokenLedger
  running so it keeps capturing.

Cost is labeled *at API list prices — not billed*: every source here is
subscription, free-tier, or self-hosted, so the number is an estimate, not
an invoice.

## In the app

| Tab | What's on it |
|---|---|
| **Overview** | Everything above, over a date window and source selection you choose — plus **Export** (the whole selected window written to one sectioned CSV), **Trend** (enlarges into its own window, bucket size, and per-bucket CSV export), **Activity** (a 12-month heatmap that enlarges into a rotatable 3D landscape), and **Profile** (the window's models ranked across every source, top five with the rest one click away). Activity deliberately ignores the date window and source selection; Profile follows the window but never the source selection. |
| **Pricing** | Every model seen in the ledger with its resolved list price, the catalog it came from, and any override you've set |
| **Settings** | Theme (system / light / dark), language (English / 繁體中文), display currency at a fixed exchange rate, launch at login, auto-update checks, the scan interval, and **Custom range presets** — up to four of your own beside the four that ship, each a rolling *last N days* or a completed calendar period. Add one, reorder them by dragging (or with the arrows), retype a rolling one's day count, remove any; each row shows the dates it currently resolves to, and the picker lists them in the order you put them in |

## Install

Grab the build for your platform from
[Releases](https://github.com/BrianWong05/TokenLedger/releases/latest). Whichever
one you take, it updates itself from then on.

| Platform | Download | Before it runs |
|---|---|---|
| macOS (Apple Silicon) | `.dmg` | Not notarized yet: Gatekeeper says the app "is damaged and can't be opened" → **right-click the app → Open → Open** |
| Windows | `-setup.exe` | Not code-signed yet: SmartScreen says "Windows protected your PC" → **More info → Run anyway** |
| Linux | `.AppImage` | `chmod +x`, and the system tray needs `libayatana-appindicator3-1` (plus the AppIndicator extension on stock GNOME) |

Two things worth knowing before you install:

- **WSL is not scanned.** The Windows build reads the logs under your Windows
  home. Coding tools run inside WSL write to the Linux home instead, so a
  WSL-only setup shows an empty ledger.
- **The Menu Bar Extra is how you get back to the app.** Closing the window
  leaves TokenLedger running so it keeps capturing; on a Linux desktop with no
  system tray at all, that resident presence has nowhere to live.

## Privacy

TokenLedger reads your prompts, the models' responses, thinking, images, tool
arguments, and tool-result bodies — it has to, because sizin

... (truncated)