Skip to content
pyyxziPublic

About

Local-first AI usage & cost workbench for Windows. One unified ledger of tokens, cost, models and sessions across 25+ AI coding tools (Claude Code, Codex CLI, Gemini CLI...). token usage tracker / token 统计 / AI 用量统计 / 费用统计

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TokenLens

Local-first AI usage & cost workbench for Windows. TokenLens scans the logs your AI coding tools already write to disk and turns them into one unified ledger: tokens, estimated cost, models, projects and per-session detail — without uploading anything.

CI License: MIT Platform PRs Welcome

简体中文 | English


Overview dashboard

More screenshots
Usage by tool Data sources
Usage by tool Data sources

Why TokenLens

If you use several AI tools — Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot, … — every one of them keeps its own usage log in its own format. Answering "what did I actually burn this month, on which model, in which project?" means reverse-engineering a dozen log formats by hand.

TokenLens does that once, properly:

  • One unified ledger. 25+ data sources normalized into a single schema: input / output / cache-read / cache-write / reasoning tokens, per call, with stable event IDs so rescans stay idempotent.
  • Cache efficiency at every level. Input token cache hit rate appears in the overview, tool/model/project/session views, records and reports, with average tokens per call where applicable. Cache hit rate is cache-read tokens divided by all input tokens (uncached + cache read + cache write), computed after aggregation; no input data is shown as N/A.
  • Cost you can reason about. Public per-model price tables plus your own manual prices produce USD estimates; provider-reported actuals are kept when the source exposes them. Subscription-only sources are labeled honestly instead of being mislabeled as dollars.
  • Local-first privacy. Everything runs on your machine and lands in a local SQLite database. API keys for the optional AI assistant are protected with Windows DPAPI. No telemetry, no cloud dashboard.
  • Built for big histories. Incremental scanning (unchanged files are skipped by fingerprint), paginated drill-downs, background aggregation — validated against a 300k-record, ~260 MiB database.
  • Import & export. CSV / JSON / JSONL import with full pre-validation, snapshot backup & restore, CSV export.
  • Optional AI analysis. A built-in assistant can analyze usage, draft reports and optimize prompts — it only ever calls the provider you configure, and only when you ask.
  • Signed auto-updates. The app quietly checks GitHub Releases and offers one-click signed updates (tray menu → Check for updates…).

Supported data sources

CLI agents: Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, Aider, Goose, Pi, Kimi, ZCode, WorkBuddy, DeepSeek Harness, generic API logs IDE & editors: Cursor, Windsurf, Trae, Qoder, Continue, Cline-family, JetBrains AI (via Cline family), Claude Desktop Local runtimes: Ollama, LM Studio, Cherry Studio Plus user imports: CSV / JSON / JSONL

Each adapter documents the exact log format it reads, with upstream references, in backend/tokenlens/SOURCES.md. Sources whose logs can only give approximate totals are marked as such in the UI — TokenLens never presents a guess as an exact bill.

Getting started

Download the latest installer from Releases (Windows 10/11 x64, NSIS installer), or build from source:

Requirements: Windows 10/11 x64, WebView2, Node.js LTS, Rust (MSVC toolchain), Python 3.14 series (3.14.8+ recommended).

git clone https://github.com/pyyxzi/tokenlens.git
cd REPO
.\build.ps1 -Python 'C:\path\to\python.exe' -WorkDir 'D:\tokenlens-build'

WorkDir holds the virtual environment, dependencies and build caches and should live outside the repository; the installer ends up in <WorkDir>\target\...\bundle. Append -Dev for a development build, or -UseExistingPython if you already have an isolated environment.

For day-to-day backend work you don't need the full toolchain — Python alone is enough to run the tests:

python -m unittest discover -s backend/tests -v

How it works

┌──────────────┐   spawns    ┌──────────────────┐   reads    ┌─────────────┐
│  src-tauri/  │ ──────────▶ │    backend/      │ ─────────▶ │ tool logs   │
│  Rust host:  │  sidecar    │  Python service: │            │ (25+ tools) │
│  window,tray │ ◀────────── │  scan · parse ·  │            └─────────────┘
│  IPC bridge  │  localhost  │  aggregate ·     │
└──────┬───────┘  + secret   │  price · serve   │   writes   ┌─────────────┐
       │ loads     token     └──────────────────┘ ─────────▶ │ SQLite DB   │
       ▼                                                      └─────────────┘
┌──────────────┐
│  frontend/   │  vanilla JS/CSS workbench: dashboard, rankings,
│  UI bundle   │  drill-downs, themes, zh-CN / en-US
└──────────────┘
  • src-tauri/ — native window, tray, single-instance, and the Python sidecar lifecycle (job objects, crash recovery, generation-based reconnection).
  • backend/ — the analytics engine: adapters for every data source, incremental scanner, aggregator, price tables, AI assistant services, import/backup.
  • frontend/ — the workbench UI, no framework, no build step.

Data & privacy

  • Statistics are computed locally; the database lives in the system app-data directory.
  • The analytics service binds to 127.0.0.1 on a random port, authenticated with a per-launch secret; the frontend talks to it only through the native bridge.
  • The optional AI assistant sends requests only to the provider you configure, only when you trigger it. Credential handling is described in SECURITY.md.
  • The only outbound request the app makes on its own is a version check against this repository's GitHub Releases; updates are minisign-signed and verified before install.

Documentation

Contributing

Issues and pull requests are welcome! New data-source adapters are the single most valuable contribution — see the adapter guide and CONTRIBUTING.md to start. Good first issues are labeled good first issue.

License

MIT — third-party notices in THIRD_PARTY_NOTICES.md and licenses/.

About

Local-first AI usage & cost workbench for Windows. One unified ledger of tokens, cost, models and sessions across 25+ AI coding tools (Claude Code, Codex CLI, Gemini CLI...). token usage tracker / token 统计 / AI 用量统计 / 费用统计

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages