tokenusage (tu)

Blazing-fast Rust token usage tracker for Claude Code and Codex.

tu scans local session logs, merges multiple sources, estimates cost, and shows results in:

• CLI table (responsive columns)
• TUI (sticky header + scroll)
• GUI (iced + tiny-skia)
• Live session monitor with progress bars

Why tu

• Real-world speedup vs ccusage: about 34.5x (cold) and 131.1x (warm) on local Codex logs
• Why it is faster: native Rust startup, parallel file discovery/parsing, and incremental cache reuse
• One report for both Codex + Claude (merged totals and merged model view)
• Also supports source-specific modes: tu codex, tu claude, tu live codex, tu live claude

This project is built for people searching for: Claude Code usage tracker, Codex usage monitor, LLM token cost dashboard, Rust TUI/GUI token analytics.

Screenshots

Install

cargo (crates.io)

cargo install tokenusage --bin tu

Homebrew

brew tap hanbu97/tap
brew install tu

npm

npm install -g tokenusage

From source

cargo install --path . --bin tu --force

Quick Start

# Run daily report (default command)
tu

# Only Codex / only Claude
tu codex
tu claude

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

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

# Live block monitor
tu live
tu live codex
tu live claude

# GUI dashboard
tu gui

Benchmark Details (Real Local Data, Codex-Only)

Benchmark setup:

• Machine: Apple M3 Max, macOS 15.6.1
• Dataset: ~/.codex/sessions (71 JSONL files, ~537 MB), date range 2025-09-01 to 2026-02-28
• tu version: 1.1.0
• @ccusage/codex version: 18.0.8
• Both in default mode (online pricing behavior, network enabled)

Results:

• Cold-run speedup: about 34.5x
• Warm-run speedup: about 131.1x

Notes: results vary by hardware, filesystem cache state, and log volume.

Demo Dataset (No Real Data)

Use the bundled mock dataset when you want screenshots/demos without exposing local usage logs.

# regenerate demo logs
python3 examples/demo/generate_demo_data.py

# run reports with demo-only config
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

What tu Tracks

• Input tokens
• Output tokens
• Cache create tokens
• Cache read tokens
• Total tokens
• Estimated cost (USD)
• Per-model merged view (claude-haiku-..., gpt-5.3-codex, etc.)

Data Sources

By default, tu checks these directories and merges all valid logs:

• Claude:
  • ~/.config/claude/projects
  • ~/.claude/projects
• Codex:
  • ~/.codex/sessions
  • ~/.config/codex/sessions

You can override with:

• --claude-projects-dir <PATH> (repeatable)
• --codex-sessions-dir <PATH> (repeatable)

This merged mode is the key difference from single-source tools: one timeline/table can include both providers, while still allowing per-source commands when needed.

Command Overview

tu [daily|codex|claude|monthly|weekly|session|blocks|live|statusline|gui]

Useful commands:

• tu daily --tui: terminal table UI with sticky header
• tu daily --json
• tu daily --jq '.rows[0]'
• tu blocks --active
• tu blocks --live
• tu live: same intent as live block monitor
• tu statusline: statusline output (cache-aware)

Config File

Config search order:

1. ./.tu/tu.json
2. ~/.config/tu/tu.json
3. ~/.config/tokenusage/tokenusage.json

You can also pass explicit config:

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

Example:

{
  "defaults": {
    "timezone": "Asia/Shanghai",
    "workers": 16,
    "compact": false
  },
  "commands": {
    "daily": {
      "instances": true
    },
    "live": {
      "sessionLength": 5,
      "refreshInterval": 1
    },
    "weekly": {
      "startOfWeek": "monday"
    }
  }
}

Pricing

• Uses OpenRouter model pricing when available.
• Pricing cache TTL: 6 hours.
• Falls back to built-in offline rate table if network data is unavailable.
• Optional override file:

tu --pricing-file ./pricing.json

Use offline-only mode:

tu --offline

Performance Notes

• Parallel file discovery via ignore crate
• Parallel parsing with rayon + worker threads + channels
• Incremental parse cache for repeated runs

Built-in heavy directory ignores include: .git, node_modules, target, dist, build, .cache, venv...

Troubleshooting

• If no data appears, pass explicit roots:
  • --claude-projects-dir ...
  • --codex-sessions-dir ...
• If your terminal is narrow, tu auto-switches to compact columns.
• Use --debug to print parser stats.

Development

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

Release (Maintainers)

Tag-based release is enabled in GitHub Actions (.github/workflows/release.yml).

On tag push (vX.Y.Z), the pipeline:

• builds and uploads release assets (Linux/macOS/Windows)
• publishes GitHub Release
• publishes to crates.io and npm (release fails if tokens are missing)
• optionally updates Homebrew tap formula (if configured)

Required repository secrets for full multi-channel publish:

• CRATES_IO_TOKEN
• NPM_TOKEN
• HOMEBREW_TAP_PAT

If CRATES_IO_TOKEN or NPM_TOKEN is missing, the tagged release job fails to prevent partial publish.

Homebrew tap target repo defaults to:

• hanbu97/homebrew-tap (tap name: hanbu97/tap)

git tag v1.1.0
git push origin v1.1.0

Version sync requirement before tagging:

• Cargo.toml package.version must equal tag without v
• npm/tu/package.json version must equal tag without v

License

MIT. See LICENSE.