junhoyeo/tokscale

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

[!TIP]

v2 is here — native Rust TUI, cross-platform support, and more.
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.

Overview	Models

Daily Summary	Stats

Frontend (3D Contributions Graph)	Wrapped 2025

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:

Logo	Client	Data Location	Supported
	OpenCode	~/.local/share/opencode/opencode.db (1.2+, all channels including opencode-stable.db) or/and ~/.local/share/opencode/storage/message/ (legacy/unmigrated)	✅ Yes
	Claude Code	~/.claude/projects/ and ~/.claude/transcripts/	✅ Yes
	OpenClaw	~/.openclaw/agents/ (+ legacy: .clawdbot, .moltbot, .moldbot)	✅ Yes
	Codex CLI	~/.codex/sessions/	✅ Yes
	Sakana Fugu	via Codex — ~/.codex/sessions/*.jsonl (model_provider: sakana)	✅ Yes
	GitHub Copilot CLI	~/.copilot/otel/*.jsonl (+ COPILOT_OTEL_FILE_EXPORTER_PATH)	✅ Yes
	Hermes Agent	$HERMES_HOME/state.db (fallback: ~/.hermes/state.db)	✅ Yes
	Gemini CLI	$GEMINI_CLI_HOME/tmp/*/chats/*.json (fallback: ~/.gemini/tmp/*/chats/*.json)	✅ Yes
	Cursor IDE	Cursor API export cached at ~/.config/tokscale/cursor-cache/usage*.csv (not ~/.cursor)	✅ Yes
	Amp (AmpCode)	~/.local/share/amp/threads/	✅ Yes
	Codebuff	~/.config/manicode/ (+ manicode-dev, manicode-staging; override via CODEBUFF_DATA_DIR)	✅ Yes
	Droid (Factory Droid)	~/.factory/sessions/	✅ Yes
	Pi	~/.pi/agent/sessions/ and ~/.omp/agent/sessions/ (Oh My Pi)	✅ Yes
	Kimi CLI / Kimi Code	kimi-cli: ~/.kimi/sessions/ kimi-code: ~/.kimi-code/sessions/ (override via KIMI_CODE_HOME)	✅ Yes
	Qwen CLI	~/.qwen/projects/	✅ Yes
	Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/)	✅ Yes
	Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/)	✅ Yes
	Kilo CLI	~/.local/share/kilo/kilo.db	✅ Yes
	Mux	~/.mux/sessions/	✅ Yes
	Crush	$XDG_DATA_HOME/crush/projects.json (project registry; fallback: ~/.local/share/crush/projects.json)	✅ Yes
	Goose	~/.local/share/goose/sessions/sessions.db (+ macOS Application Support, legacy Block/goose paths; override via GOOSE_PATH_ROOT)	✅ Yes
	Google Antigravity	Cached via tokscale antigravity sync to ~/.config/tokscale/antigravity-cache/sessions/*.jsonl (live RPC against the local language server)	✅ Yes
	Antigravity CLI	~/.gemini/antigravity-cli/conversations/*.db (override the Gemini home via GEMINI_CLI_HOME; local SQLite, read directly — no antigravity sync needed)	✅ Yes
	Trae IDE / Trae Solo (international)	Cached via tokscale trae sync to ~/.config/tokscale/trae-cache/sessions/*.json (account-level usage from the official API)	✅ Yes
	Warp / Oz	Cached via tokscale warp sync to ~/.config/tokscale/warp-cache/usage.json (aggregate requests and spend only; no token transcripts)	✅ Yes
	Grok Build	$GROK_HOME/sessions/*/*/updates.jsonl (fallback: ~/.grok/sessions/*/*/updates.jsonl)	✅ Yes
	Zed Agent	~/.local/share/zed/threads/threads.db (macOS: ~/Library/Application Support/Zed/threads/threads.db; Windows: %LOCALAPPDATA%/Zed/threads/threads.db; hosted Zed models only, not external ACP agents)	✅ Yes
	Kiro	~/.kiro/sessions/cli/*.json (+ *.jsonl), ~/.local/share/kiro-cli/data.sqlite3 (macOS: ~/Library/Application Support/kiro-cli/data.sqlite3), and Kiro IDE globalStorage snapshots (Kiro/User/globalStorage/kiro.kiroagent; macOS Application Support, Linux ~/.config/Kiro, Windows %APPDATA%\Kiro)	✅ Yes
	Cline	VS Code globalStorage tasks (Linux: ~/.config/Code/...; macOS: ~/Library/Application Support/Code/...; Windows: %APPDATA%\Code\...; server: ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/tasks/)	✅ Yes
	gajae-code (gjc)	~/.gjc/agent/sessions/ (override via GJC_CODING_AGENT_DIR, GJC_CONFIG_DIR, PI_CONFIG_DIR; $XDG_DATA_HOME/gjc/sessions/ on Linux/macOS)	✅ Yes
	Jcode	~/.jcode/sessions/session_*.json + session_*.journal.jsonl sidecars (override via JCODE_HOME)	✅ Yes
	MiMo Code	~/.local/share/mimocode/mimocode.db (XDG data dir; SQLite)	✅ Yes
	Junie	~/.junie/sessions/*/events.jsonl	✅ Yes
	Command Code	~/.commandcode/projects/**/*.jsonl (token usage estimated from transcripts at ~4 chars/token; not persisted on disk)	✅ Yes
	ZCode	~/.zcode/cli/db/db.sqlite (v2 usage database) and ~/.zcode/projects/**/*.jsonl (legacy transcripts)	✅ Yes
	OpenCodeReview	~/.opencodereview/sessions/**/*.jsonl	✅ Yes
	CodeBuddy (CLI, IDE, VS Code plugin)	~/.codebuddy/projects/**/*.jsonl + extension logs	✅ Yes
	WorkBuddy	~/.workbuddy/projects/**/*.jsonl + SQLite fallback	✅ Yes
	Synthetic	Re-attributed from other sources via hf: model prefix or synthetic provider (+ Octofriend: ~/.local/share/octofriend/sqlite.db)	✅ Yes

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
• 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, Copilot CLI, Cursor IDE, Gemini CLI, Amp, Codebuff, Droid, OpenClaw, Hermes Agent, Pi, Kimi CLI, 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, and Synthetic
• Multi-platform support - Track usage across OpenCode, Claude Code, Codex CLI, Copilot CLI, Cursor IDE, Gemini CLI, Amp, Codebuff, Droid, OpenClaw, Hermes Agent, Pi, Kimi CLI, 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, WorkBuddy, and Synthetic
• 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)
• 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
  • 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).

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, 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, synthetic.

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 positive, and cache-read/cache-creation fields are optional. 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 2024-01-01

# Preview what would be submitted (dry run)
tokscale submit --dry-run

# Logout
tokscale logout

Autosubmit

Autosubmit schedules the normal tokscale submit flow with the operating system scheduler. It is useful for keeping your public profile current without a manual terminal run.

# Enable periodic submission. Uses launchd on macOS, systemd user timers on Linux
# when available, cron as a Linux fallback, and Windows Task Scheduler on Windows.
tokscale autosubmit enable --interval 24h

# Keep the same client and date filters you would pass to submit.
tokscale autosubmit enable --interval 2h --client opencode,claude --week

# Show saved settings and the last run/error.
tokscale autosubmit status
tokscale autosubmit status --json

# Run once now, even if the saved interval has not elapsed.
tokscale autosubmit run --force

# Disable autosubmit and remove the scheduler entry.
tokscale autosubmit disable

Scheduled runs are non-interactive: they never prompt for GitHub auth or star confirmation. Run tokscale login --token tt_xxx once, or set TOKSCALE_API_TOKEN in the scheduler environment. Tokscale records scheduler state in settings.json, writes logs under ~/.config/tokscale/autosubmit/, and uses a lock file so overlapping scheduler ticks do not submit twice.

Cursor IDE Commands

Cursor IDE support uses Cursor's web API export, cached by Tokscale at ~/.config/tokscale/cursor-cache/usage*.csv. Tokscale does not parse local Cursor Agent CLI state under ~/.cursor.

Setup:

1. Open https://www.cursor.com/settings in your browser and sign in.
2. Copy the WorkosCursorSessionToken cookie value:
   • Network tab: make any request to cursor.com/api/*, then copy the value after WorkosCursorSessionToken= from the Cookie request header.
   • Application tab: open Cookies -> https://www.cursor.com, then copy the WorkosCursorSessionToken value.
3. Run tokscale cursor login --name work and paste the token.
4. Run tokscale cursor sync --json to populate ~/.config/tokscale/cursor-cache/usage.csv.
5. Run tokscale --client cursor or any report command.

Treat the session token like a password. It is stored locally in ~/.config/tokscale/cursor-credentials.json.

# Login to Cursor (requires session token from browser)
# --name is optional; it just helps you identify accounts later
tokscale cursor login --name work

# Check Cursor authentication status and session validity
tokscale cursor status

# List saved Cursor accounts
tokscale cursor accounts

# Manually refresh cached Cursor usage
tokscale cursor sync --json

# Switch active account (controls which account syncs to cursor-cache/usage.csv)
tokscale cursor switch work

# Logout from a specific account (keeps history; excludes it from aggregation)
tokscale cursor logout --name work

# Logout and delete cached usage for that account
tokscale cursor logout --name work --purge-cache

# Logout from all Cursor accounts (keeps history; excludes from aggregation)
tokscale cursor logout --all

# Logout from all accounts and delete cached usage
tokscale cursor logout --all --purge-cache

By default, Tokscale aggregates usage across all saved Cursor accounts by reading cursor-cache/usage*.csv. The active account syncs to usage.csv; additional accounts sync to usage.<account>.csv.

When you log out, Tokscale moves cached usage to cursor-cache/archive/ so it is no longer aggregated. Use --purge-cache to delete cached usage instead.

Antigravity Commands

Antigravity sync currently works on macOS and Linux only. The Antigravity-enabled editor must be running and its local language server available; tokscale reads usage from that local language server and caches normalized artifacts locally.

# Check whether tokscale can see running Antigravity language servers
tokscale antigravity status

# Sync usage from local Antigravity language servers into tokscale's cache
tokscale antigravity sync

# Delete the cached Antigravity artifacts
tokscale antigravity purge-cache

Cache location: ~/.config/tokscale/antigravity-cache/

How it works: tokscale antigravity sync discovers local Antigravity session candidates, fetches confirmed usage data from the local language server RPC, and stores normalized JSONL artifacts for tokscale-core to parse later. Run sync before reports if you want the freshest Antigravity data.

Trae Commands

Trae (ByteDance's AI IDE) ships in two international product lines — Trae IDE and Trae Solo. They share the same account-level usage data (same backend, same JWT), so tokscale reports them as a single trae client. You can install either or both desktop apps; tokscale auto-discovers credentials from whichever is present.

Credentials are identified per desktop app via --variant:

• --variant ide — credentials from Trae IDE (~/Library/Application Support/Trae/)
• --variant solo — credentials from Trae Solo (~/Library/Application Support/TRAE SOLO/)

tokscale trae sync calls the official query_user_usage_group_by_session API exactly once per run (regardless of how many desktop apps are installed) and persists the raw JSON to a local cache.

# Log in (auto-detects credentials from any installed Trae desktop client)
tokscale trae login

# Manual JWT entry (for environments where auto-detect can't find storage.json,
# e.g. Linux/Windows or a headless server). Open https://www.trae.ai/account-setting#usage
# in your browser, then F12 → Network → filter `query_user_usage` and copy the
# `Authorization` header value.
tokscale trae login --manual --variant solo

# Show which variants have cached credentials
tokscale trae status

# Sync usage (uses the first available credential source)
tokscale trae sync --since 30

# Forget cached credentials for one variant
tokscale trae logout --variant solo

Cache location: ~/.config/tokscale/trae-cache/

How it works: tokscale either decrypts the desktop client's iCubeAuthInfo://* blob (globalStorage/storage.json) to recover a JWT, or accepts one pasted via --manual. It then calls POST /trae/api/v1/pay/query_user_usage_group_by_session paginated and stores the raw JSON. Run sync before reports if you want the freshest Trae data.

Note on pricing: Trae cost figures are vendor-reported — tokscale surfaces the dollar_float value returned by Trae's own API rather than recomputing cost from token counts through tokscale's pricing engine. Numbers will match what you see on trae.ai/account-setting#usage, not what tokscale would otherwise calculate for the same usage.

China variants: The China editions (trae.com.cn) are intentionally not supported. The CN backend does not expose a session-level usage query API. Trae CN / Trae Solo CN support will be added once an official endpoint becomes available upstream.

Warp/Oz Commands

Warp/Oz does not expose local token transcripts. Tokscale only syncs the aggregate request and spend counters returned by Warp's GraphQL API, then reports them as warp / aggregate-requests rows with zero token buckets.

# Save a bearer token or Cookie header copied from an authenticated Warp request
tokscale warp login

# Inspect credential/cache state and diagnostics
tokscale warp status

# Sync aggregate requests and spend into tokscale's local cache
tokscale warp sync

# Remove saved credentials; add --purge-cache to delete synced usage too
tokscale warp logout --purge-cache

Cache location: ~/.config/tokscale/warp-cache/usage.json

How it works: tokscale warp sync calls Warp's authenticated GraphQL API for account and workspace aggregate counters. Tokscale preserves request counts as message counts and vendor-reported spend as cost, but it never converts requests into synthetic tokens. Warp is excluded from default submit data because the public leaderboard accepts token-attributed usage, not aggregate request counters.

Task-Attributed Report

The report command generates a task-attributed usage breakdown. It uses an LLM to summarize each session into a short title and category, then groups related sessions into high-level task clusters for a bird's-eye view of where your tokens went.

# Basic report (today, default Apple FM summarizer)
tokscale report

# Last 7 days
tokscale report --week

# Use Claude Code as the summarizer backend
tokscale report --week --summarizer claude

# Use Codex, Gemini, or Kiro
tokscale report --summarizer codex
tokscale report --summarizer gemini
tokscale report --summarizer kiro

# Skip LLM summarization (show raw data only)
tokscale report --no-summarize

# Re-summarize from scratch (resets cached summaries in range)
tokscale report --week --rebuild

# Output as JSON
tokscale report --week --json

# Filter by workspace or client
tokscale report --workspace my-project --client opencode

Summarizer backends:

How it works:

1. Sessions are scanned and inserted into a local SQLite wiki database (wiki.db in your platform config dir — e.g. ~/.config/tokscale/ on Linux, ~/Library/Application Support/tokscale/ on macOS)
2. Unsummarized sessions are sent to the chosen LLM backend in batches, which returns a title, category, description, and complexity for each
3. A second LLM pass groups all titled sessions into 3–8 high-level task clusters (e.g. "Kiro Auth", "Tokscale Report", "System Config")
4. Results are cached in the wiki DB — subsequent runs skip already-summarized sessions

Example output:

  Task Group                                  Sess     Tokens     Cost
  ───────────────────────────────────────────────────────────────────────
  Tokscale Development                          19      4.2B    $22.66
    Add task-attributed report command
    Implement wiki DB schema
    Fix pricing lookup for new models
  System Config                                 28      2.1B    $10.06
    Configure OpenCode workspace settings
    Update shell aliases
  Kiro Auth                                      4    890.5M     $3.10
    Implement JWT refresh flow

Subscription Usage

Tokscale can fetch and display your real-time subscription quota across AI providers. This shows how much of your plan you've used and when limits reset.

# Show subscription usage for all detected providers
tokscale usage

# Output as JSON (for scripting)
tokscale usage --json

# Lightweight terminal output (no TUI)
tokscale usage --light

In the TUI, navigate to the Usage tab to see subscription data. Use [Refresh] to refresh subscription quotas. The keyboard refresh shortcut r uses the same refresh path.

Note: Subscription quotas and balances are vendor-reported — tokscale calls each provider's own quota endpoint and surfaces the response verbatim. Numbers reflect what the provider reports (which is also what shows up in their official dashboards) and are not independently verified against tokscale's own usage tracking.

Supported Providers

Providers are auto-detected — only those with valid credentials are shown. If a provider is missing, ensure you've logged in or set the required environment variable.

Codex Multi-Account Usage

Tokscale can save multiple Codex OAuth accounts for subscription usage display. The TUI Usage tab groups saved accounts under one Codex section. The active account is marked with *; inactive accounts can be selected with [Use]; account removal uses [Remove] followed by [Confirm].

To add an account without leaving the TUI, click [Add Codex] in the Usage tab. Tokscale starts codex login with a temporary CODEX_HOME, displays the login output in the Usage tab, imports the resulting auth into Tokscale's saved account store, and then refreshes usage. This keeps the login isolated and does not switch the current Codex auth; click [Use] on a saved account when you want Tokscale to write that account into the real Codex auth file.

The CLI commands are still available for scripted or manual account management:

# Save the current Codex auth as a named Tokscale account
tokscale codex import --name work

# List saved Codex accounts
tokscale codex accounts
tokscale codex accounts --json

# Switch the active Codex account and write Codex auth.json
tokscale codex switch work

# Stop tracking a saved Codex account (removes it from Tokscale's store
# only — the codex CLI's own auth.json/login is never touched)
tokscale codex remove personal

# Check subscription usage for the active or a named account
tokscale codex status
tokscale codex status --name personal --json

When saved Codex accounts exist, tokscale usage --json includes structured account metadata for each Codex entry and the TUI displays those entries under one Codex group. Without saved accounts, Tokscale falls back to the current Codex auth discovery path (CODEX_HOME/auth.json, ~/.config/codex/auth.json, ~/.codex/auth.json, then macOS Keychain).

Example Output

╭──────────────────────────────────────────────────────────╮
│ Session    85% left  [=========---] resets in 2h 15m     │
│ Weekly     72% left  [========----] resets Fri 3pm       │
│ Plan     Max 20x                                         │
╰──────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────╮
│ Session    40% left  [=====-------] resets in 4h 30m     │
│ Weekly     90% left  [==========--] resets Mon 12am      │
│ Account  user@example.com                                │
│ Plan     Pro                                             │
╰──────────────────────────────────────────────────────────╯

Example Output (--light version)

Configuration

Tokscale stores settings in ~/.config/tokscale/settings.json:

{
  "colorPalette": "blue",
  "includeUnusedModels": false,
  "defaultClients": ["opencode", "claude"],
  "scanner": {
    "extraScanPaths": {
      "codex": [
        "/Users/me/workspace/project-a/.codex/sessions",
        "/Users/me/workspace/project-b/.codex/archived_sessions"
      ],
      "hermes": [
        "/Users/me/.hermes/profiles/director_planning",
        "/Users/me/.hermes/profiles/research/state.db"
      ]
    }
  }
}

README truncated. Continue reading on GitHub