tokenusage 1.5.2

Install in one line

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

Run it

tu                          # daily cost report in 0.08s

Screenshots

Why tokenusage

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
tu claude
tu antigravity

# 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 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 / Antigravity)
tu live
tu live codex
tu live claude
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

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)

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

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
• Antigravity: probed from running IDE language server (no log files needed)

You can override with --claude-projects-dir and --codex-sessions-dir.

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.

Is my data private?

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

Command Overview

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

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 img --logo ./logo.png --brand-url tokenusage.dev
• tu statusline

Config File

Config search order:

1. ./.tu/tu.json
2. ~/.config/tu/tu.json
3. ~/.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/hanbu97/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

License

MIT. See LICENSE.