tokenusage

Stop getting throttled without warning. Know your AI coding costs in 0.08s.

English | 中文

Install in one line

npm i -g tokenusage        # or: cargo install tokenusage --bin tu

Run it

tu                          # daily cost report in 0.08s

214x faster than ccusage on Claude logs · 138x faster on Codex logs · See benchmark

If tokenusage saves you time, give it a star — it directly helps other Codex and Claude users find it.

Screenshots

`tu` — daily report	`tu gui` — desktop dashboard
`tu img day` — shareable card	`tu img week` — weekly card
`tu live` — real-time TUI monitor

Why tokenusage

Problem	tokenusage solution
Hit rate limits mid-refactor, no warning	`tu live` shows usage in real-time
No idea what AI coding costs per day	`tu` gives daily cost breakdown in 0.08s
Codex / Claude / Gemini / OpenCode logs in separate places	One merged dashboard across all sources
Existing tools are slow on large logs	214x faster than ccusage (Rust + parallel scan + cache)
Don't want to upload logs to a cloud	100% local parsing, no data leaves your machine
Want coding-time context, not just raw tokens	`tu` keeps the classic token table by default; `--with-activity` opt-in adds coding time and tokens/hour
Want to share usage stats	`tu img` generates shareable image cards

This fork

This is FelixIsaac/tokenusage, a fork of hanbu97/tokenusage. All credit for the original tool goes upstream — this fork extends it with the following (see CHANGELOG.md for detail):

Performance & correctness

SQLite parse cache (parse-cache-v3.db) replacing the rewrite-everything JSON cache — incremental upserts, WAL mode (a statusline run can read while an interactive run writes), and a rayon-parallel file scan. Auto-migrates from the old JSON cache on first run.
Cache-thrash fix: the cache key is pricing-independent and cached events are re-priced at hydration, so the 6-hourly OpenRouter pricing refresh no longer wipes the cache; eviction is scoped to the roots actually scanned, so a single-source run (e.g. tu codex daily) no longer evicts the others.
tu gui no longer panics on window close (iced runs outside the tokio runtime — upstream issue #2).

UX

Interactive menu on bare tu (category-grouped, type-to-filter, arrow-keys); tu <cmd>, piped, and non-TTY invocations are unaffected.
tu statusline init — wires tu into Claude Code's status line with a safe JSON merge + backup + conflict guard (won't clobber another tool's line); --print (no-write preview), --ccstatusline (integration prompt for an existing status line), --yes. Plus modular tu statusline --json / --field / --format for ccstatusline widgets, sharing one per-session cache. See docs/statusline.md.
--brief — one-line headline (range · tokens · cost · top model) across today/daily/weekly/monthly/blocks/session.
Cost-centric insights (cache $ saved, reuse ratio, cost-concentration) and tu doctor cache/pricing health with a real-problems-only warnings section.
Menu Balances lists only providers whose API key is configured.

Platform

tu antigravity on Windows fails with a clear, actionable message instead of a cryptic ps/lsof error (a real Windows port is tracked separately).

Install this fork

The published tokenusage packages (npm / cargo / pip) are upstream. To run this fork:

# Prebuilt binary via Homebrew (macOS, Linux) — recommended, no Rust toolchain needed
brew install FelixIsaac/tokenusage/tokenusage

# Or build from source
git clone https://github.com/FelixIsaac/tokenusage
cd tokenusage
cargo install --path . --bin tu

Prebuilt binaries (shell/PowerShell installer scripts, and Windows/Linux archives) are also on the Releases page.

Install

npm (recommended)

npm install -g tokenusage

cargo (crates.io)

cargo install tokenusage --bin tu

pip (PyPI)

pip install tokenusage

cargo-binstall (prebuilt binary)

cargo binstall tokenusage --no-confirm

Quick Start

# Daily report (default)
tu                          # classic merged token report
tu --tui                    # same report in terminal UI

# Source-specific
tu codex daily
tu claude daily
tu gemini
tu opencode
tu antigravity

# Provider selection (merged commands)
tu --only codex,gemini
tu weekly --sources claude,opencode

# Data source diagnostics
tu doctor
tu doctor --only opencode --json

# Date filter
tu --since 2026-02-01 --until 2026-02-28

# Weekly / monthly
tu weekly --start-of-week monday
tu monthly

# Native time views inferred from local AI usage
tu today
tu today --since 2026-05-01 --until 2026-05-05
tu activity
tu activity --days 14
tu activity --project tokenusage

# Add locally inferred coding activity columns (Coding / Tok/hr)
tu --with-activity
tu --with-activity --tui
tu live --with-activity

# Native local heartbeat collector
tu heartbeat watch .
tu heartbeat stats
tu heartbeat ping src/main.rs --write

# Live monitor (tabs: Codex / Claude / Gemini / OpenCode / Antigravity)
tu live
tu live codex
tu live claude
tu live gemini
tu live opencode
tu live antigravity

# Real-time per-session viewer (htop for tokens)
tu top
tu top --active-hours 12    # show sessions active in last 12h
tu top --active-hours 0     # show all sessions

# GUI dashboard
tu gui

# Share image card (for social posting)
tu img
tu img day
tu img week

Data locations (defaults)

Claude Code: ~/.claude/projects (override with --claude-projects-dir)
Codex CLI: $CODEX_HOME/sessions (fallback ~/.codex/sessions, override with --codex-sessions-dir)
Gemini CLI: ~/.gemini/tmp (override with --gemini-data-dir)
OpenCode: $OPENCODE_DATA_DIR or $XDG_DATA_HOME/opencode (fallback ~/.local/share/opencode, override with --opencode-data-dir)
Grok Build: ~/.grok/logs (override with --grok-log-dir)

--only / --sources currently target log-based providers (claude, codex, gemini, opencode, grok). Antigravity remains a separate quota probe. Note: tu grok is the pre-existing xAI balance-check subcommand (needs XAI_API_KEY) — Grok's log-based usage data is accessed via --sources grok/--only grok, not a tu grok daily-style shortcut like the other four sources have, since the bare word grok is already claimed by that balance command.

Benchmark Details

Setup:

Machine: Apple M3 Max, macOS 15.6.1
tu version: 1.2.6 · ccusage version: 18.0.8 · @ccusage/codex version: 18.0.8
Default mode (no date filters, online pricing, network enabled)

Codex — 91 JSONL files, 1.7 GB (~/.codex/sessions)

	`tu codex daily`	`bunx @ccusage/codex`	Speedup
Cold (rebuild cache)	0.92s	20.76s	22.6x
Warm (best of 5 / avg of 3)	0.15s	20.76s	138x

Claude — 1 521 JSONL files, 2.2 GB (~/.claude/projects)

	`tu claude daily`	`bunx ccusage`	Speedup
Cold (rebuild cache)	0.73s	17.15s	23.5x
Warm (best of 5 / avg of 3)	0.08s	17.15s	214x

Results vary by hardware, filesystem cache state, and log volume.

For a detailed feature comparison, see tokenusage vs ccusage.

FAQ

Where does the data come from?

From local log directories and IDE probes:

Claude: ~/.config/claude/projects, ~/.claude/projects
Codex: ~/.codex/sessions, ~/.config/codex/sessions
Gemini: ~/.gemini/tmp
OpenCode: $OPENCODE_DATA_DIR or ~/.local/share/opencode
Grok Build: ~/.grok/logs
Antigravity: probed from running IDE language server (no log files needed)

You can override with --claude-projects-dir, --codex-sessions-dir, --gemini-data-dir, --opencode-data-dir, and --grok-log-dir.

OpenCode merge semantics:

tu ingests both opencode.db and legacy storage/message/**/*.json when both exist.
Cross-source dedupe prefers stable OpenCode message ids (msg_*) so DB and legacy copies of the same assistant message are counted once.
tu doctor --only opencode --json reports DB/legacy discovered and retained counts to debug overlap.

How is cost estimated?

tu uses OpenRouter pricing when available, caches it for 6 hours, and falls back to built-in offline rates when network pricing is unavailable.

How does `--with-activity` work?

tu infers coding activity locally from your machine. By default it clusters nearby AI usage events into active windows. If you enable the native heartbeat collector (tu heartbeat watch ...), tu will prefer heartbeat-backed activity on days with sufficient heartbeat coverage and fall back to token-event inference elsewhere.

From that local activity signal, tu derives:

coding time
tokens per coding hour
cost per coding hour
project / language / source breakdowns

The dedicated time views (tu today, tu activity) enable this automatically. --with-activity adds the same local activity context to daily/weekly/monthly reports and tu live.

By default, tu keeps the original merged token report layout. The extra Coding / Tok/hr columns only appear when activity context is explicitly enabled with --with-activity, or when you use the dedicated time views.

What are `Insights` in reports?

tu now computes derived analytics for daily/weekly/monthly reports and includes them in both CLI and JSON output:

cache/output token share
unit efficiency ($/1M tok, tok/$)
top source and top model concentration
streaks and average active-day usage
peak period, token spikes, robust anomaly detection
provider mix by tokens/cost

Spike and anomaly entries include top source/model attribution, and when available, top project/session attribution for faster root-cause checks on heavy periods. In tu gui, the same insights are surfaced as summary cards.

Is my data private?

Yes for usage logs: parsing is local. tu only requests pricing metadata unless you run --offline.

Why did historical tokens drop after a machine cleanup?

tu only counts what still exists in local provider logs. If old session files were deleted/rotated by the provider, OS cleanup, or storage migration, past token totals can drop and cannot be reconstructed exactly from pricing/cache data alone.

Use tu doctor --json to verify current discovered roots/files. Keep periodic backups of provider log dirs (~/.claude/projects, ~/.codex/sessions, ~/.gemini/tmp, OpenCode data dir) if long-term parity matters.

Command Overview

tu [daily|today|activity|heartbeat|doctor|parity|antigravity|monthly|weekly|img|session|blocks|live|top|statusline|gui]

Provider-first grammar:
- `tu <provider> <report>` e.g. `tu codex daily`, `tu claude weekly`, `tu opencode doctor`

Useful commands:

tu --tui
tu --with-activity --tui
tu daily --tui
tu daily --json
tu daily --jq '.rows[0]'
tu today
tu activity --days 14
tu heartbeat watch .
tu heartbeat stats
tu blocks --active
tu blocks --live
tu live
tu img --output tokenusage-share.png (today, hourly)
tu img --period weekly --output tokenusage-week.png (7 days, daily)
tu parity --provider claude --period daily --since 20260401 --until 20260401 --json
tu img --logo ./logo.png --brand-url tokenusage.dev
tu statusline

Config File

Config search order:

./.tu/tu.json
~/.config/tu/tu.json
~/.config/tokenusage/tokenusage.json

Use an explicit config file:

tu --config /path/to/tu.json

Example:

{
  "defaults": {
    "timezone": "Asia/Shanghai",
    "workers": 16,
    "compact": false
  },
  "commands": {
    "daily": {
      "instances": true
    },
    "live": {
      "sessionLength": 5,
      "refreshInterval": 1
    },
    "img": {
      "period": "daily",
      "bars": 24,
      "brand": "tokenusage",
      "brandUrl": "https://github.com/FelixIsaac/tokenusage"
    },
    "weekly": {
      "startOfWeek": "monday"
    }
  }
}

Pricing

tu --pricing-file ./pricing.json

Offline-only mode:

tu --offline

Demo Dataset (No Real Data)

python3 examples/demo/generate_demo_data.py
tu daily --config ./examples/demo/tu.demo.json --since 2026-02-09 --until 2026-02-28
tu live --config ./examples/demo/tu.demo.json
tu gui --config ./examples/demo/tu.demo.json --since 2026-02-09 --until 2026-02-28
tu img --config ./examples/demo/tu.demo.json --since 2026-02-28 --until 2026-02-28 --output ./docs/images/share-demo.png
tu img --config ./examples/demo/tu.demo.json --period weekly --since 2026-02-22 --until 2026-02-28 --output ./docs/images/share-week-demo.png

Development

cargo fmt
cargo clippy --all-targets --all-features
cargo check

Release notes: see CHANGELOG.md.

License

MIT. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 163 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
npm/tu		npm/tu
pypi/tu		pypi/tu
scripts		scripts
site		site
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README.zh-cn.md		README.zh-cn.md
SECURITY.md		SECURITY.md
dist-workspace.toml		dist-workspace.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

tokenusage

Install in one line

Run it

Screenshots

Why tokenusage

This fork

Install this fork

Install

npm (recommended)

cargo (crates.io)

pip (PyPI)

cargo-binstall (prebuilt binary)

Quick Start

Data locations (defaults)

Benchmark Details

FAQ

Where does the data come from?

How is cost estimated?

How does `--with-activity` work?

What are `Insights` in reports?

Is my data private?

Why did historical tokens drop after a machine cleanup?

Command Overview

Config File

Pricing

Demo Dataset (No Real Data)

Development

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

tokenusage

Install in one line

Run it

Screenshots

Why tokenusage

This fork

Install this fork

Install

npm (recommended)

cargo (crates.io)

pip (PyPI)

cargo-binstall (prebuilt binary)

Quick Start

Data locations (defaults)

Benchmark Details

FAQ

Where does the data come from?

How is cost estimated?

How does --with-activity work?

What are Insights in reports?

Is my data private?

Why did historical tokens drop after a machine cleanup?

Command Overview

Config File

Pricing

Demo Dataset (No Real Data)

Development

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

How does `--with-activity` work?

What are `Insights` in reports?