GitHub - mag123c/toktrack: Ultra-fast token & cost tracker for LLM Token Usage (e.g. Claude Code)

English | 한국어

⚠️ Did you know? Claude Code deletes your session data after 30 days by default. Once deleted, your token usage and cost history are gone forever — unless you preserve them.

Track token usage and costs across all your AI coding CLIs — Claude Code, Codex CLI, Gemini CLI, and OpenCode — in one dashboard.

Built with Rust for ultra-fast performance (simd-json + rayon parallel processing).

Why toktrack?

Performance Comparison

Dataset: 2,000+ JSONL files, 3.4 GB total

Existing tools:     ████████████████████████████████████████ 40s+
toktrack (cold):    █ ~1s (first run)
toktrack (cached):  ▏ ~0.04s (daily use)

                    └── up to 1000x faster

Features

• Ultra-Fast Parsing — simd-json + rayon parallel processing (~3 GiB/s throughput)
• TUI Dashboard — 3 tabs (Overview, Stats, Models) with daily/weekly/monthly views
• CLI Commands — daily, weekly, monthly, stats with JSON output support
• Usage Reports — Shareable text & SVG receipts via toktrack report
• Multi-CLI Support — Claude Code, Codex CLI, Gemini CLI, OpenCode in one place
• Data Preservation — Cached daily summaries survive CLI data deletion

Installation

npx (Recommended)

No Rust toolchain required. Downloads the correct binary for your platform automatically.

npx toktrack
# or
bunx toktrack

From Source

cargo install --git https://github.com/mag123c/toktrack

Pre-built Binaries

Download from GitHub Releases.

Quick Start

# Launch TUI dashboard
npx toktrack

# Get today's cost in JSON
npx toktrack daily --json

# Monthly summary
npx toktrack monthly --json

TUI Mode (Default)

CLI Commands

# Open TUI at specific tab
toktrack daily     # Overview (daily view)
toktrack weekly    # Overview (weekly view)
toktrack monthly   # Overview (monthly view)
toktrack stats     # Stats tab

# JSON output (for scripting)
toktrack daily --json
toktrack weekly --json
toktrack monthly --json
toktrack stats --json

# Usage report (shareable receipt)
toktrack report              # Last 7 days (text)
toktrack report --month      # Last 30 days
toktrack report --days 14    # Last N days
toktrack report --svg        # Text + SVG file

Keyboard Shortcuts

Supported AI CLIs

Performance

Measured on Apple Silicon with 2,000+ JSONL files (3.4 GB).

Why so fast? SIMD JSON parsing (simd-json) + parallel processing (rayon) = ~3 GiB/s throughput.

Data Preservation

The Problem: You've been using Claude Code for 3 months, spending hundreds of dollars. One day you want to check your total spending — but Claude Code already deleted your session files from 2 months ago. That cost data is gone forever.

toktrack solves this. It caches daily cost summaries independently, so your usage history survives even after the CLI deletes the original files.

CLI Data Retention Policies (The Hidden Risk)

toktrack Cache Structure

~/.toktrack/
├── cache/
│   ├── claude-code_daily.json   # Daily cost summaries
│   ├── codex_daily.json
│   ├── gemini_daily.json
│   └── opencode_daily.json
└── pricing.json                 # LiteLLM pricing (1h TTL)

Past dates in each *_daily.json are immutable — once a day is summarized, the cached result is never modified. Only the current day is recomputed on each run. This means even if Claude Code deletes session files after 30 days, your cost history remains intact in the cache.

Disable Claude Code Auto-Deletion

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 9999999999
}

Reset Cache

rm -rf ~/.toktrack/cache/

The next run will rebuild the cache from available session data.

How It Works

Cold path (first run): Full glob scan → parallel SIMD parsing → build cache → aggregate.

Warm path (cached): Load cached summaries → parse only recent files (yesterday midnight mtime filter) → merge → aggregate.

Deep Dive: I Rewrote a Node.js CLI in Rust — It Went from 43s to 1s | 한국어

Development

make check    # fmt + clippy + test (pre-commit)
cargo test    # Run tests
cargo bench   # Benchmarks

Roadmap

OpenCode support has been added! See Supported AI CLIs.

Contributing

Issues and PRs welcome!

make check  # Run before PR

License

MIT