junhoyeo/tokscale

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 @Tokscale on X for release notes and updates.
	Come hang out in our Discord — and surround yourself with the world's top-tier vibers.
	Support Tokscale's continued development through GitHub Sponsors.
	Follow @junhoyeo on GitHub for more projects. Hacking on AI, infra, and everything in between.

Overview	Models

Daily Summary	Stats

Session Details	Hourly

Frontend (3D Contributions Graph)	Wrapped 2025

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

Tokscale helps you monitor and analyze your token consumption from:

Logo	Client	Data Location
	OpenCode	~/.local/share/opencode/opencode.db (1.2+, all channels including opencode-stable.db) or/and ~/.local/share/opencode/storage/message/ (legacy/unmigrated)
	Claude Code	~/.claude/projects/ and ~/.claude/transcripts/
	OpenClaw	~/.openclaw/agents/ (*/agent/openclaw-agent.sqlite + */sessions/*.jsonl; + legacy: .clawdbot, .moltbot, .moldbot)
	Codex CLI	~/.codex/sessions/ and ~/.codex/archived_sessions/ (*.jsonl plus zstd-compressed *.jsonl.zst and other archive copies; copies of one rollout count once)
	Prime Agent	~/.prime/agent/sessions/ and ~/.prime/agent/session-artifacts/ (RLM child sessions)
	Sakana Fugu	via Codex — rollouts in ~/.codex/sessions/ and ~/.codex/archived_sessions/ (model_provider: sakana)
	GitHub Copilot CLI	~/.copilot/session-store.db (CLI usage events; no OTEL required), ~/.copilot/otel/*.jsonl (+ COPILOT_OTEL_FILE_EXPORTER_PATH), ~/.copilot/data.db
	Hermes Agent	$HERMES_HOME/state.db and $HERMES_HOME/profiles/*/state.db (fallback: ~/.hermes/...)
	Gemini CLI	$GEMINI_CLI_HOME/tmp/*/chats/*.json (fallback: ~/.gemini/tmp/*/chats/*.json)
	Cursor IDE	Cursor API usage cached at ~/.config/tokscale/cursor-cache/usage*.json (legacy usage*.csv caches are still read; desktop auto-login or cookie paste; not ~/.cursor)
	Amp (AmpCode)	~/.config/tokscale/amp-cache/threads/ (tokscale amp sync)
	Codebuff	~/.config/manicode/ (+ manicode-dev, manicode-staging; override via CODEBUFF_DATA_DIR)
	Freebuff	shares ~/.config/manicode/ with Codebuff (same runtime); token usage is estimated from the transcript (no local usage; override via FREEBUFF_DATA_DIR)
	Droid (Factory Droid)	~/.factory/sessions/
	Pi	~/.pi/agent/sessions/
	omp (Oh My Pi)	~/.omp/agent/sessions/**/*.jsonl
	Senpi (OmO Native)	~/.senpi/agent/sessions/ (override via SENPI_CODING_AGENT_DIR) and ~/.omo/agent/sessions/ (OmO Native, omo-ai 5.1.0+), plus each project's task children in .omo/senpi-task/children/; add other OmO locations with scanner.extraScanPaths.senpi
	Kimchi Coding	~/.config/kimchi/harness/sessions/ (override via KIMCHI_CODING_AGENT_DIR)
	Reasonix	~/.reasonix/stats/*.jsonl (override via REASONIX_STATE_HOME or REASONIX_HOME)
	Kimi CLI / Kimi Code	kimi-cli: ~/.kimi/sessions/ kimi-code: ~/.kimi-code/sessions/ (override via KIMI_CODE_HOME) kimi-work: desktop app-data root (auto-discovered)
	Qwen CLI	~/.qwen/projects/
	Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/)
	Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/)
	Kilo CLI	~/.local/share/kilo/kilo.db
	Mux	~/.mux/sessions/
	Crush	$XDG_DATA_HOME/crush/projects.json (project registry; fallback: ~/.local/share/crush/projects.json)
	Goose	~/.local/share/goose/sessions/sessions.db / %APPDATA%\Block\goose\data\sessions\sessions.db (+ macOS Application Support, legacy Block/goose paths; override via GOOSE_PATH_ROOT)
	Google Antigravity	Cached via tokscale antigravity sync to ~/.config/tokscale/antigravity-cache/sessions/*.jsonl (live RPC against the local language server)
	Antigravity CLI	~/.gemini/antigravity-cli/conversations/*.db (override the Gemini home via GEMINI_CLI_HOME; local SQLite, read directly — no antigravity sync needed)
	Antigravity IDE Extension	~/.gemini/antigravity/conversations/*.db (local SQLite, read directly)
	Trae IDE / Trae Solo (international)	Cached via tokscale trae sync to ~/.config/tokscale/trae-cache/sessions/*.json (account-level usage from the official API)
	Warp / Oz	Cached via tokscale warp sync to ~/.config/tokscale/warp-cache/usage.json (aggregate requests and spend only; no token transcripts)
	Grok Build	$GROK_HOME/sessions/*/*/updates.jsonl (fallback: ~/.grok/sessions/*/*/updates.jsonl)
	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)
	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)
	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/) + Cline CLI sessions (first available root, in order: $CLINE_SESSION_DATA_DIR, $CLINE_DATA_DIR/sessions/, $CLINE_DIR/data/sessions/, fallback ~/.cline/data/sessions/; blank/whitespace-only environment values are ignored)
	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)
	Cherry Studio	%APPDATA%\CherryStudio\Data\Agents\.claude\projects\*.jsonl and legacy %APPDATA%\CherryStudio\.claude\projects\*.jsonl (macOS: ~/Library/Application Support/CherryStudio/Data/Agents/.claude/projects/; Linux: $XDG_CONFIG_HOME/CherryStudio/Data/Agents/.claude/projects/; Agent / Claude Code mode transcripts; V2 root preferred, legacy keeps untransferred history) plus the chat ledger at %APPDATA%\CherryStudio\Data\cherrystudio.sqlite (macOS: ~/Library/Application Support/CherryStudio/Data/cherrystudio.sqlite; Linux: $XDG_CONFIG_HOME/CherryStudio/Data/cherrystudio.sqlite; ai_usage_record rows for the built-in chat and assistant surfaces, which write no transcript; Agent-mode rows in that table are skipped because the transcripts already report them, and both ledgers count toward the same client)
	LM Studio	~/.lmstudio/server-logs/**/*.log (LM_STUDIO_HOME supported; Chat Completions and Responses API final-response usage only; prompts and responses are not retained; local inference cost is $0)
	Unsloth Studio	$UNSLOTH_STUDIO_HOME/studio.db (fallback: ~/.unsloth/studio/studio.db; exact internal-chat and authenticated API inference usage; message content is not read; training metrics are excluded; local inference cost is $0)
	Hindsight	$HINDSIGHT_HOME/usage/*.jsonl (fallback: ~/.hindsight/usage/*.jsonl; populated via tokscale hindsight sync)
	Jcode	~/.jcode/sessions/session_*.json + session_*.journal.jsonl sidecars (override via JCODE_HOME)
	MiMo Code	~/.local/share/mimocode/mimocode.db (XDG data dir; SQLite)
	Xiaomi MiMo AI (desktop)	Same ~/.local/share/mimocode/mimocode.db store as MiMo Code; sessions are split by session.version (desktop- prefix → micode-desktop)
	Junie	~/.junie/sessions/*/events.jsonl
	Command Code	~/.commandcode/projects/**/*.jsonl (v3 transcripts persist per-request usage and cost; estimated fallback only for legacy transcripts without a usage block)
	ZCode	~/.zcode/cli/db/db.sqlite (v2 usage database) and ~/.zcode/projects/**/*.jsonl (legacy transcripts)
	OpenCodeReview	~/.opencodereview/sessions/**/*.jsonl
	CodeBuddy (CLI, IDE, VS Code plugin)	~/.codebuddy/projects/**/*.jsonl + extension logs
	WorkBuddy	~/.workbuddy/projects/**/*.jsonl (5.5+ under ~/.workbuddy-ai/) + SQLite fallback
	Devin CLI	~/.local/share/devin/cli/sessions.db (SQLite)
	Devin Desktop	ACP events: macOS ~/Library/Application Support/Devin/User/acp-events/; Linux ~/.config/Devin/User/acp-events/; Windows %APPDATA%\Devin\User\acp-events\
	Augment Code (Auggie CLI)	~/.augment/sessions/*.json
	Synthetic	Re-attributed from other sources via hf: model prefix or synthetic provider (+ Octofriend: ~/.local/share/octofriend/sqlite.db)
	DeepSeek Harness	~/.dsh/sessions/**/session.jsonl.zstd (or session.jsonl when written uncompressed, plus versioned session.v<N>.jsonl[.zstd] spellings; override via DSH_HOME)
	MiniMax Code	~/.config/tokscale/headless/mcode/*.jsonl (headless capture of mcode exec --output-format stream-json; override via TOKSCALE_HEADLESS_DIR)
	fx	~/.fx/sessions/<sessionId>/usage-v2.json (per-session aggregates)
	Muse Code	~/.local/share/muse/sessions/**/session.jsonl (same XDG-style path on Windows; subagent transcripts under subagent/<uuid>/ included)
	Aside	~/.aside/u/<account>/sessions/<session>/messages.jsonl
	Mistral Vibe	~/.vibe/logs/session/<session-dir>/meta.json (same path on Windows; override the root via VIBE_HOME)

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

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.

• 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
• Local Usage Recovery Ledger
• Contributing
  • Development Guidelines
• Acknowledgments
• License

• Interactive TUI Mode - Beautiful terminal UI powered by Ratatui (default mode)
  • 10 interactive views: Overview, Usage, Models, Daily, Hourly, Monthly, Sessions, Projects, 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, Antigravity IDE Extension, Zed, Kiro, Trae, Warp/Oz, Cline, Gajae-Code, Grok Build, Jcode, MiMo Code, Xiaomi MiMo AI, Command Code, Junie, ZCode, OpenCodeReview, CodeBuddy, WorkBuddy, Devin CLI, Devin Desktop, Augment Code, Synthetic, Cherry Studio, LM Studio, Unsloth Studio, Hindsight, fx, Oh My Pi, Muse Code, Aside, and Mistral Vibe
• 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

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

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

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.

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.

# 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

The interactive TUI mode provides:

• 10 Views: Overview (chart + top models), Usage (subscription quotas), Models, Daily, Hourly, Monthly, Sessions, Projects (per-workspace rollups), Stats (contribution graph), Agents. In Projects, Codex Desktop's ordinary chat directories (Documents/Codex/YYYY-MM-DD/<chat>) are combined into Codex Chat, preserving their session count, tokens, and cost; directories containing a Git repository remain separate. 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) / per-day trend with ms/1K and Cost/1M (Models 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)
  • b: Toggle subagent session roll-up into parent sessions (Sessions 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)

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

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

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; a signed-in desktop session is imported when no login is saved
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, antigravity-extension, zed, kiro, trae, warp, cline, gjc, grok, jcode, micode, micode-desktop, commandcode, junie, zcode, opencodereview, codebuddy, augment, synthetic, cherrystudio, lmstudio, unsloth, hindsight, muse, aside, vibe.

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

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

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.

{
  "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
    }
  }
}

The JSON schema is available at schemas/custom-pricing.schema.json in this repository. For editor validation, use a local copy of that schema.

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

Custom pricing now supports provider_overrides alongside the existing global models object. Use tokscale pricing MODEL --billing-provider vertex --source custom --json --no-spinner; the old --provider flag still means pricing source. Channels are exact whole log labels (trim + ASCII case-insensitive), not inferred model vendors or verified billing accounts. Unknown channels only use global/upstream estimates.

Run tokscale pricing validate-overrides --strict --json --no-spinner to check configuration offline and tokscale pricing explain --json --no-spinner for local per-message scope, coverage, multiplier and estimate status. Rules are base rates; authoritative costs including zero are preserved. Restart after editing: historical estimates use current rates, while missing/stale prices do not remain in totals. Older binaries ignore scoped rules on downgrade. Full contract, precedence, cache behavior and example.

# 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

Before anything is submitted, every message must resolve to an authoritative price that covers every token bucket the message populated (input, output, cache read, cache write). Messages that cannot be priced are skipped and reported as Warning: excluded N unpriced provider/model message(s) — unknown models never submit invented or guessed spend, and all remaining priced usage still submits normally.

The exclusion reasons:

• no authoritative model-to-price mapping — the model ID is absent from LiteLLM, OpenRouter, models.dev, and your custom overrides.
• generic routing label has no authoritative model-to-price mapping — the ID is a router label (auto, gemini-default, …) whose underlying model varies per request, so it is refused outright. An explicit entry for the label in custom-pricing.json is the supported way to assert a rate you know applies.
• pricing does not cover every populated token bucket — a price row was found, but it is missing a rate (most often cache read or cache creation) that this usage actually populates.
• model price match does not establish the requested provider — a price row was found only by matching the model part of the ID, or by trying a provider prefix, which does not prove your provider bills at that row's rate.
• model price match does not exactly name the requested model — a fuzzy or provider-scoped match was found, but nothing proves the priced key names the model you actually used.
• model price lookup is ambiguous across non-equivalent candidates — several candidate rows matched and they quote different prices.

To include previously excluded usage, add an exact-match entry to custom-pricing.json (see Custom Pricing Overrides) — an explicit 0 declares a genuinely free model — then re-run tokscale submit --dry-run until no warnings remain. tokscale pricing <model-id> shows which entry matched. The file is keyed by the model ID alone — the model half of the provider/model pair shown in the warning.

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 support uses Cursor's usage-events API. Tokscale caches usage at ~/.config/tokscale/cursor-cache/usage.json for the active account and usage.account-<sha256-of-exact-account-id>.json for each other account, with verified ownership metadata. Unmarked legacy JSON/CSV caches are preserved in cursor-cache/archive/ before sync or an account change; see the migration details below. Tokscale does not parse local Cursor Agent CLI state under ~/.cursor, and it does not treat the desktop SQLite DB as a usage ledger.

When the Cursor desktop app is installed and signed in, reports, submit, and wrapped can import cursorAuth/accessToken from state.vscdb when no Cursor login is saved yet. Wrapped only does this when Cursor is included in the requested clients. Reports skip syncing while the usage cache is fresh. Whenever a sync runs, including explicit tokscale cursor sync, it refreshes the desktop token when available and can switch the active account to that desktop login. A saved login remains usable when no desktop session is available. Usage rows still come only from Cursor's usage-events API, not from local ~/.cursor transcripts.

Setup (desktop auto-login):

1. Sign in to the Cursor desktop app.
2. Optional: run tokscale cursor login --name work to save that desktop session under a name. Reports, submit, and sync import it automatically when no Cursor login is saved yet.
3. Optional: run tokscale cursor sync --json to refresh ~/.config/tokscale/cursor-cache/usage.json now. A report syncs on its own when the cache is stale.
4. Run tokscale --client cursor or any report command.

Fallback (manual browser cookie), if desktop login is unavailable:

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 when prompted.
4. Continue with tokscale cursor sync --json as above.

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

# Login to Cursor (auto-detects Cursor desktop login; falls back to browser cookie paste)
# --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

# Give a slow or very large account more time (overall budget in seconds)
tokscale cursor sync --timeout 600

# Switch active account (controls which account syncs to cursor-cache/usage.json)
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*.json. The active account syncs to usage.json; additional accounts use usage.account-<sha256-of-exact-account-id>.json. Each new cache records its account owner, so different IDs cannot share cached history or incremental sync progress merely because their sanitized names match.

On the first sync or account change after upgrading, unmarked legacy JSON and CSV caches cannot prove which account owns their history. Tokscale preserves their original bytes and filenames in unique directories under cursor-cache/archive/, then fetches each account independently from the beginning. These backups are excluded from reports to avoid attributing ambiguous history to the wrong account. If a fetch fails, the backup remains recoverable; reauthenticate that account and sync again. Offline reports can still read legacy caches until this upgrade step runs. A backup failure stops the sync or account change before any cache is overwritten.

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.

tokscale cursor sync downloads each saved account's usage history page by page and gives each account one overall time budget. By default the budget starts at 120 seconds and grows with the number of usage events Cursor reports for the account, up to 1800 seconds (30 minutes). To use a fixed budget instead, pass --timeout <SECONDS> for one run, or save cursor.syncTimeoutSeconds in settings.json (by default ~/.config/tokscale/settings.json; see Configuration for Windows, XDG_CONFIG_HOME and TOKSCALE_CONFIG_DIR). Both take a whole number of seconds from 1 to 86400. If the setting holds any other value, tokscale cursor sync run without --timeout prints a warning and uses the default budget. The flag takes precedence over the setting, and the setting takes precedence over the default budget.

{
  "cursor": {
    "syncTimeoutSeconds": 600
  }
}

When an account has a JSON cache, Cursor sync fetches new usage plus the hour before that account's newest cached event. This bounded overlap refreshes recent billing corrections without downloading the full history on every report. Corrections older than this one-hour window remain as cached; older cached events are preserved, and a first sync without a usable cache still fetches the full history. Each account uses its own cache to determine the window. Only rows accepted by the report parser with positive timestamps no more than five minutes ahead of the sync's start time can set that window or stop pagination; other raw rows are preserved without advancing sync progress. A timed-out delta leaves the cache unchanged so the next sync cannot skip an incomplete interval.

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

Antigravity and Trae syncs use a legacy-compatible sync.lock file to avoid overlapping an older tokscale binary during a rolling upgrade. After a crash or forced stop, that file can remain. Tokscale intentionally fails closed instead of replacing it, because an older binary may still be creating or updating the same path. Confirm that no tokscale antigravity sync or tokscale trae sync process is active, remove the exact quoted sync.lock path printed by the command, then retry. Do not remove the lock while a sync may still be running.

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

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, Kiro, or MiniMax
tokscale report --summarizer codex
tokscale report --summarizer gemini
tokscale report --summarizer kiro
tokscale report --summarizer minimax

# 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

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.

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.

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, plus a separate opt-in account-activity snapshot:

# 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

# Fetch the active Codex app-server account activity separately from local totals
tokscale codex activity
tokscale codex activity --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).

If those native Codex sources produce no successful usage result, Tokscale reads the openai OAuth entry from OpenCode's $XDG_DATA_HOME/opencode/auth.json (normally ~/.local/share/opencode/auth.json). OpenAI API-key entries are not ChatGPT subscription credentials and are ignored. OpenCode credentials are read-only: Tokscale never imports, refreshes, or rewrites them. If the access token is rejected, use OpenCode so it can refresh the login, or reconnect OpenAI with /connect.

tokscale codex activity uses only the installed Codex app-server's active authentication to fetch a timestamped, account-level snapshot. It is supplemental data: it is never included in local totals, reports, exports, submissions, or leaderboards.

╭──────────────────────────────────────────────────────────╮
│ 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                                             │
╰──────────────────────────────────────────────────────────╯

Tokscale stores settings in settings.json in its config directory. By default that is ~/.config/tokscale/settings.json. On Linux it is $XDG_CONFIG_HOME/tokscale/settings.json when XDG_CONFIG_HOME is set, and on Windows it is %APPDATA%\tokscale\settings.json. TOKSCALE_CONFIG_DIR overrides the directory on every platform. If no config directory can be resolved at all, Tokscale falls back to ./.tokscale/settings.json in the current working directory:

{
  "colorPalette": "blue",
  "glyphs": "auto",
  "includeUnusedModels": false,
  "defaultClients": ["opencode", "claude"],
  "usage": {
    "disabledProviders": ["copilot"]
  },
  "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"
      ]
    }
  }
}

Which calendar day a message counts toward depends on a timezone. Tokscale records this device's timezone on first run and reuses it, rather than reading the machine's current timezone on every scan.

This matters because day totals are submitted per day and never allowed to decrease. If the same history were re-bucketed under a different timezone — you travel, you change your system clock, you run in CI with a different TZ — a session near midnight would move to the neighbouring day, and both the old and the new day would keep their value. The total would go up without any new usage. Pinning the zone makes the day boundary stable, so a rescan of unchanged history always produces the same buckets.

$ tokscale config list
timezone     Asia/Seoul

$ tokscale config get timezone
Asia/Seoul

# `set timezone auto` is allowed only before a valid pin exists (or while
# recovering an invalid hand-edited value). It cannot repin an established
# device.
$ tokscale config set timezone auto

Only IANA zone names are accepted. Fixed UTC offsets such as +09:00 are rejected: an offset cannot follow daylight saving time, so a pinned offset stops matching local midnight after a DST transition and re-splits usage near the day boundary — a smaller version of the problem pinning removes.

An established valid pin cannot be changed or unset, including with auto. Historical submitted day rows are monotonic, so re-keying prior usage would permanently double count it. Relocating a device requires a server resync/replacement transition before choosing a different bucket timezone.

Existing installs are unaffected until they pin, and the run that pins reports exactly what it would have reported anyway: the zone recorded is the one the machine was already using.

Use scanner.extraScanPaths for persistent extra roots such as project-level .codex directories or imported Gemini/OpenClaw histories. Tokscale automatically discovers Hermes profile databases under $HERMES_HOME/profiles/*/state.db (or ~/.hermes/profiles/*/state.db when HERMES_HOME is unset). Use scanner.extraScanPaths.hermes only for non-standard Hermes profile locations; entries may point at a profile directory containing state.db or directly at a state.db file. For an OmO Native agent directory outside ~/.omo/agent, add it to scanner.extraScanPaths.senpi; the entry may point at the agent directory or its sessions/ directory (see Senpi (OmO Native)). Tokscale merges these paths with the default scan roots on every run and deduplicates overlapping roots by canonical path.

Use defaultClients to pin a personal default — for example, set it to ["opencode", "claude"] if those are the only clients you use, and tokscale (with no flags) will scope every report to them automatically. Pass --client on the command line to override for a single run.

The Minutely tab shows a per-minute breakdown of token usage and is most useful for diagnosing burst patterns, debugging a single session, or watching activity in near-real-time alongside autoRefreshEnabled. It is hidden by default because the per-minute aggregation runs over every parsed message during data loading, which adds RAM and CPU cost that most users do not need.

To enable it, set minutelyTabEnabled to true in ~/.config/tokscale/settings.json:

{
  "minutelyTabEnabled": true
}

After restart, the Minutely tab appears between Hourly and Stats in the tab strip, and Tab / BackTab / Left / Right navigation cycles through it. Set the flag back to false to hide the tab and skip the aggregation again.

The regenerable CLI/TUI/pricing/Wrapped caches now live under ~/.config/tokscale/cache/ (or ${TOKSCALE_CONFIG_DIR}/cache/ when overridden). Integration sync artifacts remain in client-specific cache roots such as ~/.config/tokscale/antigravity-cache/ and ~/.config/tokscale/trae-cache/:

• tui-data-cache.json — TUI startup cache
• source-message-cache-v2/ + source-message-cache.lock — sharded source-message cache + lock file
• pricing-litellm.json / pricing-openrouter.json — pricing caches
• opencode-migration.json — OpenCode migration record
• fonts/ and images/ — Wrapped asset caches

It is safe to delete this directory. Tokscale will recreate and repopulate it on demand.

One caveat, for Claude Code only. Claude Code rewrites a session transcript in place when you resume or compact it: the file keeps its name but loses assistant turns it had already written. source-message-cache-v2/ remembers those turns for as long as the transcript file exists, so they keep counting toward your totals. That is the only place they still exist — the transcript itself no longer has them. Deleting the cache (or letting a Claude parser upgrade rebuild it) rebuilds from the compacted transcripts, so totals for heavily compacted sessions can come back lower. Deleting a transcript still drops its turns either way, which is what makes local disk the source of truth.

Environment variables override config file values. For CI/CD or one-off use:

# Example: Increase timeout for very large datasets
TOKSCALE_NATIVE_TIMEOUT_MS=600000 tokscale graph --output data.json

# Example: one-off extra scan roots
TOKSCALE_EXTRA_DIRS='codex:/Users/me/workspace/project-a/.codex/sessions,gemini:/Users/me/imports/imac/gemini/tmp' tokscale

# Example: submit from CI without an interactive browser login
TOKSCALE_API_TOKEN=tt_xxx tokscale submit

Note: For persistent extra roots, prefer scanner.extraScanPaths in ~/.config/tokscale/settings.json. TOKSCALE_EXTRA_DIRS is best for one-off overrides or CI/CD.

Tokscale can aggregate token usage from Codex CLI and MiniMax Code headless outputs for automation, CI/CD pipelines, and batch processing.

What is headless mode?

When you run Codex CLI or MiniMax Code with JSON output flags, the CLI writes usage data to stdout. Headless mode captures that stream and keeps it attributable to the originating CLI. MiniMax Code is intentionally read from Tokscale's capture directory rather than its shared Desktop/Runtime session store, whose records do not identify the originating surface.

Storage location: ~/.config/tokscale/headless/

On macOS, Tokscale also scans ~/Library/Application Support/tokscale/headless/ when TOKSCALE_HEADLESS_DIR is not set.

Tokscale automatically scans this directory structure:

~/.config/tokscale/headless/
├── codex/       # Codex CLI JSONL outputs
└── mcode/       # MiniMax Code stream-json outputs

Environment variable: Set TOKSCALE_HEADLESS_DIR to customize the headless log directory:

export TOKSCALE_HEADLESS_DIR="$HOME/my-custom-logs"

Recommended (automatic capture):

Manual redirect (optional):

MiniMax Code usage is counted only when the final exec.result includes model.providerId and model.modelId. Partial captures and older MiniMax Code releases that omit this identity are skipped instead of being priced against a guessed model.

Diagnostics:

# Show scan locations and headless counts
tokscale sources
tokscale sources --json

CI/CD integration example:

# In your GitHub Actions workflow
- name: Run AI automation
  run: |
    mkdir -p ~/.config/tokscale/headless/codex
    codex exec --json "review code changes" \
      > ~/.config/tokscale/headless/codex/pr-${{ github.event.pull_request.number }}.jsonl

# Later, track usage
- name: Report token usage
  run: tokscale --json

Note: Headless capture is supported for Codex CLI and MiniMax Code. If you run either CLI directly, redirect stdout to its matching headless directory as shown above.

The frontend provides a GitHub-style contribution graph visualization:

• 2D View: Classic GitHub contribution calendar
• 3D View: Isometric 3D contribution graph with height based on token usage
• Multiple color palettes: GitHub, GitLab, Halloween, Winter, and more
• 3-way theme toggle: Light / Dark / System (follows OS preference)
• GitHub Primer design: Uses GitHub's official color system
• Interactive tooltips: Hover for detailed daily breakdowns
• Day breakdown panel: Click to see per-source and per-model details
• Year filtering: Navigate between years
• Source filtering: Filter by platform (OpenCode, Claude, Codex, MiniMax Code, Copilot, Cursor, Gemini, Amp, Codebuff, Droid, OpenClaw, Hermes Agent, Pi, Prime Agent, Kimi, Qwen, Roo Code, Kilo, Mux, Kilo CLI, Crush, Goose, Antigravity, Antigravity CLI, Antigravity IDE Extension, Zed, Kiro, Trae, Warp, Cline, Gajae-Code, Grok Build, Jcode, MiMo Code, Xiaomi MiMo AI, Command Code, Junie, ZCode, OpenCodeReview, CodeBuddy, WorkBuddy, Devin CLI, Devin Desktop, Augment Code, Synthetic, Cherry Studio, LM Studio, Unsloth, Hindsight, Muse Code, Aside, Mistral Vibe)
• Stats panel: Total cost, tokens, active days, streaks
• FOUC prevention: Theme applied before React hydrates (no flash)

cd packages/frontend
bun install
bun run dev

Open http://localhost:3000 to access the social platform.

Tokscale includes a social platform where you can share your usage data and compete with other developers.

• Leaderboard - See who's using the most tokens across all platforms
• User Profiles - Public profiles with contribution graphs and statistics
• Period Filtering - View stats for all time, this month, or this week
• GitHub Integration - Login with your GitHub account
• Local Viewer - View your data privately without submitting

You can embed your public Tokscale stats directly in your GitHub profile README:

[![Tokscale Stats](https://tokscale.ai/api/embed/<username>/svg)](https://tokscale.ai/u/<username>)

Replace <username> with your GitHub username. With no query parameters this renders the default classic card; append any of the parameters below to customize the design.

Examples:

![](https://tokscale.ai/api/embed/<username>/svg?template=minimal&color=purple&graph=1)
![](https://tokscale.ai/api/embed/<username>/svg?template=orbit&color=pink&rank=percent)
![](https://tokscale.ai/api/embed/<username>/svg?template=terminal&color=green&theme=light)
![](https://tokscale.ai/api/embed/<username>/svg?template=receipt&color=YlGnBu&graph=1)
![](https://tokscale.ai/api/embed/<username>/svg?view=3d&compact=1)
![](https://tokscale.ai/api/embed/<username>/svg?period=week&graph=1)

You can also use a shields.io-style badge for a more compact display:

![Tokscale Tokens](https://tokscale.ai/api/badge/<username>/svg)

• Replace <username> with your GitHub username
• Optional query params:
  • metric=tokens (default), metric=cost, or metric=rank
  • style=flat (default) or style=flat-square
  • sort=tokens (default) or sort=cost to control ranking basis
  • compact=1 to use compact number notation (e.g., 1.2M, $3.4K)
  • label=<text> to override the left-side label
  • color=<hex> to override the right-side color (e.g., color=ff5733)
• Examples:
  • https://tokscale.ai/api/badge/<username>/svg?metric=cost&compact=1
  • https://tokscale.ai/api/badge/<username>/svg?metric=rank&sort=cost&style=flat-square

1. Login - Run tokscale login to authenticate via GitHub, or create an API token in Settings for CI/headless use
2. Submit - Run tokscale submit to upload your usage data
3. View - Visit the web platform to see your profile and the leaderboard

Submitted data goes through Level 1 validation:

• Mathematical consistency (totals match, no negatives)
• No future dates
• Required fields present
• Duplicate detection

Generate a beautiful year-in-review image summarizing your AI coding assistant usage—inspired by Spotify Wrapped.

bunx tokscale@latest wrapped	bunx tokscale@latest wrapped --clients

# Generate wrapped image for current year
tokscale wrapped

# Generate for a specific year
tokscale wrapped --year 2025

The generated image includes:

• Total Tokens - Your total token consumption for the year
• Top Models - Your 3 most-used AI models ranked by cost
• Top Clients - Your 3 most-used platforms (OpenCode, Claude Code, Cursor, etc.)
• Messages - Total number of AI interactions
• Active Days - Days with at least one AI interaction
• Cost - Estimated total cost based on LiteLLM pricing
• Streak - Your longest consecutive streak of active days
• Contribution Graph - A visual heatmap of your yearly activity

The generated PNG is optimized for sharing on social media. Share your coding journey with the community!

Quick setup: If you just want to get started quickly, see Development Setup in the Installation section above.

# Bun (required for JS tooling)
bun --version

# Rust (for native CLI binary)
rustc --version
cargo --version

After following the Development Setup, you can:

# Build native module (optional but recommended)
bun run build:core

# Run in development mode (launches TUI)
cd packages/cli && bun src/index.ts

# Or use legacy CLI mode
cd packages/cli && bun src/index.ts --light

make docker/build   # build and tag the frontend image (tokscale:latest)
make up             # start Postgres and the frontend on http://localhost:3333

make up

make tui/build   # build once
make tui         # launch

TOKSCALE_UID=$(id -u) TOKSCALE_GID=$(id -g) \
  docker compose --profile tui run --rm \
  -v "$HOME/.claude:/home/tokscale/.claude:ro" tui

make down         # stop all services
make logs/app     # tail app logs
make help         # full target list

export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypass
export POSTGRES_DB=mydb
export DATABASE_URL=postgresql://myuser:mypass@db:5432/mydb

# Test native module (Rust)
cd packages/core
bun run test:rust      # Cargo tests
bun run test           # Node.js integration tests
bun run test:all       # Both

cd packages/core

# Build in debug mode (faster compilation)
bun run build:debug

# Build in release mode (optimized)
bun run build

# Run Rust benchmarks
bun run bench

# Export graph data to file
tokscale graph --output usage-data.json

# Date filtering (all shortcuts work)
tokscale graph --today
tokscale graph --week
tokscale graph --since 2024-01-01 --until 2024-12-31
tokscale graph --year 2024

# Filter by platform
tokscale graph --client opencode,claude

# Show processing time benchmark
tokscale graph --output data.json --benchmark

tokscale --benchmark           # Show processing time with default view
tokscale models --benchmark    # Benchmark models report
tokscale monthly --benchmark   # Benchmark monthly report
tokscale graph --benchmark     # Benchmark graph generation

# Export data for visualization
tokscale graph --output packages/frontend/public/my-data.json

# Generate synthetic data
cd packages/benchmarks && bun run generate

# Run Rust benchmarks
cd packages/core && bun run bench

On Linux, the launcher detects glibc vs musl automatically (via process.report, the musl dynamic loader at /lib/ld-musl-*.so.1, and ldd). If detection ever picks the wrong flavor — e.g. in minimal containers — set TOKSCALE_LIBC=musl (or TOKSCALE_LIBC=gnu) to force it.

Tokscale fully supports Windows. The TUI and CLI work the same as on macOS/Linux.

Installation on Windows:

# Install Bun (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Run tokscale
bunx tokscale@latest

AI coding tools store their session data in cross-platform locations. Most tools use the same relative paths on all platforms:

Devin Desktop agent support: Local usage parsing works for ACP-connected agents (e.g. Cascade/Windsurf, claude-code, opencode) that emit usage_update events in the NDJSON stream. The default devin-cloud agent does not emit local usage_update events — its usage stays server-side and cannot be tracked by tokscale without an account-level API.

Note: On Windows, ~ expands to %USERPROFILE% (e.g., C:\Users\YourName). Some tools use Unix-style paths (like .local/share) for cross-platform consistency, while others, including Goose, use Windows-native paths like %APPDATA%, as listed above.

Tokscale stores its configuration in:

• TUI settings: %APPDATA%\tokscale\settings.json (platform default; override with TOKSCALE_CONFIG_DIR)
• Cache: %APPDATA%\tokscale\cache\ (consolidated cache root)
• Legacy cache paths: %USERPROFILE%\.cache\tokscale\ and %LOCALAPPDATA%\tokscale\cache\ equivalents from older releases may still exist until regenerated data is written to the new path
• Cursor credentials: %USERPROFILE%\.config\tokscale\cursor-credentials.json
• Trae credentials and synced usage: %APPDATA%\tokscale\trae-cache\
• Tokscale account credentials: %USERPROFILE%\.config\tokscale\credentials.json

By default, some AI coding assistants automatically delete old session files. To preserve your usage history for accurate tracking, disable or extend the cleanup period.

Default: 30 days cleanup period

Add to ~/.claude/settings.json:

{
  "cleanupPeriodDays": 9999999999
}

Setting an extremely large value (e.g., 9999999999 days ≈ 27 million years) effectively disables cleanup.

Default: Cleanup disabled (sessions persist forever)

If you've enabled cleanup and want to disable it, remove or set enabled: false in $GEMINI_CLI_HOME/settings.json (fallback: ~/.gemini/settings.json):

{
  "general": {
    "sessionRetention": {
      "enabled": false
    }
  }
}

Or set an extremely long retention period:

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "9999999d"
    }
  }
}

Default: No automatic cleanup (sessions persist forever)

Codex CLI does not have built-in session cleanup. Sessions in ~/.codex/sessions/ persist indefinitely.

Note: There's an open feature request for this: #6015

Default: No automatic cleanup (sessions persist forever)

OpenCode does not have built-in session cleanup. Sessions in ~/.local/share/opencode/storage/ persist indefinitely.

Note: See #4980

Location: ~/.local/share/opencode/opencode.db (v1.2+) or storage/message/{sessionId}/*.json (legacy)

OpenCode 1.2+ stores sessions in SQLite. Tokscale reads from SQLite first and falls back to legacy JSON files for older versions.

OpenCode picks the db filename from the release channel the binary was built against: the latest and beta channels use opencode.db, while other channels use opencode-<channel>.db (e.g. opencode-stable.db, opencode-nightly.db). Tokscale scans all of them, so users running multiple channels side by side get a unified view.

If you launched opencode with OPENCODE_DB pointing at a file outside ~/.local/share/opencode, add the absolute path to ~/.config/tokscale/settings.json so tokscale can find it on every run:

{
  "scanner": {
    "opencodeDbPaths": [
      "/custom/location/opencode.db",
      "/another/location/opencode-stable.db"
    ]
  }
}

Paths are merged with auto-discovery, deduped by canonical path, and non-existent entries are silently skipped (so stale config never breaks a scan). opencode.db-wal, opencode.db-shm, and other SQLite sidecars are rejected.

If you keep sessions outside Tokscale's default home-root locations, you can also persist extra scan roots per client:

{
  "scanner": {
    "extraScanPaths": {
      "codex": [
        "/Users/me/workspace/project-a/.codex/sessions",
        "/Users/me/workspace/project-b/.codex/archived_sessions"
      ],
      "gemini": ["/Users/me/imports/imac/gemini/tmp"],
      "hermes": [
        "/Users/me/.hermes/profiles/director_planning",
        "/Users/me/.hermes/profiles/research/state.db"
      ],
      "openclaw": ["/Users/me/imports/imac/openclaw/agents"]
    }
  }
}

This is useful for project-level .codex directories, imported histories, and Hermes profile databases outside the default $HERMES_HOME/state.db or ~/.hermes/state.db location. Tokscale still scans its default roots, then merges scanner.extraScanPaths and TOKSCALE_EXTRA_DIRS on top with canonical-path deduplication. It does not auto-discover your whole workspace.

Each message contains:

{
  "id": "msg_xxx",
  "role": "assistant",
  "modelID": "claude-sonnet-4-20250514",
  "providerID": "anthropic",
  "tokens": {
    "input": 1234,
    "output": 567,
    "reasoning": 0,
    "cache": { "read": 890, "write": 123 }
  },
  "time": { "created": 1699999999999 }
}

Location: ~/.claude/projects/{projectPath}/*.jsonl and ~/.claude/transcripts/*.jsonl

JSONL format with assistant messages containing usage data:

{"type": "assistant", "message": {"model": "claude-sonnet-4-20250514", "usage": {"input_tokens": 1234, "output_tokens": 567, "cache_read_input_tokens": 890}}, "timestamp": "2024-01-01T00:00:00Z"}

Wrapper transcript files under ~/.claude/transcripts/ are counted only when they contain real Claude usage metadata. Files with user/tool events but no usage block are skipped rather than estimated.

The claude client also scans Claude Desktop's retained Code/Cowork transcripts under ~/Library/Application Support/Claude/{local-agent-mode-sessions,claude-code-sessions}/**/.claude/{projects,transcripts} and the claude-conversation-store IndexedDB cache under the app's IndexedDB/https_claude.ai_0.indexeddb.leveldb directory. Equivalent app roots under AppData/Roaming/Claude and .config/Claude are recognized. Every retained session is scanned without a date cutoff, including subagents. Non-placeholder model identifiers carrying recorded usage are accepted, including models unknown to Tokscale's pricing tables; missing pricing does not discard tokens. Empty model identifiers and the placeholders unknown and <synthetic> are excluded. Cached Chat, Cowork and Code tree formats are read, but ordinary chats without token counters cannot be counted accurately and are not estimated from text.

Desktop cache reads are local and read-only: no Claude process, credentials, login, or remote requests are needed. Tokscale follows the current LevelDB manifest, deletion records and conversation tombstones, decodes compressed/external values, and deduplicates streamed responses against local transcripts. It does not import audit.jsonl alongside the original transcripts.

Cumulative modelUsage snapshots are not added together or added on top of the requests they already cover. Tokscale adds only the missing balance to all-time local model/session totals, with an unknown usage date and zero invented messages. These balances are conservative lower bounds when counters reset or histories overlap. Thinking tokens are already included in Anthropic output tokens and are not added again. Advisor calls are counted without adding extra turns, and per-request 1-hour cache writes retain their pricing split. When space permits, the TUI footer labels these tokens undated; models --json exposes undatedTokens and claudeDesktopCache coverage/decode diagnostics. Date-filtered reports, hourly/monthly/daily graphs and leaderboard submissions exclude undated balances. Dollar figures calculated from pricing tables are API-equivalent estimates, not subscription charges.

The app cache is not a complete account history. Truncated trees (hasOlder/earlierCursor), evicted/deleted conversations, incomplete streaming usage and counter resets can leave gaps. Tokscale reads the current live cache; it does not fetch missing cloud pages, recover deleted records, or retain private conversation text. An export containing only chat text cannot supply an exact token ledger. tokscale usage remains a separate view of subscription quota bars.

Location: ~/.codex/sessions/ and ~/.codex/archived_sessions/ (*.jsonl rollouts, zstd-compressed *.jsonl.zst copies, and other archive copies that add a suffix to the .jsonl name)

Event-based format with token_count events:

{"type": "event_msg", "payload": {"type": "token_count", "info": {"last_token_usage": {"input_tokens": 1234, "output_tokens": 567}}}}

Copies of one rollout are counted once, so a session that exists in both directories, or as both a plain and a compressed file, does not double its usage.

Location: ~/.copilot/session-store.db (CLI usage events; no OTEL required), ~/.copilot/otel/*.jsonl or the explicit path in COPILOT_OTEL_FILE_EXPORTER_PATH, and Desktop ~/.copilot/data.db

Copilot CLI usage is read from session-store.db by default. File-exported OpenTelemetry JSONL is still supported and wins per session when both exist. Enable OTEL before running Copilot:

export COPILOT_OTEL_ENABLED=true
export COPILOT_OTEL_EXPORTER_TYPE=file
mkdir -p "$HOME/.copilot/otel"
export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot-otel-$(date +%Y%m%d-%H%M%S).jsonl"

PowerShell:

$otelDir = "$HOME/.copilot/otel"
New-Item -ItemType Directory -Force -Path $otelDir | Out-Null
$env:COPILOT_OTEL_ENABLED = "true"
$env:COPILOT_OTEL_EXPORTER_TYPE = "file"
$env:COPILOT_OTEL_FILE_EXPORTER_PATH = Join-Path $otelDir ("copilot-otel-{0}.jsonl" -f (Get-Date -Format "yyyyMMdd-HHmmss"))

Using a timestamped filename is recommended so each Copilot session writes to a fresh file instead of accumulating into one huge OTEL log.

Repeated OTEL span snapshots are merged across files only when they carry a complete trace/span identity and compatible attribution and timestamps. Missing model, session, or agent context is filled from a matching richer snapshot; conflicting populated values remain separate. Records with a span ID but no trace ID can still merge within one file; they remain separate across files. The local parser cache is rebuilt when the parser generation changes.

This local deduplication does not immediately lower already-uploaded historical totals. The hosted high-water policy retains the previous maximum until corrected usage exceeds it: incoming totals of 200 → 100 → 150 → 200 → 250 retain hosted totals of 200 → 200 → 200 → 200 → 250. Later growth is still counted; repairing previously inflated hosted days requires a separate safe historical-correction mechanism. The local cache parser generation is independent of the submission wire generation, which is unchanged by this fix.

Tokscale treats chat spans as the source of truth for token accounting and ignores tool spans plus cumulative metrics in phase 1:

{"type":"span","name":"chat gpt-5.4-mini","attributes":{"gen_ai.operation.name":"chat","gen_ai.response.model":"gpt-5.4-mini","gen_ai.conversation.id":"session-id","gen_ai.usage.input_tokens":1234,"gen_ai.usage.output_tokens":567,"gen_ai.usage.cache_read.input_tokens":890,"gen_ai.usage.reasoning.output_tokens":123}}

Copilot's OTEL payloads currently do not expose stable workspace metadata, so Copilot rows may appear without workspace attribution. Tokscale prices these rows from the reported model when possible and does not trust github.copilot.cost directly.

Location: $GEMINI_CLI_HOME/tmp/{projectHash}/chats/*.json (fallback: ~/.gemini/tmp/{projectHash}/chats/*.json)

Session files containing message arrays:

{
  "sessionId": "xxx",
  "messages": [
    {"type": "gemini", "model": "gemini-2.5-pro", "tokens": {"input": 1234, "output": 567, "cached": 890, "thoughts": 123}}
  ]
}

Location: ~/.config/tokscale/cursor-cache/usage*.json (synced via Cursor API; legacy usage*.csv caches are still read when no JSON cache exists for the same account)

Cursor usage is fetched from the Cursor API using a session token and cached locally. Auth can be imported from the Cursor desktop state.vscdb (cursorAuth/accessToken only) or pasted as a browser cookie. Tokscale reads the API cache files for reports; it does not parse local ~/.cursor session data or desktop usage tables. See Cursor IDE Commands for setup.

Location: ~/.config/tokscale/antigravity-cache/sessions/*.jsonl (synced via local Antigravity language server RPC)

Antigravity data is not fetched automatically by the root command. Run tokscale antigravity sync while the Antigravity-enabled editor is open to refresh the local cache, then use normal tokscale reports and filters against the cached JSONL artifacts.

Location: ~/.config/tokscale/trae-cache/sessions/*.json (synced via official usage API)

Trae data is not fetched automatically by the root command. Run tokscale trae login once, then tokscale trae sync before reports. Tokscale parses the synced API dumps as session-level records and preserves the cost totals reported by Trae.

Location: ~/.config/tokscale/warp-cache/usage.json (synced via authenticated GraphQL API)

Warp/Oz data is not fetched automatically by the root command. Run tokscale warp login, then tokscale warp sync before reports. Tokscale records only aggregate request counts and spend because Warp does not expose token-attributed local transcripts.

Location: $GROK_HOME/sessions/*/*/updates.jsonl (fallback: ~/.grok/sessions/*/*/updates.jsonl)

Grok Build data is parsed directly from local session updates. Current logs expose cumulative totalTokens counters without a stable input/output split, so Tokscale records positive per-turn deltas as input tokens. grok-composer-2.5-fast is temporarily mapped to the Composer 2.5 Fast pricing override until a dedicated public price is available.

Location: $JCODE_HOME/sessions/session_*.json (fallback: ~/.jcode/sessions/session_*.json) plus matching session_*.journal.jsonl sidecars.

Jcode data is parsed directly from local session snapshots. Tokscale reads assistant messages[].token_usage fields (input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, and reasoning_output_tokens) without spoofing another client identity. Matching journal sidecars are merged into the same session stream before deduplication so recent appended messages are included until Jcode checkpoints them into the snapshot. Stable message IDs are used for replay dedupe; malformed/custom records without IDs use a scoped fallback key.

Location: ~/.augment/sessions/<sessionId>.json

Augment Code / Auggie CLI writes one JSON snapshot per chat session. Tokscale reads each completed turn under chatHistory[], prefers exchange.model_id over the session default agentState.modelId, and takes the single token_usage observation on exchange.response_nodes[] (input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens). The top-level sessionId is preserved so external tools can join costs back to the ACP session id.

Location: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (current OpenClaw) plus ~/.openclaw/agents/<agentId>/sessions/*.jsonl* (legacy transcripts, published archives, and doctor backups such as *.jsonl.pre-doctor-*.bak; also scans legacy paths: ~/.clawdbot/, ~/.moltbot/, ~/.moldbot/)

Current OpenClaw (2026.x) stores live transcripts in a per-agent SQLite database. Tokscale opens every agent database read-only (safe in WAL mode while the gateway is running), reads the transcript_events table, counts assistant events that carry a usage block (except OpenClaw's own transcript-bookkeeping rows such as delivery-mirror, which are not model output), and falls back to the session_windows model/provider when an event does not name its own. For turns OpenClaw ran through the Codex app-server harness, the transcript only mirrors the final assistant message with the last model response's usage, so Tokscale also reads the Codex rollouts OpenClaw keeps under ~/.openclaw/agents/<agentId>/agent/codex-home/sessions/ (its default per-agent CODEX_HOME), attributes every response in them to openclaw under the OpenClaw session they were mirrored into, and drops the transcript's mirror row for each turn the rollout holds (a mirror row for a turn the rollout lacks, because the rollout was cut short or the turn ran after it was read, is kept). Rollouts OpenClaw creates in a shared user Codex home (appServer.homeScope: "user", or a supervision branch) carry originator: "openclaw" and are attributed the same way instead of to the Codex client. A thread the Codex client already counts (one OpenClaw resumed from the user's own Codex home through supervision) keeps its usage under codex and the mirror rows of its turns are dropped, so nothing is counted twice; a mirror row whose rollout cannot be found anywhere is kept as is. Copies of a transcript that /fork writes under a new session id, and legacy JSONL that openclaw doctor --fix imported into SQLite, count once. Legacy JSONL the doctor found unreferenced is never imported; it moves to session-sqlite-import-archive/archive-tier.<sessionId>.jsonl.imported-<ts> and is read from there under its original session id.

Legacy installs wrote one JSONL file per session (indexed by sessions.json), and openclaw doctor --fix imports them into SQLite while leaving the originals in place. Every assistant event is keyed by its own event id, timestamp and token counts across both stores, so a migrated transcript that still exists as JSONL is counted once.

Legacy index file pointing to JSONL session files:

{
  "agent:main:main": {
    "sessionId": "uuid",
    "sessionFile": "/path/to/session.jsonl"
  }
}

Session JSONL format with model_change events and assistant messages:

{"type":"model_change","provider":"openai-codex","modelId":"gpt-5.2"}
{"type":"message","message":{"role":"assistant","usage":{"input":1660,"output":55,"cacheRead":108928,"cost":{"total":0.02}},"timestamp":1769753935279}}

Location: $HERMES_HOME/state.db (fallback: ~/.hermes/state.db) plus standard profile databases at $HERMES_HOME/profiles/*/state.db (or sibling ~/.hermes/profiles/*/state.db when HERMES_HOME points at an active profile)

Hermes stores session-level usage in a SQLite sessions table. Tokscale imports rows where model is present and token or cost totals are non-zero, uses started_at as the timestamp, preserves message_count, and prefers actual_cost_usd over estimated_cost_usd.

Location: $UNSLOTH_STUDIO_HOME/studio.db (fallback: ~/.unsloth/studio/studio.db)

Tokscale reads exact inference counters from Unsloth Studio's durable SQLite database. Internal Studio responses come from contextUsage metadata on completed assistant messages; authenticated external API calls come from the content-free api_usage_events table. The queries do not select message bodies, prompts, responses, credentials, or response previews. Stable message and request IDs prevent double-counting across overlapping scan roots, and SQLite WAL changes invalidate the source cache. Local inference is recorded at $0. Training num_tokens metrics are intentionally excluded because they measure training progress rather than prompt/completion usage.

Location: $HINDSIGHT_HOME/usage/<YYYY-MM>.jsonl (fallback: ~/.hindsight/usage/<YYYY-MM>.jsonl, synced via Hindsight LLM trace API)

Hindsight writes no local session logs of its own. Running tokscale hindsight sync fetches recent LLM calls from Hindsight's rolling /v1/{tenant}/banks/{bank_id}/llm-requests trace endpoint and appends them to monthly JSONL ledgers on disk. Tokscale reads those cached ledgers for reports and deduplicates requests by their stable request ID.

Location: ~/.pi/agent/sessions/<encoded-cwd>/*.jsonl. Oh My Pi writes the same session format under ~/.omp/agent/sessions/ and is tracked as its own omp client.

JSONL format with session header and message entries:

{"type":"session","id":"pi_ses_001","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/tmp"}
{"type":"message","id":"msg_001","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-3-5-sonnet","provider":"anthropic","usage":{"input":100,"output":50,"cacheRead":10,"cacheWrite":5,"totalTokens":165}}}

Pi also bills work that is not an assistant reply: /compact writes a compaction record, branch summarization a branch_summary record, and standalone accounting (e.g. cache warming) a usage record, while a toolResult message can carry usage for the call behind it. Tokscale counts each of those as its own request and preserves its reported cost when present. A current-format standalone usage record names its billed provider and model explicitly, while an older model-less one inherits the session's current selection (the last model_change or reply). Model-less tool results, compactions, and branch summaries stay in Pi's separate tools/summaries bucket instead of being charged to the preceding conversation model. A record without usage bills nothing.

Location: ~/.senpi/agent/sessions/<encoded-cwd>/*.jsonl and ~/.omo/agent/sessions/<encoded-cwd>/*.jsonl (OmO Native, omo-ai 5.1.0+), plus task child sessions under each project's .omo/senpi-task/children/

Senpi uses the same JSONL session format as Pi. OmO stores task child sessions inside each project, so Tokscale reads the cwd from the session headers in both sessions trees and scans <project>/.omo/senpi-task/children/ for every project that has one. If OmO's task.state_dir is set to an absolute path (in the project's .omo/omo.jsonc or .omo/omo.json, or in the same file under ~/.omo/), Tokscale scans <state_dir>/children/ instead.

If OmO keeps its agent directory somewhere else, add it to scanner.extraScanPaths.senpi in settings.json (by default ~/.config/tokscale/settings.json; see Configuration for Windows, XDG_CONFIG_HOME and TOKSCALE_CONFIG_DIR). The entry may point at the agent directory or at its sessions/ directory. Tokscale scans the sessions there and finds the task children of the projects they record in the same way:

{
  "scanner": {
    "extraScanPaths": {
      "senpi": ["/Users/me/custom/omo/agent"]
    }
  }
}

Location: ~/.prime/agent/sessions/*.jsonl for root sessions and ~/.prime/agent/session-artifacts/*/sub-*/*.jsonl for RLM child sessions. The agent root can be moved with PRIME_AGENT_CODING_AGENT_DIR; the sessionDir setting, PRIME_AGENT_SESSION_DIR, or legacy PRIME_AGENT_CODING_AGENT_SESSION_DIR can move the session directory independently.

Prime Agent uses the same append-only JSONL message format as Pi. Tokscale scans root and child session files as separate sources and ignores child_usage_attributed bookkeeping records, which prevents RLM child tokens from being counted both in the parent aggregate and in the child's own transcript. Named RLM sessions are exposed as agent attribution.

Location: ~/.kimi/sessions/{GROUP_ID}/{SESSION_UUID}/wire.jsonl

wire.jsonl format with StatusUpdate messages:

{"type": "metadata", "protocol_version": "1.3"}
{"timestamp": 1770983426.420942, "message": {"type": "StatusUpdate", "payload": {"token_usage": {"input_other": 1562, "output": 2463, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "chatcmpl-xxx"}}}

Location: ~/.kimi-code/sessions/{WORKDIR}/{SESSION_UUID}/agents/{AGENT}/wire.jsonl

{"type":"usage.record","model":"kimi-code/kimi-for-coding","usage":{"inputOther":1163,"output":352,"inputCacheRead":22272,"inputCacheCreation":0},"usageScope":"turn","time":1780410897480}

Location: ~/.qwen/projects/{PROJECT_PATH}/chats/{CHAT_ID}.jsonl

Format: JSONL — one JSON object per line, each with type, model, timestamp, sessionId, and usageMetadata fields.

Token fields (from usageMetadata):

• promptTokenCount → input tokens
• candidatesTokenCount → output tokens
• thoughtsTokenCount → reasoning/thinking tokens
• cachedContentTokenCount → cached input tokens

Location:

• Local: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json
• Server (best-effort): ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json

Each task directory may also include api_conversation_history.json with <environment_details> blocks used for model/agent metadata.

ui_messages.json is an array of UI events. Tokscale counts only:

• type == "say"
• say == "api_req_started"

The text field is JSON containing token/cost metadata:

{
  "type": "say",
  "say": "api_req_started",
  "ts": "2026-02-18T12:00:00Z",
  "text": "{\"cost\":0.12,\"tokensIn\":100,\"tokensOut\":50,\"cacheReads\":20,\"cacheWrites\":5,\"apiProtocol\":\"anthropic\"}"
}

Location:

• Local: ~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json
• Server (best-effort): ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json

Kilo uses the same task log shape as Roo Code. Tokscale applies the same rules:

• count only say/api_req_started events from ui_messages.json
• parse tokensIn, tokensOut, cacheReads, cacheWrites, cost, and apiProtocol from text JSON
• enrich model/agent metadata from sibling api_conversation_history.json when available

Location:

• Linux desktop VS Code: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/tasks/{TASK_ID}/ui_messages.json
• macOS desktop VS Code: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/tasks/{TASK_ID}/ui_messages.json
• Windows desktop VS Code: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\tasks\{TASK_ID}\ui_messages.json
• Server (best-effort): ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/tasks/{TASK_ID}/ui_messages.json

Cline is the upstream project that Roo Code and Kilo forked from, so it uses the same VS Code globalStorage task log shape. Tokscale applies the same rules:

• count only say/api_req_started events from ui_messages.json
• parse tokensIn, tokensOut, cacheReads, cacheWrites, cost, and apiProtocol from text JSON
• enrich model/agent metadata from sibling api_conversation_history.json when available

Cline CLI sessions select the first available root in this order: $CLINE_SESSION_DATA_DIR → $CLINE_DATA_DIR/sessions/ → $CLINE_DIR/data/sessions/ → fallback ~/.cline/data/sessions/. Blank or whitespace-only environment values are treated as unset. Within the selected root, sessions are read from {SESSION_ID}/{SESSION_ID}.messages.json. Tokscale counts assistant messages with persisted metrics, including input/output/cache tokens and provider-reported cost, and uses the sibling session manifest for workspace and fallback model metadata. When environment-root discovery is disabled, only the home fallback is used.

Location:

• ~/.config/kimchi/harness/sessions/{ENCODED_WORKSPACE}/*.jsonl (or $KIMCHI_CODING_AGENT_DIR/sessions/)

Kimchi uses the Pi-compatible JSONL session format. Tokscale counts assistant messages with persisted input/output/cache usage and keeps Kimchi as a separate client from Pi, even though the session schema is shared.

Location:

• ~/.mux/sessions/{WORKSPACE_ID}/session-usage.json

Mux stores cumulative per-session token usage in session-usage.json files. Each file contains a byModel map with per-model token breakdowns:

• input, cached (cache reads), cacheCreate (cache writes), output, reasoning
• Model names use provider:model format (e.g., anthropic:claude-opus-4-6) — tokscale strips the provider prefix for model identification
• Sub-agent usage is automatically rolled up into parent sessions by Mux, so there is no double-counting

Location: ~/.local/share/kilo/kilo.db

Kilo CLI stores session data in a SQLite database similar to OpenCode. Each message row contains per-message token breakdowns (input, output, cache read/write, reasoning) with model and provider attribution.

Location: Project-level SQLite databases discovered via $XDG_DATA_HOME/crush/projects.json (fallback: ~/.local/share/crush/projects.json)

Crush stores usage in per-project SQLite databases (crush.db). Tokscale imports session-level cost totals from root sessions only, because Crush does not expose reliable per-message or per-model token accounting. Records appear as model=session-total with zero token breakdown.

Location: ~/.local/share/goose/sessions/sessions.db (also scans ~/Library/Application Support/goose/, ~/Library/Application Support/Block/goose/, ~/.local/share/Block/goose/; override via GOOSE_PATH_ROOT)

Native Windows scans check %APPDATA%\Block\goose\data\sessions\sessions.db before XDG and legacy locations. With APPDATA unset or empty, the native roaming directory is checked before Desktop's <HOME>/AppData/Roaming fallback. --home scans ignore GOOSE_PATH_ROOT and process-specific Windows locations, and also check <home>/AppData/Roaming/Block/goose/data/sessions/sessions.db. Without --home, an absolute GOOSE_PATH_ROOT is authoritative even when its database is absent; relative values are ignored. Moving the executable does not relocate the database.

Goose stores per-session usage in a SQLite sessions.db. Tokscale extracts the model from model_config_json, the provider from provider_name, and accumulated input/output token totals per session. Reasoning tokens are inferred when the column is populated.

Location: ~/.config/manicode/projects/<project>/chats/<chatId>/chat-messages.json (also scans manicode-dev and manicode-staging channels; override via CODEBUFF_DATA_DIR)

Codebuff (formerly Manicode) writes per-chat JSON files. Tokscale parses token usage from metadata.usage, metadata.codebuff.usage, and the run-state messageHistory[*].providerOptions fallback, walking the history in reverse so partial newer entries don't shadow earlier entries that carry the actual token counts. Per-message timestamps fall back to the chat-id directory name and finally to file mtime when missing.

Location: ~/.gjc/agent/sessions/<project-slug>/*.jsonl (override the agent dir via GJC_CODING_AGENT_DIR; also resolves GJC_CONFIG_DIR/PI_CONFIG_DIR joined with agent/sessions, and the flattened $XDG_DATA_HOME/gjc/sessions/ redirect on Linux/macOS). Depth-2 per-pass sub-agent transcripts (<slug>/<session>/N-*.jsonl) are discovered too.

JSONL format with a session header and message entries. Tokscale emits only assistant messages and reuses gjc's authoritative per-message usage.cost.total (USD) when present, recomputing from tokens only when it is absent:

{"type":"session","id":"S1","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/work/proj"}
{"type":"message","id":"M1","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-sonnet-4","provider":"anthropic","usage":{"input":1000,"output":500,"cacheRead":0,"cacheWrite":0,"totalTokens":1500,"cost":{"input":0.1,"output":0.2,"total":0.3}}}}

Messages dedup by <session id>:<message id> (with a deterministic fallback) so replayed depth-1/depth-2 transcripts are counted once. service_tier_change and malformed lines are skipped per line.

Synthetic usage is detected via post-processing of existing agent session files. Messages are re-attributed to synthetic when they use hf: model IDs or synthetic providers (synthetic, glhf, octofriend).

Tokscale also checks Octofriend SQLite at ~/.local/share/octofriend/sqlite.db and parses token-bearing records when available.

Location: ~/.local/share/mimocode/mimocode.db (XDG data directory)

MiMo Code stores session data in a SQLite database. Tokscale queries the message table joined with session for workspace context:

SELECT m.id, m.session_id, m.data, NULLIF(s.directory, '') AS workspace_root
FROM message m
LEFT JOIN session s ON s.id = m.session_id
WHERE json_extract(m.data, '$.role') = 'assistant'
  AND json_extract(m.data, '$.tokens') IS NOT NULL

The data column is a JSON blob with the following token-relevant fields:

{
  "role": "assistant",
  "modelID": "claude-sonnet-4",
  "providerID": "anthropic",
  "cost": 0.0032,
  "tokens": {
    "input": 1200,
    "output": 450,
    "reasoning": 0,
    "cache": { "read": 800, "write": 0 }
  },
  "time": { "created": 1780410897000, "completed": 1780410912000 },
  "agent": "micode",
  "path": { "root": "/Users/me/project" }
}

Tokscale deduplicates messages across forked sessions using a fingerprint of timestamps, model, provider, token counts, cost, and agent name.

Aside stores flat assistant usage at ~/.aside/u/<account>/sessions/<session>/messages.jsonl. Tokscale preserves native timestamps, model metadata and separate cached-input buckets, including the 1-hour-TTL subset of cache writes. Reasoning is split out of output, so totals and estimated cost count it once. Aside's provider field records the route rather than the vendor, so a Claude Code route is reported as Anthropic and a generic gateway route defers to model-family inference; explicit vendor ids stay authoritative. Repeated provider-scoped response IDs are counted once across sessions/accounts; calls without an ID remain separate. Positive recorded costs are retained; zero or absent costs use standard pricing. Use tokscale --no-spinner --client aside to filter usage. Windows execution has not been verified.

Location: ~/.local/share/muse/sessions/YYYY/MM/DD/<session-uuid>/session.jsonl (same XDG-style path on all platforms, including Windows; subagent transcripts under subagent/<uuid>/ are scanned too)

Muse Code writes one event-sourced JSONL transcript per session. Tokscale reads model_completed events, which carry the model id (muse-spark-*), a Responses-shaped usage object (input_tokens, output_tokens, cached_tokens/cache_read_tokens, cache_write_tokens, reasoning_tokens) and the call's duration_ms; recorded_at is in microseconds. cached_tokens is a subset of input_tokens and reasoning rides inside output_tokens, so both are split out before pricing and aggregation. The parent session's workflow_child_lifecycle usage aggregates are skipped because the child transcripts they summarize are scanned separately. Workspace labels come from the file's runtime.session.metadata record.

Muse Spark models are priced from upstream datasets — LiteLLM and models.dev carry meta/muse-spark-* rows at Meta's published rates — so Muse usage is costed out of the box (Standard: $1.25/$4.25 per 1M input/output tokens, $0.15 cached input; Contributor: $0.10/$0.20, $0.002 cached input — see pricing and rate limits).

Location: ~/.vibe/logs/session/<prefix>_<YYYYMMDD_HHMMSS>_<short-id>/meta.json (same ~/.vibe root on macOS, Linux and Windows — Vibe uses no XDG or %APPDATA% location; override the root with VIBE_HOME, or the session directory itself with session_logging.save_dir)

Vibe writes a directory per session holding meta.json and a messages.jsonl transcript. Usage is session-granular: the transcript carries no per-message model, timestamp, or token counts, so Tokscale reads only the cumulative stats block in meta.json (session_prompt_tokens, session_completion_tokens, session_cached_tokens) and never the conversation content. session_cached_tokens is a subset of session_prompt_tokens rather than an addition to it, so cached reads are split out of the input count before pricing — the same arithmetic Vibe's own cost display uses. One message per session is therefore the finest row the format supports; steps becomes the session's message count, and end_time (ISO-8601, falling back to start_time) its timestamp. Pre-2.0 sessions stored one flat <prefix>_*.json per session with the same fields under a metadata key; those are still read.

The model comes from config.active_model in meta.json, which holds the alias the session was pinned to. A session that was never pinned records the empty string — Vibe's documented "follow the configured default" sentinel — so Tokscale resolves it from the session's own config.models table, then from Mistral's published default alias, rather than attributing the usage to a blank model. Note that the alias (mistral-medium-3.5) is not the wire id: Vibe sends a CLI-routed endpoint name (mistral-vibe-cli-latest) that no public pricing dataset carries, so the alias is what pricing resolves against. Workspace labels come from environment.working_directory, falling back to origin_directory.

Tokscale fetches real-time pricing from LiteLLM's pricing database.

Dynamic Fallback: For models not yet available in LiteLLM (e.g., recently released models), Tokscale automatically fetches pricing from OpenRouter's endpoints API. This ensures you get accurate pricing from the model's author provider (e.g., Z.AI for glm-4.7) without waiting for LiteLLM updates.

Cursor Model Pricing: For very recently released models not yet in either LiteLLM or OpenRouter (e.g., gpt-5.3-codex), Tokscale includes hardcoded pricing sourced from Cursor's model docs. These overrides are checked after all upstream sources but before fuzzy matching, so they automatically yield once real upstream pricing becomes available.

Sakana Fugu Pricing: Fugu Ultra cost is estimated from Sakana's published pay-as-you-go rates; the fugu router model is intentionally left unpriced because its cost is the variable rate of whichever underlying model it orchestrated.

Caching: Pricing data is cached to disk with 1-hour TTL for fast startup:

• LiteLLM cache: ~/.config/tokscale/cache/pricing-litellm.json
• OpenRouter cache: ~/.config/tokscale/cache/pricing-openrouter.json (caches author pricing for models from supported providers)

Pricing includes:

• Input tokens
• Output tokens
• Cache read tokens (discounted)
• Cache write tokens
• Reasoning tokens (for models like o1)
• Model-specific tiered pricing (for example, above 200k or 272k tokens)

Tokscale can reconcile an older local export of wiped session transcripts back into local reports via an opt-in ledger at ~/.config/tokscale/recovered-usage-v1.json (the config directory resolved by TOKSCALE_CONFIG_DIR). The file is an Archive JSON object: version (must be 1), home (must exactly match the scanned home directory), and optional messages / daily_floors arrays of serialized UnifiedMessage records — messages restores archived request rows for sessions no longer on disk, while daily_floors holds per-(client, date) aggregate snapshots that fill only the positive gap between the snapshot and the counted daily total. Live transcripts always win, recovered rows are marked with local-recovery: dedup keys and "Recovered request archive" / "Recovered daily aggregate (component split estimated)" agent labels, and the overlay is strictly local-only: recovered usage is never submitted to the leaderboard, never written into the source-message cache, and daily-floor aggregates are excluded from the Sessions, Agents, Hourly, and Minutely views. Set TOKSCALE_RECOVERY_DISABLE to ignore the ledger. The format is internal: local-recovery: keys are trusted as produced by Tokscale itself, so do not hand-author them. While a matching ledger is present, local reports collect all messages instead of streaming them, so users with very large corpora may see higher memory usage.

{
  "version": 1,
  "home": "/Users/you",
  "messages": [ /* archived request rows as serialized UnifiedMessages */ ],
  "daily_floors": [ /* per-(client, date) aggregate snapshots as serialized UnifiedMessages */ ]
}

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (cd packages/core && bun run test:all)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

• Follow existing code style
• Add tests for new functionality
• Update documentation as needed
• Keep commits focused and atomic

• ccusage, viberank, and Isometric Contributions for inspiration
• Ratatui for terminal UI framework
• Solid.js for reactive rendering
• LiteLLM for pricing data
• napi-rs for Rust/Node.js bindings
• github-contributions-canvas for 2D graph reference

MIT © Junho Yeo

If you find this project intriguing, please consider starring it ⭐ or follow me on GitHub and join the ride (1.1k+ already aboard). I code around the clock and ship mind-blowing things on a regular basis—your support won't go to waste.