Token Usage

token-usage

[简体中文](README.zh-CN.md) | English

A local LLM usage analytics tool for collecting, analyzing, and querying token usage across AI clients — and for turning that data into your own multi-dimensional usage reports, no SQL required.

Features

• Message/API-request-level accounting: each actual model invocation is stored independently instead of aggregating tokens by session.
• Accurate attribution across dates and models: messages that span dates, sessions that use multiple models, and forks/branches are neither missed nor double-counted.
• Preserves actual rewind consumption: completed calls before a rewind and new calls after it are kept separately rather than deduplicated.
• Codex rollout replay deduplication: replayed complete token snapshots caused by rate-limit bucket changes are not counted twice, while legitimate resets and multi-turn calls are retained.
• Multiple data sources: Claude Code/Desktop, OpenCode, Codex, WorkBuddy, ZCode, and Zhipu-AutoClaw.
• CC Switch router attribution: backfills the actual provider/model from CC-Switch proxy logs (currently effective only for the Claude family).
• Build your own usage reports — no SQL required: combine client, model, provider, and project into named multi-dimensional views; compose built-in and custom views into reusable, ordered report groups; set a personal default and run it by name. The guided configuration TUI and query list make those views discoverable and easy to maintain.
• Two run modes: one-off CLI commands and a real-time monitoring daemon with nginx-style background startup.
• Autostart: macOS launchd and the Windows Registry, configurable through the config TUI or config set.
• Opt-in configuration: every client is disabled by default; enable only the ones you use, while data-source paths fall back to ready-to-use defaults.
• Single-binary distribution: built with Go and pure-Go SQLite (no CGO), with macOS and Windows supp