token-usage

README

token-usage

简体中文 | English

A local LLM usage analytics CLI. It collects token usage from the AI clients you use, keeps each model invocation as an independent record, and turns the data into reusable reports without SQL.

Highlights

• Build the report you actually want — no SQL required. Define a named multi-dimensional view from client, model, provider, and project; then compose built-in and custom views into a reusable, ordered report group. Set it as the default, discover it with query list, and run it by name.
• Message/API-request-level accounting, including accurate attribution across dates, models, branches, and rewinds.
• Collectors for Claude Code/Desktop, OpenCode, Codex, WorkBuddy, ZCode, and Zhipu-AutoClaw.
• CC-Switch router attribution for the Claude family, backfilling the actual provider and model from proxy logs.
• One-off commands or a real-time background monitoring daemon, with macOS launchd and Windows Registry autostart.
• A pure-Go, single-binary CLI for macOS and Windows.

Quick Start

1. Install and Update

The official installer downloads the latest stable Release, verifies its SHA256 checksum, installs the binary under ~/.token-usage/bin, and configures your user PATH. It needs neither sudo nor administrator privileges.

Paste this into an AI agent (it installs and verifies):

Install token-usage on this machine with the appropriate official installer:

- macOS: curl -fsSL https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.sh | bash
- Windows PowerShell:
  irm https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.ps1 -OutFile "$env:TEMP\install.ps1"
  powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1"

Open a new terminal, run `token-usage --help` to see the commands, and verify the installation with `token-usage version`.

macOS:

curl -fsSL https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.ps1 -OutFile "$env:TEMP\install.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1"

Open a new terminal, then verify the installation:

token-usage version

Both the installer and a manually SHA256-verified official Release asset update themselves in place:

token-usage update                  # latest stable Release
token-usage update --check          # check only; makes no local changes
token-usage update --version vX.Y.Z # a specific Release

For a re-signed official asset, a source build (Version = dev), or go install of a tagged release, run token-usage update --force once to replace it with an official Release asset; later updates work normally. Symlinked copies and non-official tags cannot be converted this way.

For manual installation, a pinned version, source builds, update trust rules, uninstall, migration, and platform-specific notes, see the Installation Guide.

2. Configure in the TUI and Collect

All clients start disabled. We recommend the guided configuration TUI: it initializes the configuration on first use, lets you enable the clients you use, and can also configure routers, the daemon, logs, aliases, and query views.

token-usage config

After saving the TUI configuration, collect the history of enabled clients:

token-usage collect all

collect all scans all enabled clients and includes router attribution backfill where configured. It bypasses collection_log date deduplication and is safe to rerun because messages are upserted by (client, id). To keep new data current, start the daemon:

token-usage start

3. Query and Build Your Own Reports

token-usage query             # today's default report (client when unconfigured)
token-usage query model       # group by model
token-usage query 20260701-20260721

Dates are positional: YYYYMMDD for one day or YYYYMMDD-YYYYMMDD for an inclusive range.

The real payoff is making a report fit the question you return to. In the TUI, open Query views to create a named multi-dimensional view, combine views into an ordered report group, and select its default. You can also define portable views in ~/.token-usage/config.toml:

[query]
default = "daily_stack"

[query.subqueries]
model_provider_client = "model,provider,client"

[query.groups]
daily_stack = "client,model,provider,model_provider_client"

token-usage query model_provider_client
token-usage query daily_stack 20260701-20260721
token-usage query list

query list reads only configuration and never opens the usage database, so it is a safe way to discover built-in and configured views. The CLI Reference describes the validation rules and complete command contract.

Command Cheat Sheet

Command	Purpose
config / config init	Open the configuration TUI / create initial configuration and database.
config set <key> <value>	Change one configuration value.
collect [date]	Incrementally collect today or a date range.
collect all	Collect all history without collection_log date deduplication; safe to rerun.
collect retry	Retry unresolved collection failures.
query [date]	Run the default report.
query client/model/provider/project/session/summary [date]	Run a built-in report.
query <name> [date]	Run a configured view or group.
query list	List views without opening the usage database.
errors	Show collection failures.
version / --version	Show detailed / one-line version information.
start / status / stop / restart	Control the background daemon.
completion <shell>	Print a Bash, Zsh, Fish, or PowerShell completion script.
update	Self-update an official Release asset in place; use update --force once to switch an eligible re-signed, source-built, or go install binary.

Run token-usage --help for a command overview, or read the CLI Reference for flags, exit codes, side-effect boundaries, configuration behavior, and daemon lifecycle.

Shell Completion

completion writes a shell-completion script to standard output. For example, load Zsh completion in the current session:

source <(token-usage completion zsh)

For persistent setup, run token-usage completion <bash|zsh|fish|powershell> --help.

Documentation

Document	What it covers
Installation Guide	All installation methods, self-update, uninstall, migration, PATH, and platform notes.
CLI Reference	Command tree, arguments, flags, examples, configuration, and daemon behavior.
Architecture	Data flow, storage, process control, update design, and extension points.
Contributing Guide	Development setup, tests, documentation, commits, and pull requests.

Platform Support

Platform	Build	Daemon	Autostart
macOS	Yes	Yes	launchd
Windows	Yes	Yes	Registry Run key

Development

make build
go test ./...
go test -race ./...

Use make build-all for the supported macOS and Windows targets. See the Contributing Guide for the full development workflow.

License

This project is released under the MIT License.