tokenusage 1.4.0

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

# 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

# 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.

Is my data private?

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

Command Overview

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

Useful commands:

• tu daily --tui
• tu daily --json
• tu daily --jq '.rows[0]'
• 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.