Tokscale: AI Coding Token Usage Tracker

A high-performance CLI tool and visualization dashboard for tracking token usage and costs across multiple AI coding agents.

[!TIP]

I drop new open-source work every week. Don't miss the next one.

	Follow @junhoyeo on GitHub for more projects. Hacking on AI, infra, and everything in between.
	Come hang out in our Discord — and surround yourself with the world's top-tier vibers.
	Support Tokscale's continued development through GitHub Sponsors.

🇺🇸 English | 🇰🇷 한국어 | 🇯🇵 日本語 | 🇨🇳 简体中文

Overview	Models

Daily Summary	Stats

Run bunx tokscale@latest submit to submit your usage data to the leaderboard and create your public profile!

Overview

Tokscale helps you monitor and analyze your token consumption from:

Get real-time pricing calculations using 🚅 LiteLLM's pricing data, with support for tiered pricing models and cache token discounts.

Why "Tokscale"?

This project is inspired by the Kardashev scale, a method proposed by astrophysicist Nikolai Kardashev to measure a civilization's level of technological advancement based on its energy consumption. A Type I civilization harnesses all energy available on its planet, Type II captures the entire output of its star, and Type III commands the energy of an entire galaxy.

In the age of AI-assisted development, tokens are the new energy. They power our reasoning, fuel our productivity, and drive our creative output. Just as the Kardashev scale tracks energy consumption at cosmic scales, Tokscale measures your token consumption as you scale the ranks of AI-augmented development. Whether you're a casual user or burning through millions of tokens daily, Tokscale helps you visualize your journey up the scale—from planetary developer to galactic code architect.

Contents

• Overview
  • Why "Tokscale"?
• Features
• Installation
  • Quick Start
  • Prerequisites
  • Development Setup
  • Building the Native Module
• Usage
  • Basic Commands
  • TUI Features
  • Filtering by Platform
  • Date Filtering
  • Pricing Lookup
  • Social
  • Autosubmit
  • Cursor IDE Commands
  • Antigravity Commands
  • Trae Commands
  • Warp/Oz Commands
  • Task-Attributed Report
  • Subscription Usage
  • Example Output
  • Configuration
  • Environment Variables
• Frontend Visualization
  • Features
  • Running the Frontend
• Social Platform
  • Features
  • Getting Started
  • Data Validation
• Wrapped 2025
  • Command
  • What's Included
• Development
  • Prerequisites
  • How to Run
  • Container Setup
• Supported Platforms
  • Native Module Targets
  • Windows Support
• Session Data Retention
• Data Sources
• Pricing
• Contributing
  • Development Guidelines
• Acknowledgments
• License

Features

• Interactive TUI Mode - Beautiful terminal UI powered by Ratatui (default mode)
  • 6 interactive views: Overview, Models, Daily, Hourly, Stats, Agents (plus an optional Minutely view, opt-in via minutelyTabEnabled)
  • Keyboard & mouse navigation
  • GitHub-style contribution graph with configurable color themes
  • Real-time filtering and sorting
  • Zero flicker rendering
• Multi-platform support - Track usage across OpenCode, Claude Code, Codex CLI, Prime Agent, Copilot CLI, Cursor IDE, Gemini CLI, Amp, Codebuff, Droid, OpenClaw, Hermes Agent, Pi, Kimchi Coding, Reasonix, Kimi CLI, Kimi Work, Qwen CLI, Roo Code, Kilo, Mux, Kilo CLI, Crush, Goose, Antigravity, Antigravity CLI, Zed, Kiro, Trae, Warp/Oz, Cline, Gajae-Code, Grok Build, Jcode, MiMo Code, Command Code, Junie, ZCode, OpenCodeReview, CodeBuddy, WorkBuddy, Devin CLI, Devin Desktop, Augment Code, Synthetic, Cherry Studio, LM Studio, Unsloth Studio, Hindsight, fx, and Oh My Pi
• Real-time pricing - Fetches current pricing from LiteLLM with 1-hour disk cache; automatic OpenRouter fallback and Cursor model pricing for newly released models
• Detailed breakdowns - Input, output, cache read/write, and reasoning token tracking
• Native Rust core - All parsing and aggregation done in Rust for 10x faster processing
• Web visualization - Interactive contribution graph with 2D and 3D views
• Flexible filtering - Filter by platform, date range, or year
• Task-attributed reports - LLM-powered session summarization and task grouping with multi-backend support (Apple FM, Claude, Codex, Gemini, Kiro, MiniMax)
• Export to JSON - Generate data for external visualization tools
• Social Platform - Share your usage, compete on leaderboards, and view public profiles

Installation

Quick Start

# Run directly with npx
npx tokscale@latest

# Or use bunx
bunx tokscale@latest

# Or use Deno without installing an alias
deno x npm:tokscale@latest

# Light mode (table rendering only)
npx tokscale@latest --light

That's it! This gives you the full interactive TUI experience with zero setup.

Package Structure: tokscale is an alias package (like swc) that installs @tokscale/cli. Both install the same CLI with the native Rust core (@tokscale/core) included.

Prerequisites

• Node.js or Bun
• (Optional) Rust toolchain for building native module from source

Development Setup

For local development or building from source:

# Clone the repository
git clone https://github.com/junhoyeo/tokscale.git
cd tokscale

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Run the CLI in development mode
bun run cli

Note: bun run cli is for local development. When installed via bunx tokscale, the command runs directly. The Usage section below shows the installed binary commands.

Building the Native Module

The native Rust module is required for CLI operation. It provides ~10x faster processing through parallel file scanning and SIMD JSON parsing:

# Build the native core (run from repository root)
bun run build:core

Note: Native binaries are pre-built and included when you install via bunx tokscale@latest. Building from source is only needed for local development.

Usage

Basic Commands

# Launch interactive TUI (default)
tokscale

# Launch TUI with specific tab
tokscale models    # Models tab
tokscale monthly   # Daily view (shows daily breakdown)
tokscale hourly    # Hourly tab

# Use legacy CLI table output
tokscale --light
tokscale models --light

# Launch TUI explicitly
tokscale tui

# Export contribution graph data as JSON
tokscale graph --output data.json

# Output data as JSON (for scripting/automation)
tokscale --json                    # Default models view as JSON
tokscale models --json             # Models breakdown as JSON
tokscale monthly --json            # Monthly breakdown as JSON
tokscale models --json > report.json   # Save to file

TUI Features

The interactive TUI mode provides:

• 8 Views: Overview (chart + top models), Usage (subscription quotas), Models, Daily, Hourly, Stats (contribution graph), Agents. A per-minute view (Minutely) is hidden by default and can be enabled with minutelyTabEnabled in settings.json — see Configuration
• Keyboard Navigation:
  • ←/→/Tab/BackTab: Switch views
  • ↑/↓ or Home/End: Navigate lists
  • Enter: Open daily detail (Daily tab) / select graph cell (Stats tab)
  • Esc or Backspace: Close dialog or exit detail view
  • c/d/t: Sort by cost/date/tokens
  • j: Jump to today
  • s: Open source picker dialog
  • g: Open group-by picker dialog (model, client+model, client+provider+model, workspace+model, session+model, client+session+model)
  • h: Toggle Daily/Hourly chart granularity (Overview tab)
  • v: Toggle Table/Profile view (Hourly tab)
  • y: Copy selected row to clipboard
  • p: Cycle through color themes
  • L: Toggle light mode (white background)
  • r: Refresh data; Shift+R toggles auto-refresh; +/- adjusts interval
  • e: Export to JSON
  • q or Ctrl+C: Quit
• Mouse Support: Click tabs, buttons, and filters
• Themes: Green, Halloween, Teal, Blue, Pink, Purple, Orange, Monochrome, YlGnBu, Graphite, Lagoon, Dusk
• Settings Persistence: Preferences saved to ~/.config/tokscale/settings.json (see Configuration)

Group-By Strategies

Press g in the TUI or use --group-by in --light/--json mode to control how model rows are aggregated:

--group-by model (most consolidated)

--group-by client,model (CLI default)

--group-by client,provider,model (most granular)

--group-by session,model (per-session cost attribution)

tokscale models --json --group-by session,model emits one entry per (session_id, model). Each entry includes a top-level sessionId field so downstream tools (e.g. multi-agent IDEs) can join cost data back to a specific agent-CLI session:

{
  "groupBy": "session,model",
  "entries": [
    {
      "sessionId": "019e1e27-af49-7cd1-89b7-7bad1c3f3be2",
      "client": "codex",
      "provider": "openai",
      "model": "gpt-5",
      "input": 25251,
      "output": 47,
      "cacheRead": 1920,
      "cacheWrite": 0,
      "reasoning": 40,
      "messageCount": 12,
      "cost": 0.0123
    }
  ]
}

Use --group-by client,session,model when you also need the client name on every row (one spawn across all 20+ supported CLIs at once).

Per-workspace cost

--group-by workspace,model attributes usage to the directory an agent ran in, so you can see what a given project cost:

# One row per (workspace, model)
tokscale models --light --group-by workspace,model --month

# Fold every git worktree into its parent repository — one row per repo
tokscale models --light --group-by workspace,model --merge-worktrees --month

# JSON carries workspaceKey (grouping identity) and workspaceLabel (display name)
tokscale models --json --group-by workspace,model --merge-worktrees

In the TUI, press g → Workspace + Model, then w to toggle worktree rollup (the footer shows [w:worktrees] or [w:repos]).

Workspace rows are labeled repo or repo ⑃ worktree. Clients disagree about how they record a workspace — Claude Code stores a dash-mangled directory slug (-Users-me-devpro-app) while Codex and OpenCode store real paths — so tokscale resolves slugs back to their true path against the filesystem. Four consequences worth knowing:

• Without --merge-worktrees, each git worktree is its own row. Agent CLIs that isolate every task into a worktree will therefore spread one repository across many rows; --merge-worktrees re-unites them (and also merges a repo recorded by different clients under different key formats).
• --merge-worktrees finds worktrees kept inside the repo and beside it. <repo>/.claude/worktrees/<name> (what agent CLIs create) and <repo>/.git/worktrees/<name> are recognized from the path alone; a worktree checked out elsewhere (git worktree add ../feature-x) is recognized by reading its .git pointer file back to the repository. A repo reached through two different path spellings (a symlink and its target) still stays two rows, because a workspace identity is compared as a string. Totals are unaffected either way — usage is split across rows, never lost or double counted.
• Rows that would show the same name are qualified with their parent directory. A label is the directory's own name, so ~/work/api and ~/oss/api would both read api; colliding labels gain as many leading path segments as it takes to tell them apart (work/api, oss/api), and when no path segment can — the same directory recorded by two clients under different key formats — the row is qualified with its workspace key instead. Grouping is unaffected — this only changes the displayed text.
• Clients that never record a workspace roll up into a single Unknown workspace row. Roughly half the supported clients (including gemini, cursor, amp, droid, roocode, kilocode, goose, and Copilot's OTEL path) do not write one, so their usage cannot be attributed to a directory.

Filtering by Platform

Use --client (short -c) to scope reports to one or more clients. The flag is repeatable, accepts comma-separated values, and works with every report command:

# Show only OpenCode usage
tokscale --client opencode

# Comma-separated: combine multiple clients
tokscale --client opencode,claude

# Repeated: same effect, useful with shell aliases
tokscale -c opencode -c claude

# Cursor IDE uses Tokscale's API cache; run login + sync --json first
tokscale --client cursor

# Synthetic (synthetic.new) is detected from other agent sessions
tokscale --client synthetic

# Combine with other filters
tokscale --client opencode,claude --week --json

Possible values: opencode, claude, codex, copilot, gemini, cursor, amp, codebuff, droid, openclaw, hermes, pi, prime-agent, kimchi, kimi, qwen, roocode, kilocode, kilo, mux, crush, goose, antigravity, antigravity-cli, zed, kiro, trae, warp, cline, gjc, grok, jcode, micode, commandcode, junie, zcode, opencodereview, codebuddy, augment, synthetic, cherrystudio, lmstudio, unsloth, hindsight.

Breaking change (v4.0.0): The per-client boolean flags (--opencode, --claude, --codex, etc.) have been removed and now error. Use the canonical --client/-c flag instead — e.g. tokscale --client opencode,claude.

Date Filtering

Date filters work across all commands that generate reports (tokscale, tokscale models, tokscale monthly, tokscale graph):

# Quick date shortcuts
tokscale --today              # Today only
tokscale --yesterday          # Yesterday only
tokscale --week               # Last 7 days
tokscale --month              # Current calendar month

# Custom date range (inclusive, local timezone)
tokscale --since 2024-01-01 --until 2024-12-31

# Filter by year
tokscale --year 2024

# Combine with other options
tokscale models --week --client claude --json
tokscale monthly --month --benchmark

Note: Date filters use your local timezone. Both --since and --until are inclusive. v2.2.0 note: Session active-time daily buckets also use your local timezone, so users outside UTC may see active-time dates align with local token/cost report days instead of UTC day boundaries.

Pricing Lookup

Look up real-time pricing for any model:

# Look up model pricing
tokscale pricing "claude-3-5-sonnet-20241022"
tokscale pricing "gpt-4o"
tokscale pricing "grok-code"

# Force specific provider source
tokscale pricing "grok-code" --provider openrouter
tokscale pricing "claude-3-5-sonnet" --provider litellm

# Inspect custom pricing overrides
tokscale pricing list-overrides

Lookup Strategy:

The pricing lookup uses a multi-step resolution strategy:

1. Custom Pricing Overrides - Exact user-defined entries from ~/.config/tokscale/custom-pricing.json
2. Exact Match - Direct lookup in LiteLLM/OpenRouter databases
3. Alias Resolution - Resolves friendly names (e.g., big-pickle → glm-4.7)
4. Tier Suffix Stripping - Removes quality tiers (gpt-5.2-xhigh → gpt-5.2)
5. Version Normalization - Handles version formats (claude-3-5-sonnet ↔ claude-3.5-sonnet)
6. Provider Prefix Matching - Tries common prefixes (anthropic/, openai/, etc.)
7. Cursor Model Pricing - Hardcoded pricing for models not yet in LiteLLM/OpenRouter (e.g., gpt-5.3-codex)
8. Fuzzy Matching - Word-boundary matching for partial model names

Custom Pricing Overrides

Create custom-pricing.json in Tokscale's config directory (~/.config/tokscale/custom-pricing.json on macOS/Linux by default; the same directory resolved by TOKSCALE_CONFIG_DIR when set) to override prices for model IDs that upstream pricing databases do not yet cover correctly.

{
  "$schema": "https://tokscale.ai/custom-pricing.schema.json",
  "models": {
    "accounts/fireworks/routers/kimi-k2p6-turbo": {
      "input_cost_per_million_tokens": 2.00,
      "output_cost_per_million_tokens": 8.00,
      "cache_read_input_token_cost_per_million_tokens": 0.30,
      "source": "https://docs.fireworks.ai/serverless/pricing",
      "notes": "Fireworks Kimi K2.6 Turbo (preview)"
    },
    "accounts/fireworks/models/kimi-k2p6": {
      "input_cost_per_million_tokens": 0.95,
      "output_cost_per_million_tokens": 4.00,
      "cache_read_input_token_cost_per_million_tokens": 0.16
    },
    "kimi-k2p6-turbo": {
      "input_cost_per_million_tokens": 2.00,
      "output_cost_per_million_tokens": 8.00
    }
  }
}

Override prices are entered in dollars per million tokens, matching how most API providers publish pricing; Tokscale converts them to per-token rates internally. At least one of input_cost_per_million_tokens or output_cost_per_million_tokens must be present, and cache-read/cache-creation fields are optional. An explicit 0 is allowed and is the way to declare a free model — it is a statement ("this costs nothing"), unlike an omitted field, which means the rate is unknown and leaves the usage unpriced. LiteLLM-style per-token field names such as input_cost_per_token, output_cost_per_token, and cache_read_input_token_cost are also accepted for copy/paste compatibility, but the per-million names are the recommended user-facing form. To omit a tier or cache price, leave the field out; negative or non-finite values are treated as invalid and the whole model entry is skipped so typos do not silently alter accounting. Optional source and notes fields are ignored by Tokscale and can be used for your own bookkeeping.

Overrides are exact-only and case-insensitive. Tokscale checks the raw model ID first, then the existing synthetic /models/ normalization, then falls through to LiteLLM, OpenRouter, Cursor pricing, and fuzzy matching if no override matches. Raw exact matches beat normalized exact matches, so accounts/fireworks/routers/kimi-k2p6-turbo can override one gateway-specific model while kimi-k2p6-turbo can cover normalized /models/ paths. Overrides are loaded once at startup; restart the command after editing the file. This is the recommended local fix for wrong-model pricing bugs while waiting on upstream LiteLLM pricing updates.

Provider Preference:

When multiple matches exist, original model creators are preferred over resellers:

Example: grok-code matches xai/grok-code-fast-1 ($0.20/$1.50) instead of azure_ai/grok-code-fast-1 ($3.50/$17.50).

Social

# Login to Tokscale (opens browser for GitHub auth)
tokscale login

# Save an existing Tokscale API token without browser auth
tokscale login --token tt_xxx

# Check who you're logged in as
tokscale whoami

# Display your saved API token as a QR code (useful for sharing to another device)
# Encodes {"token":"tt_xxx","username":"..."} — scan with any QR reader
tokscale qr

# Submit your usage data to the leaderboard
tokscale submit

# Submit in CI/headless environments without writing credentials
# Precedence: TOKSCALE_API_TOKEN env > saved credentials file (~/.config/tokscale/credentials.json).
# When the env var is set, the saved file is ignored for that invocation.
TOKSCALE_API_TOKEN=tt_xxx tokscale submit

# Revoke a token: visit Settings > API Tokens on the leaderboard site
# (https://tokscale.ai/settings) and click "Revoke" on the token row.
# Revocation takes effect immediately — subsequent requests with that
# token will get HTTP 401 "Invalid API token".

# Submit with filters
tokscale submit --client opencode,claude --since 2