Stop Guessing Your AI Costs: Tokscale Exposes Every Token

Stop Guessing Your AI Costs: Tokscale Exposes Every Token

Your AI coding bill just arrived—and it's terrifying. You swore you only used Claude Code for "a quick refactor," but your invoice tells a different story. Hundreds of dollars evaporated into tokens you can't trace, models you don't remember choosing, and agents whose names you barely recognize. Sound familiar?

Here's the dirty secret most developers won't admit: we're flying blind. We obsess over cloud compute costs, meticulously optimize CI/CD minutes, yet treat AI tokens like Monopoly money—until the monthly statement slaps us awake. The average developer now juggles five different coding assistants daily. Claude Code for architecture, Cursor for quick edits, Codex CLI for automation, Gemini for research, OpenCode for the new project you started Tuesday. Each burns tokens differently. Each hides its consumption in obscure log files and proprietary databases. Nobody consolidates this mess. Nobody, that is, until now.

Enter Tokscale—the high-performance CLI tool and visualization dashboard that transforms token chaos into crystal-clear intelligence. Built by prolific open-source creator Junho Yeo, Tokscale doesn't just count tokens; it reveals your complete AI consumption fingerprint across 20+ platforms with real-time pricing, stunning terminal UIs, and a social leaderboard that turns cost tracking into competitive sport. Whether you're burning millions of tokens daily or carefully rationing your Claude budget, Tokscale exposes exactly where every penny goes. And the best part? It installs in under ten seconds with zero configuration.

What Is Tokscale?

Tokscale is a native Rust-powered CLI tool with an interactive Terminal User Interface (TUI) and web visualization platform designed to track, analyze, and socialize token usage from virtually every AI coding assistant in existence. Born from Junho Yeo's fascination with the Kardashev scale—the astrophysicist's framework for measuring civilizations by energy consumption—Tokscale applies the same cosmic thinking to developer productivity. Tokens are the new energy. They power our reasoning, fuel our output, and increasingly dominate our infrastructure budgets.

The project emerged from a genuine pain point: as AI coding agents proliferated, developers lost visibility into their aggregate consumption. Each tool—Claude Code, Cursor, Codex CLI, OpenCode—stores session data in incompatible formats across disparate locations. Some use SQLite databases. Others dump JSONL files. A few require API scraping. Tokscale unifies this fragmentation through a sophisticated native Rust core that performs parallel file scanning and SIMD JSON parsing, delivering approximately 10x faster processing than pure JavaScript^{↗ Bright Coding Blog} alternatives.

Version 2 represents a significant evolution, introducing a complete Rust TUI powered by Ratatui, cross-platform support including Windows, and a social platform with global leaderboards. The tool has garnered substantial community traction with multilingual documentation (English, Korean, Japanese, Chinese), active Discord engagement, and a growing ecosystem of contributors. What started as a personal utility has become the de facto standard for AI cost transparency in developer tooling.

Key Features That Separate Tokscale from Everything Else

Interactive TUI with Six Specialized Views. Tokscale's default mode launches a gorgeous terminal interface with zero flicker rendering, mouse support, and keyboard navigation. Cycle through Overview (charts plus top models), Models (detailed breakdown), Daily (calendar aggregation), Hourly (time-of-day patterns), Stats (GitHub-style contribution graph), and Agents (per-tool analysis). Switch views with 1-6 or arrow keys, sort by cost/date/tokens with single keystrokes, and cycle through nine color themes including Halloween and Monochrome.

Native Rust Core for Insane Performance. All parsing and aggregation execute in Rust through napi-rs bindings, achieving ~8.5x total speedup over TypeScript equivalents. File discovery drops from 500ms to 50ms. JSON parsing accelerates from 800ms to 100ms. Memory consumption shrinks by ~45% through streaming parsing and zero-copy string handling. For developers processing thousands of session files with hundreds of thousands of messages, this performance delta transforms Tokscale from "nice to have" to "essential infrastructure."

Real-Time Pricing with Intelligent Fallbacks. Tokscale fetches current pricing from LiteLLM's database with one-hour disk caching. When models haven't reached LiteLLM yet, it automatically queries OpenRouter's endpoints API for author pricing. For bleeding-edge releases like gpt-5.3-codex, hardcoded Cursor pricing fills gaps temporarily. The system even handles tiered pricing (200k+ token thresholds) and cache token discounts—complexities most tools ignore entirely.

Multi-Platform Session Archaeology. Tokscale doesn't just read files; it performs forensic reconstruction across incompatible storage systems. SQLite databases (OpenCode, Hermes, Kilo CLI, Goose), JSONL event streams (Claude Code, Codex CLI, Copilot OTEL), nested chat directories (Gemini, Pi, Amp), VS Code globalStorage (Roo Code, Kilo), API-synchronized caches (Cursor), and even live RPC against local language servers (Antigravity). Each platform requires distinct parsing logic, path resolution strategies, and schema versioning.

Flexible Aggregation Strategies. Press g in the TUI or use --group-by to control granularity. Merge all clients per model for consolidated views. Split by client-model pairs for attribution. Go fully granular with client-provider-model triplets when you need to distinguish OpenCode's Anthropic usage from its GitHub Copilot routing.

Social Platform and Gamification. Submit usage to tokscale.ai, compete on global leaderboards, generate shareable "Wrapped 2025" year-in-review images, and embed live stats badges in your GitHub profile. The social layer transforms solitary cost anxiety into transparent community benchmarking.

Real-World Use Cases Where Tokscale Dominates

Scenario 1: The Multi-Agent Freelancer. You contract across teams using different AI stacks—one client mandates Claude Code, another standardized on Cursor, a third experiments with OpenCode. Your monthly AI spend exceeds $800 but you can't attribute costs to specific projects for accurate billing. Tokscale's --client filtering and JSON export enable precise client invoicing. Run tokscale --client claude --since 2025-01-01 --until 2025-01-31 --json > client-a-january.json and transform opaque consumption into itemized expense reports.

Scenario 2: The Engineering Manager Scaling Team AI Adoption. Your twenty-person team adopted Copilot CLI, then Claude Code, then individual developers started using Gemini and Kimi without oversight. Budget requests arrive inflated with guesswork. Tokscale's aggregated TUI Overview and --group-by client,model reports reveal actual consumption patterns, identify redundant tool proliferation, and justify consolidation decisions with hard data rather than developer anecdotes.

Scenario 3: The Cost-Conscious Indie Hacker. Bootstrapping on ramen profitability, every token matters. You're optimizing between Claude Sonnet and Haiku, debating whether Cursor's convenience justifies its premium. Tokscale's real-time pricing lookup (tokscale pricing "claude-3-5-sonnet-20241022") and model-by-model cost breakdowns enable deliberate economic choices. The contribution graph visualizes usage streaks, helping you build sustainable habits rather than binge-and-purge cycles.

Scenario 4: The CI/CD Pipeline Auditor. Your automated workflows invoke Codex CLI for code review, documentation generation, and test synthesis. Token costs scale linearly with commit frequency but nobody tracks this infrastructure spend. Tokscale's headless mode captures codex exec --json output to ~/.config/tokscale/headless/codex/, enabling automated usage reporting in GitHub Actions without interactive sessions.

Scenario 5: The Competitive Developer Optimizing for Leaderboard Rank. You've embraced Tokscale's social platform, submitting usage weekly. The global leaderboard motivates efficient token utilization—higher output quality per input token, strategic cache exploitation, model selection discipline. Your public profile at tokscale.ai/u/yourname showcases your journey, and the embedded SVG badge in your GitHub README signals your AI-native development credibility.

Step-by-Step Installation & Setup Guide

Tokscale prioritizes zero-configuration immediacy. Choose your preferred runtime:

# Fastest path: run directly with npx (no installation)
npx tokscale@latest

# Or with Bun for superior performance
bunx tokscale@latest

# Or with Deno, no alias needed
deno x npm:tokscale@latest

# Lightweight table-only mode (no TUI dependencies)
npx tokscale@latest --light

That's the complete installation for most users. The tokscale npm package is an alias for @tokscale/cli, which bundles the native Rust core (@tokscale/core) with prebuilt binaries for macOS (x86_64, aarch64), Linux (x86_64, aarch64, glibc, musl), and Windows (x86_64, aarch64).

For local development or source builds:

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

# Install Bun if needed
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Build native Rust module (required for CLI operation)
bun run build:core

# Run in development mode
bun run cli

Platform-Specific Prerequisites:

• Node.js 18+ or Bun 1.0+
• Rust toolchain (only for building native module from source; prebuilt binaries included in npm install)

Critical Configuration for Accurate Tracking:

Some platforms aggressively delete old sessions. Extend retention before Tokscale can analyze history:

// ~/.claude/settings.json — prevent Claude's 30-day auto-cleanup
{
  "cleanupPeriodDays": 9999999999
}

// ~/.gemini/settings.json — disable Gemini cleanup if enabled
{
  "general": {
    "sessionRetention": {
      "enabled": false
    }
  }
}

Custom Configuration (~/.config/tokscale/settings.json):

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

The defaultClients array scopes all unflagged invocations to your active tools. scanner.extraScanPaths handles project-specific session directories outside default home locations.

REAL Code Examples from the Repository

Example 1: Basic TUI Launch and View Navigation

# Launch interactive TUI (default command)
tokscale

# Launch directly to specific tabs
tokscale models      # Models breakdown tab
tokscale monthly     # Daily view with calendar aggregation
tokscale hourly      # Hour-of-day usage patterns

# Explicit TUI launch (equivalent to bare tokscale)
tokscale tui

The TUI provides six views accessible via 1-6 or ←/→/Tab. The Overview combines a sparkline chart with top models ranking. Models view enables c/d/t sorting by cost, date, or tokens. The Stats view renders a GitHub-style contribution graph with nine color palettes cycled via p. Press e to export any view's data as JSON, r to refresh from disk, q to quit. Mouse support allows clicking tabs and buttons directly.

Example 2: JSON Export for Automation and Scripting

# Default models view as structured JSON
tokscale --json

# Specific report types as JSON
tokscale models --json              # Per-model breakdown
tokscale monthly --json             # Monthly calendar aggregation
tokscale graph --output data.json   # Contribution graph data for visualization

# Save to file for downstream processing
tokscale models --json > report.json

# Combine with filters for targeted extraction
tokscale models --week --client claude --json > weekly-claude.json

JSON output transforms Tokscale from interactive tool into pipeline infrastructure. Pipe to jq for filtering, feed to custom dashboards, or archive for compliance auditing. The --json flag works with every report command, maintaining consistent schema across views.

Example 3: Multi-Client Filtering and Date Scoping

# Single client isolation
tokscale --client opencode

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

# Repeated flag (equivalent, shell-alias friendly)
tokscale -c opencode -c claude

# Date shortcuts
tokscale --today
tokscale --week
tokscale --month

# Custom inclusive date range
tokscale --since 2024-01-01 --until 2024-12-31

# Year filtering
tokscale --year 2024

# Complex combined query
tokscale models --week --client opencode,claude --json

The --client flag accepts all supported platform identifiers: opencode, claude, codex, copilot, gemini, cursor, amp, codebuff, droid, openclaw, hermes, pi, kimi, qwen, roocode, kilocode, kilo, mux, crush, goose, antigravity, synthetic. Legacy single-client flags (--opencode, --claude, etc.) remain functional but emit deprecation warnings. Date filters use local timezone and inclusive boundaries, ensuring no session edge cases escape capture.

Example 4: Social Platform Authentication and Submission

# Interactive GitHub authentication (opens browser)
tokscale login

# Headless CI authentication with pre-generated token
tokscale login --token tt_xxx

# Verify current identity
tokscale whoami

# Submit usage to global leaderboard
tokscale submit

# Filtered submission (only specific clients and date range)
tokscale submit --client opencode,claude --since 2024-01-01

# Dry-run to preview without uploading
tokscale submit --dry-run

# Environment-variable authentication for CI/CD
TOKSCALE_API_TOKEN=tt_xxx tokscale submit

# Revoke local credentials
tokscale logout

The social platform transforms personal tracking into community participation. Submitted data undergoes Level 1 validation: mathematical consistency checks, future-date rejection, required field verification, and duplicate detection. The TOKSCALE_API_TOKEN environment variable enables secure CI/CD integration without credential files.

Example 5: Cursor IDE API Integration

# Authenticate with Cursor session token
tokscale cursor login --name work

# Verify authentication and session validity
tokscale cursor status

# List all saved Cursor accounts
tokscale cursor accounts

# Manually refresh cached usage data
tokscale cursor sync

# Switch active account for aggregation
tokscale cursor switch work

# Logout (preserves history in archive)
tokscale cursor logout --name work

# Purge cached data entirely
tokscale cursor logout --name work --purge-cache

Cursor requires special handling because it stores usage behind an authenticated API rather than local files. The session token extraction process involves browser Developer Tools: either capturing the WorkosCursorSessionToken cookie from Network tab request headers, or copying it directly from Application → Cookies. Critical security note: this token grants full Cursor account access—treat it as a password, never commit it to version control. Tokscale caches API responses at ~/.config/tokscale/cursor-cache/ and aggregates across multiple saved accounts by default.

Advanced Usage & Best Practices

Optimize Group-By Strategy for Your Question. Use --group-by model when asking "How much did I spend on Claude Opus across all tools?" Employ --group-by client,model when attributing costs to specific platforms. Reserve --group-by client,provider,model for debugging routing discrepancies—like why OpenCode's Claude usage costs differ from direct Claude Code invocation.

Leverage Headless Mode for CI/CD Economics. Codex CLI's exec --json outputs raw token events to stdout. Capture these systematically:

mkdir -p ~/.config/tokscale/headless/codex
codex exec --json "implement feature" > ~/.config/tokscale/headless/codex/$(date +%Y%m%d-%H%M%S).jsonl

Then aggregate with standard Tokscale commands. This pattern enables per-PR cost tracking, budget-gated workflows, and automated spend alerting.

Configure Persistent Defaults. Rather than typing --client opencode,claude repeatedly, set defaultClients in settings.json. This scopes all unqualified invocations to your actual toolkit, reducing cognitive overhead and preventing accidental full scans across dormant platforms.

Monitor Native Timeout for Large Histories. The default nativeTimeoutMs of 300000ms (5 minutes) suffices for most users. If processing thousands of sessions across years of history, increase via TOKSCALE_NATIVE_TIMEOUT_MS=600000 or config adjustment.

Cache Management for Troubleshooting. Tokscale's cache directory (~/.config/tokscale/cache/) is entirely regenerable. Delete freely when diagnosing stale pricing, corrupted TUI state, or migration issues. The system repopulates automatically on next invocation.

Comparison with Alternatives

Tokscale's primary differentiation is comprehensive integration depth combined with performance optimization and social features. While ccusage inspired aspects of Tokscale's approach, it lacks the breadth of platform support, real-time pricing infrastructure, and visualization ecosystem. Manual scripts solve specific problems but impose perpetual maintenance burden as AI tools evolve their storage formats. Cloud dashboards from individual vendors (Cursor, Claude) show only their own usage, forcing developers into fragmented, incomplete visibility.

FAQ: Common Developer Concerns

Does Tokscale send my code or prompts to external servers? No. Tokscale reads token metadata (counts, model names, timestamps, costs) from local session files and databases. Your actual code, prompts, and responses never leave your machine. The optional social platform only uploads aggregated statistics—total tokens, costs, active days—not conversation content.

How accurate is the pricing calculation? Tokscale fetches live pricing from LiteLLM with hourly caching, falls back to OpenRouter for unreleased models, and uses Cursor-sourced hardcoding for bleeding-edge releases. Pricing includes input, output, cache read/write, and reasoning tokens with tiered thresholds. Accuracy depends on upstream data freshness; report discrepancies to GitHub issues.

Will Tokscale slow down my system? The native Rust core is optimized for minimal overhead. Typical scans of 1000 session files complete in ~175ms with ~45% lower memory than pure JavaScript alternatives. Processing runs on demand, not as a background daemon. The TUI renders at 60fps with zero flicker.

Can I use Tokscale in my company's CI/CD pipeline? Absolutely. Headless mode captures Codex CLI JSON output for automated tracking. Use TOKSCALE_API_TOKEN for authenticated leaderboard submissions without browser interaction. Set TOKSCALE_CONFIG_DIR for sandboxed environments. All operations support non-interactive execution.

What happens when AI tools change their data formats? Tokscale's active maintenance tracks upstream changes. The project has 15+ contributors and weekly releases. Format changes are addressed promptly; subscribe to releases or join the Discord for update notifications.

Is Windows fully supported? Yes. Tokscale provides native binaries for Windows x86_64 and aarch64. TUI, CLI, and all features work identically to macOS and Linux. Session paths map automatically (~ expands to %USERPROFILE%).

How do I prevent duplicate counting across synced devices? Tokscale processes local files only; it doesn't merge across machines. For multi-device usage, either submit to the social platform (which deduplicates by session ID) or consolidate session directories via sync before scanning.

Conclusion: Your Tokens, Your Visibility, Your Competitive Edge

The AI coding revolution has a hidden tax: opacity. Every token consumed without measurement is a budgeting failure waiting to happen, an optimization opportunity missed, a competitive disadvantage accumulated. Tokscale transforms this darkness into daylight—comprehensive, beautiful, performant daylight that spans every major platform and renders in your terminal in milliseconds.

I've watched tools come and go in the developer productivity space. Most solve narrow problems. Most fragment further what was already fragmented. Tokscale is different. It's architecturally ambitious (native Rust core, multi-platform forensic parsing, real-time pricing infrastructure) yet immediately accessible (ten-second installation, zero configuration, intuitive TUI). It's personally powerful (detailed cost attribution, flexible filtering, JSON automation) yet socially engaging (leaderboards, Wrapped 2025, embeddable badges).

The Kardashev scale measures civilizations by their energy mastery. As developers, our energy is tokens—our capacity to reason, create, and ship at scale. Tokscale doesn't just count this energy; it helps you harness it deliberately. From planetary dabbling to galactic code architecture, your trajectory becomes visible, optimizable, and shareable.

Stop guessing. Start measuring. Scale intentionally.

Install Tokscale now: npx tokscale@latest or visit github.com/junhoyeo/tokscale to star the repository, read the source, and join a community of developers who refuse to fly blind. Your future self—and your accounting department—will thank you.