tokscale

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

[!TIP]

v2 is here — native Rust TUI, cross-platform support, and more.
I drop new open-source work every week. Don't miss the next one.

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

Overview	Models

Daily Summary	Stats

Frontend (3D Contributions Graph)	Wrapped 2025

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

Overview

Tokscale helps you monitor and analyze your token consumption from:

Logo	Client	Data Location	Supported
	OpenCode	~/.local/share/opencode/opencode.db (1.2+, all channels including opencode-stable.db) or/and ~/.local/share/opencode/storage/message/ (legacy/unmigrated)	✅ Yes
	Claude Code	~/.claude/projects/	✅ Yes
	OpenClaw	~/.openclaw/agents/ (+ legacy: .clawdbot, .moltbot, .moldbot)	✅ Yes
	Codex CLI	~/.codex/sessions/	✅ Yes
	GitHub Copilot CLI	~/.copilot/otel/*.jsonl (+ COPILOT_OTEL_FILE_EXPORTER_PATH)	✅ Yes
	Hermes Agent	$HERMES_HOME/state.db (fallback: ~/.hermes/state.db)	✅ Yes
	Gemini CLI	~/.gemini/tmp/*/chats/*.json	✅ Yes
	Cursor IDE	API sync via ~/.config/tokscale/cursor-cache/	✅ Yes
	Amp (AmpCode)	~/.local/share/amp/threads/	✅ Yes
	Droid (Factory Droid)	~/.factory/sessions/	✅ Yes
	Pi	~/.pi/agent/sessions/ and ~/.omp/agent/sessions/ (Oh My Pi)	✅ Yes
	Kimi CLI	~/.kimi/sessions/	✅ Yes
	Qwen CLI	~/.qwen/projects/	✅ Yes
	Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/)	✅ Yes
	Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/)	✅ Yes
	Mux	~/.mux/sessions/	✅ Yes
	Kilo CLI	~/.local/share/kilo/kilo.db	✅ Yes
	Crush	$XDG_DATA_HOME/crush/projects.json (project registry; fallback: ~/.local/share/crush/projects.json)	✅ Yes
	Synthetic	Re-attributed from other sources via hf: model prefix or synthetic provider (+ Octofriend: ~/.local/share/octofriend/sqlite.db)	✅ Yes

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

Why "Tokscale"?

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

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

Contents

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

Features

• Interactive TUI Mode - Beautiful terminal UI powered by Ratatui (default mode)
  • 6 interactive views: Overview, Models, Daily, Hourly, Stats, Agents
  • Keyboard & mouse navigation
  • GitHub-style contribution graph with 9 color themes
  • Real-time filtering and sorting
  • Zero flicker rendering
• Multi-platform support - Track usage across OpenCode, Claude Code, Codex CLI, Copilot CLI, Cursor IDE, Gemini CLI, Amp, Droid, OpenClaw, Hermes Agent, Pi, Kimi CLI, Qwen CLI, Roo Code, Kilo, Mux, Kilo CLI, Crush, and Synthetic
• Real-time pricing - Fetches current pricing from LiteLLM with 1-hour disk cache; automatic OpenRouter fallback and Cursor model pricing for newly released models
• Detailed breakdowns - Input, output, cache read/write, and reasoning token tracking
• Native Rust core - All parsing and aggregation done in Rust for 10x faster processing
• Web visualization - Interactive contribution graph with 2D and 3D views
• Flexible filtering - Filter by platform, date range, or year
• Export to JSON - Generate data for external visualization tools
• Social Platform - Share your usage, compete on leaderboards, and view public profiles

Installation

Quick Start

# Run directly with npx
npx tokscale@latest

# Or use bunx
bunx tokscale@latest

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

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

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

Prerequisites

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

Development Setup

For local development or building from source:

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

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

# Install dependencies
bun install

# Run the CLI in development mode
bun run cli

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

Building the Native Module

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

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

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

Usage

Basic Commands

# Launch interactive TUI (default)
tokscale

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

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

# Launch TUI explicitly
tokscale tui

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

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

TUI Features

The interactive TUI mode provides:

• 6 Views: Overview (chart + top models), Models, Daily, Hourly, Stats (contribution graph), Agents
• Keyboard Navigation:
  • 1-6 or ←/→/Tab: Switch views
  • ↑/↓: Navigate lists
  • c/d/t: Sort by cost/date/tokens
  • s: Open source picker dialog
  • g: Open group-by picker dialog (model, client+model, client+provider+model)
  • p: Cycle through 9 color themes
  • r: Refresh data
  • e: Export to JSON
  • q: Quit
• Mouse Support: Click tabs, buttons, and filters
• Themes: Green, Halloween, Teal, Blue, Pink, Purple, Orange, Monochrome, YlGnBu
• Settings Persistence: Preferences saved to ~/.config/tokscale/settings.json (see Configuration)

Group-By Strategies

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

--group-by model (most consolidated)

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

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

Filtering by Platform

# Show only OpenCode usage
tokscale --opencode

# Show only Claude Code usage
tokscale --claude

# Show only Codex CLI usage
tokscale --codex

# Show only Copilot CLI usage
tokscale --copilot

# Show only OpenClaw usage
tokscale --openclaw

# Show only Pi usage
tokscale --pi

# Show only Gemini CLI usage
tokscale --gemini

# Show only Cursor IDE usage (requires `tokscale cursor login` first)
tokscale --cursor

# Show only Amp usage
tokscale --amp

# Show only Droid usage
tokscale --droid

# Show only Hermes Agent usage
tokscale --hermes

# Show only Kimi CLI usage
tokscale --kimi

# Show only Qwen CLI usage
tokscale --qwen

# Show only Roo Code usage
tokscale --roocode

# Show only Kilo usage
tokscale --kilocode

# Show only Mux usage
tokscale --mux

# Show only Kilo CLI usage
tokscale --kilo

# Show only Crush usage
tokscale --crush

# Show only Synthetic (synthetic.new) usage
tokscale --synthetic

# Combine filters
tokscale --opencode --claude

Date Filtering

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

# Quick date shortcuts
tokscale --today              # Today only
tokscale --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 --claude --json
tokscale monthly --month --benchmark

Note: Date filters use your local timezone. Both --since and --until are inclusive.

Pricing Lookup

Look up real-time pricing for any model:

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

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

Lookup Strategy:

The pricing lookup uses a multi-step resolution strategy:

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

Provider Preference:

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

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

Social

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

# Check who you're logged in as
tokscale whoami

# Submit your usage data to the leaderboard
tokscale submit

# Submit with filters
tokscale submit --opencode --claude --since 2024-01-01

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

# Logout
tokscale logout

Cursor IDE Commands

Cursor IDE requires separate authentication via session token (different from the social platform login):

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

# Check Cursor authentication status and session validity
tokscale cursor status

# List saved Cursor accounts
tokscale cursor accounts

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

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

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

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

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

By default, tokscale aggregates usage across all saved Cursor accounts (all cursor-cache/usage*.csv).

When you log out, tokscale keeps your cached usage history by moving it to cursor-cache/archive/ (so it won't be aggregated). Use --purge-cache if you want to delete the cached usage instead.

Credentials storage: Cursor accounts are stored in ~/.config/tokscale/cursor-credentials.json. Usage data is cached at ~/.config/tokscale/cursor-cache/ (active account uses usage.csv, additional accounts use usage.<account>.csv).

To get your Cursor session token:

1. Open https://www.cursor.com/settings in your browser
2. Open Developer Tools (F12)
3. Option A - Network tab: Make any action on the page, find a request to cursor.com/api/*, look in the Request Headers for the Cookie header, and copy only the value after WorkosCursorSessionToken=
4. Option B - Application tab: Go to Application → Cookies → https://www.cursor.com, find the WorkosCursorSessionToken cookie, and copy its value (not the cookie name)

⚠️ Security Warning: Treat your session token like a password. Never share it publicly or commit it to version control. The token grants full access to your Cursor account.

Example Output (--light version)

Configuration

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

{
  "colorPalette": "blue",
  "includeUnusedModels": false,
  "scanner": {
    "extraScanPaths": {
      "codex": [
        "/Users/me/workspace/project-a/.codex/sessions",
        "/Users/me/workspace/project-b/.codex/archived_sessions"
      ]
    }
  }
}

Use scanner.extraScanPaths for persistent extra roots such as project-level .codex directories or imported Gemini/OpenClaw histories. Tokscale merges these paths with the default scan roots on every run and deduplicates overlapping roots by canonical path.

Environment Variables

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

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.

Headless Mode

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

What is headless mode?

When you run Codex CLI with JSON output flags (e.g., codex exec --json), it outputs usage data to stdout instead of storing it in its regular session directories. Headless mode allows you to capture and track this usage.

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

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

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 only. If you run Codex directly, redirect stdout to the headless directory as shown above.

Frontend Visualization

The frontend provides a GitHub-style contribution graph visualization:

Features

• 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, Copilot, Cursor, Gemini, Amp, Droid, OpenClaw, Hermes Agent, Pi, Kimi, Qwen, Roo Code, Kilo, Mux, Kilo CLI, Crush, Synthetic)
• Stats panel: Total cost, tokens, active days, streaks
• FOUC prevention: Theme applied before React hydrates (no flash)

Running the Frontend

cd packages/frontend
bun install
bun run dev

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

Social Platform

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

Features

• 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

GitHub Profile Embed Widget

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
• Optional query params:
  • theme=light for a light theme
  • sort=tokens (default) or sort=cost to control ranking basis
  • compact=1 to use compact layout + compact number notation (e.g., 1.2M, $3.4K)
• Example:
  • https://tokscale.ai/api/embed/<username>/svg?theme=light&sort=cost&compact=1

GitHub Profile Badge

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

Getting Started

1. Login - Run tokscale login to authenticate via GitHub
2. Submit - Run tokscale submit to upload your usage data
3. View - Visit the web platform to see your profile and the leaderboard

Data Validation

Submitted data goes through Level 1 validation:

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

Wrapped 2025

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	bunx tokscale@latest wrapped --agents --disable-pinned

Command

# Generate wrapped image for current year
tokscale wrapped

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

What's Included

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!

Development

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

Prerequisites

# Bun (required)
bun --version

# Rust (for native module)
rustc --version
cargo --version

How to Run

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/cli.ts

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

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

Supported Platforms

Native Module Targets

Windows Support

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

Data Locations on Windows

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

Note: On Windows, ~ expands to %USERPROFILE% (e.g., C:\Users\YourName). These tools intentionally use Unix-style paths (like .local/share) even on Windows for cross-platform consistency, rather than Windows-native paths like %APPDATA%.

Windows-Specific Configuration

Tokscale stores its configuration in:

• Config: %USERPROFILE%\.config\tokscale\settings.json
• Cache: %USERPROFILE%\.cache\tokscale\
• Cursor credentials: %USERPROFILE%\.config\tokscale\cursor-credentials.json

Session Data Retention

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.

Claude Code

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.

Gemini CLI

Default: Cleanup disabled (sessions persist forever)

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

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

Or set an extremely long retention period:

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

Codex CLI

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

OpenCode

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

Data Sources

OpenCode

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"],
      "openclaw": ["/Users/me/imports/imac/openclaw/agents"]
    }
  }
}

This is useful for project-level .codex directories and imported histories. 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 }
}

Claude Code

Location: ~/.claude/projects/{projectPath}/*.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"}

Codex CLI

Location: ~/.codex/sessions/*.jsonl

Event-based format with token_count events:

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

Copilot CLI

Location: ~/.copilot/otel/*.jsonl or the explicit path in COPILOT_OTEL_FILE_EXPORTER_PATH

Copilot support reads file-exported OpenTelemetry JSONL. Enable it 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.

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.

Gemini CLI

Location: ~/.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}}
  ]
}

Cursor IDE

Location: ~/.config/tokscale/cursor-cache/ (synced via Cursor API)

Cursor data is fetched from the Cursor API using your session token and cached locally. Run tokscale cursor login to authenticate. See Cursor IDE Commands for setup instructions.

OpenClaw

Location: ~/.openclaw/agents/*/sessions/sessions.json (also scans legacy paths: ~/.clawdbot/, ~/.moltbot/, ~/.moldbot/)

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

Hermes Agent

Location: $HERMES_HOME/state.db (fallback: ~/.hermes/state.db)

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.

Pi

Location: ~/.pi/agent/sessions/<encoded-cwd>/*.jsonl and ~/.omp/agent/sessions/<encoded-cwd>/*.jsonl (Oh My Pi)

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

Kimi CLI

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

Qwen CLI

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

Roo Code

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

Kilo

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

Mux

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

Kilo CLI

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.

Crush

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

README truncated. Continue reading on GitHub