> 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.
>
> [](https://x.com/Tokscale) | Follow [@Tokscale](https://x.com/Tokscale) on X for release notes and updates. |
> | :-----| :----- |
> [](https://discord.gg/h6DUGWdBbm) | Come hang out in our [Discord](https://discord.gg/h6DUGWdBbm) โ and surround yourself with the world's top-tier vibers. |
> [](https://github.com/sponsors/junhoyeo) | Support Tokscale's continued development through [GitHub Sponsors](https://github.com/sponsors/junhoyeo). |
> | [](https://github.com/junhoyeo) | Follow [@junhoyeo](https://github.com/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`](#social) 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 |
|------|----------|---------------|
| | [OpenCode](https://github.com/sst/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](https://docs.anthropic.com/en/docs/claude-code) | `~/.claude/projects/` and `~/.claude/transcripts/` |
| | [OpenClaw](https://openclaw.ai/) | `~/.openclaw/agents/` (`*/agent/openclaw-agent.sqlite` + `*/sessions/*.jsonl`; + legacy: `.clawdbot`, `.moltbot`, `.moldbot`) |
| | [Codex CLI](https://github.com/openai/codex) | `~/.codex/sessions/` and `~/.codex/archived_sessions/` (`*.jsonl` plus zstd-compressed `*.jsonl.zst` and other archive copies; copies of one rollout count once) |
| | [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) | `~/.prime/agent/sessions/` and `~/.prime/agent/session-artifacts/` (RLM child sessions) |
| | [Sakana Fugu](https://sakana.ai/fugu/) | via Codex โ rollouts in `~/.codex/sessions/` and `~/.codex/archived_sessions/` (`model_provider: sakana`) |
| | [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-the-github-copilot-coding-agent-in-cli) | `~/.copilot/session-store.db` (CLI usage events; no OTEL required), `~/.copilot/otel/*.jsonl` (+ `COPILOT_OTEL_FILE_EXPORTER_PATH`), `~/.copilot/data.db` |
| | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | `$HERMES_HOME/state.db` and `$HERMES_HOME/profiles/*/state.db` (fallback: `~/.hermes/...`) |
| | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `$GEMINI_CLI_HOME/tmp/*/chats/*.json` (fallback: `~/.gemini/tmp/*/chats/*.json`) |
| | [Cursor IDE](https://cursor.com/) | 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)](https://ampcode.com/) | `~/.config/tokscale/amp-cache/threads/` (`tokscale amp sync`) |
| | [Codebuff](https://codebuff.com/) | `~/.config/manicode/` (+ `manicode-dev`, `manicode-staging`; override via `CODEBUFF_DATA_DIR`) |
| | [Freebuff](https://github.com/CodebuffAI/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)](https://factory.ai/) | `~/.factory/sessions/` |
| | [Pi](https://github.com/badlogic/pi-mono) | `~/.pi/agent/sessions/` |
| | [omp (Oh My Pi)](https://github.com/can1357/oh-my-pi) | `~/.omp/agent/sessions/**/*.jsonl` |
| | [Senpi (OmO Native)](https://github.com/code-yeongyu/senpi) | `~/.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](https://kimchi.dev/) | `~/.config/kimchi/harness/sessions/` (override via `KIMCHI_CODING_AGENT_DIR`) |
| | [Reasonix](https://github.com/esengine/DeepSeek-Reasonix) | `~/.reasonix/stats/*.jsonl` (override via `REASONIX_STATE_HOME` or `REASONIX_HOME`) |
| | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) / [Kimi Code](https://github.com/MoonshotAI/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](https://github.com/QwenLM/qwen-cli) | `~/.qwen/projects/` |
| | [Roo Code](https://github.com/RooCodeInc/Roo-Code) | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/` (+ server: `~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/`) |
| | [Kilo](https://github.com/Kilo-Org/kilocode) | `~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/` (+ server: `~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/`) |
| | [Kilo CLI](https://github.com/nicepkg/kilo) | `~/.local/share/kilo/kilo.db` |
| | [Mux](https://github.com/coder/mux) | `~/.mux/sessions/` |
| | [Crush](https://crush.ai/) | `$XDG_DATA_HOME/crush/projects.json` (project registry; fallback: `~/.local/share/crush/projects.json`) |
| | [Goose](https://github.com/aaif-goose/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](https://antigravity.google/) | Cached via `tokscale antigravity sync` to `~/.config/tokscale/antigravity-cache/sessions/*.jsonl` (live RPC against the local language server) |
| | [Antigravity CLI](https://antigravity.google/) | `~/.gemini/antigravity-cli/conversations/*.db` (override the Gemini home via `GEMINI_CLI_HOME`; local SQLite, read directly โ no `antigravity sync` needed) |
| | [Antigravity IDE Extension](https://www.antigravity.google/docs/ide/extensions/) | `~/.gemini/antigravity/conversations/*.db` (local SQLite, read directly) |
| | [Trae IDE](https://www.trae.ai/) / [Trae Solo](https://www.trae.ai/solo) (international) | Cached via `tokscale trae sync` to `~/.config/tokscale/trae-cache/sessions/*.json` (account-level usage from the official API) |
| | [Warp](https://www.warp.dev/) / 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](https://zed.dev/docs/ai/agent-panel) | `~/.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](https://github.com/cline/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)](https://github.com/Yeachan-Heo/gajae-code) | `~/.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](https://cherry-ai.com/) | `%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](https://lmstudio.ai/) | `~/.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](https://github.com/unslothai/unsloth) | `$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](https://github.com/vectorize-io/hindsight) | `$HINDSIGHT_HOME/usage/*.jsonl` (fallback: `~/.hindsight/usage/*.jsonl`; populated via `tokscale hindsight sync`) |
| | [Jcode](https://github.com/1jehuang/jcode) | `~/.jcode/sessions/session_*.json` + `session_*.journal.jsonl` sidecars (override via `JCODE_HOME`) |
| | [MiMo Code](https://github.com/XiaomiMiMo/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](https://www.jetbrains.com/junie/) | `~/.junie/sessions/*/events.jsonl` |
| | [Command Code](https://github.com/CommandCodeAI/command-code) | `~/.commandcode/projects/**/*.jsonl` (v3 transcripts persist per-request usage and cost; estimated fallback only for legacy transcripts without a `usage` block) |
| | [ZCode](https://zcode.z.ai/) | `~/.zcode/cli/db/db.sqlite` (v2 usage database) and `~/.zcode/projects/**/*.jsonl` (legacy transcripts) |
| | [OpenCodeReview](https://github.com/alibaba/open-code-review) | `~/.opencodereview/sessions/**/*.jsonl` |
| | [CodeBuddy](https://www.codebuddy.cn/docs/cli/overview) (CLI, IDE, VS Code plugin) | `~/.codebuddy/projects/**/*.jsonl` + extension logs |
| | WorkBuddy | `~/.workbuddy/projects/**/*.jsonl` (5.5+ under `~/.workbuddy-ai/`) + SQLite fallback |
| | [Devin CLI](https://devin.ai/) | `~/.local/share/devin/cli/sessions.db` (SQLite) |
| | [Devin Desktop](https://devin.ai/) | ACP events: macOS `~/Library/Application Support/Devin/User/acp-events/`; Linux `~/.config/Devin/User/acp-events/`; Windows `%APPDATA%\Devin\User\acp-events\` |
| | [Augment Code](https://www.augmentcode.com/) (Auggie CLI) | `~/.augment/sessions/*.json` |
| | [Synthetic](https://synthetic.new/) | Re-attributed from other sources via `hf:` model prefix or `synthetic` provider (+ [Octofriend](https://github.com/synthetic-lab/octofriend): `~/.local/share/octofriend/sqlite.db`) |
| | [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | `~/.dsh/sessions/**/session.jsonl.zstd` (or `session.jsonl` when written uncompressed, plus versioned `session.v.jsonl[.zstd]` spellings; override via `DSH_HOME`) |
| | [MiniMax Code](https://github.com/MiniMax-AI) | `~/.config/tokscale/headless/mcode/*.jsonl` (headless capture of `mcode exec --output-format stream-json`; override via `TOKSCALE_HEADLESS_DIR`) |
| | [fx](https://github.com/vercel-labs/fx) | `~/.fx/sessions//usage-v2.json` (per-session aggregates) |
| | [Muse Code](https://dev.meta.ai/docs/muse-code) | `~/.local/share/muse/sessions/**/session.jsonl` (same XDG-style path on Windows; subagent transcripts under `subagent//` included) |
| | [Aside](https://asidehq.com) | `~/.aside/u//sessions//messages.jsonl` |
| | [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | `~/.vibe/logs/session//meta.json` (same path on Windows; override the root via `VIBE_HOME`) |
| | [Proma](https://github.com/proma-ai/Proma) | `~/.proma/agent-sessions/`, `~/.proma/sdk-config/{sessions,projects}/`; `~/.proma-dev/` |
| | [BB](https://getbb.app) | `~/.bb/bb.db`, `$BB_DATA_DIR/bb.db`, `~/.bb-dev/*/bb.db` |
Get real-time pricing calculations using [๐ LiteLLM's pricing data](https://github.com/BerriAI/litellm), with support for tiered pricing models and cache token discounts.
### Why "Tokscale"?
[](https://tokscale.ai)
This project is inspired by the **[Kardashev scale](https://en.wikipedia.org/wiki/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](#overview)
- [Why "Tokscale"?](#why-tokscale)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Prerequisites](#prerequisites)
- [Development Setup](#development-setup)
- [Building the Native Module](#building-the-native-module)
- [Usage](#usage)
- [Basic Commands](#basic-commands)
- [TUI Features](#tui-features)
- [Filtering by Platform](#filtering-by-platform)
- [Date Filtering](#date-filtering)
- [Pricing Lookup](#pricing-lookup)
- [Social](#social)
- [Autosubmit](#autosubmit)
- [Cursor IDE Commands](#cursor-ide-commands)
- [Antigravity Commands](#antigravity-commands)
- [Trae Commands](#trae-commands)
- [Warp/Oz Commands](#warpoz-commands)
- [Task-Attributed Report](#task-attributed-report)
- [Subscription Usage](#subscription-usage)
- [Example Output](#example-output---light-version)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [Frontend Visualization](#frontend-visualization)
- [Features](#features-1)
- [Running the Frontend](#running-the-frontend)
- [Social Platform](#social-platform)
- [Features](#features-2)
- [Getting Started](#getting-started)
- [Data Validation](#data-validation)
- [Wrapped 2025](#wrapped-2025)
- [Command](#command)
- [What's Included](#whats-included)
- [Development](#development)
- [Prerequisites](#prerequisites-1)
- [How to Run](#how-to-run)
- [Container Setup](#container-setup)
- [Supported Platforms](#supported-platforms)
- [Native Module Targets](#native-module-targets)
- [Windows Support](#windows-support)
- [Session Data Retention](#session-data-retention)
- [Data Sources](#data-sources)
- [Pricing](#pricing)
- [Local Usage Recovery Ledger](#local-usage-recovery-ledger)
- [Contributing](#contributing)
- [Development Guidelines](#development-guidelines)
- [Acknowledgments](#acknowledgments)
- [License](#license)
## Features
- **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, Mistral Vibe, Proma, and BB
- **Real-time pricing** - Fetches current pricing from LiteLLM with 1-hour disk cache; automatic OpenRouter fallback and Cursor model pricing for newly released models
- **Detailed breakdowns** - Input, output, cache read/write, and reasoning token tracking
- **Native Rust core** - All parsing and aggregation done in Rust for 10x faster processing
- **Web visualization** - Interactive contribution graph with 2D and 3D views
- **Flexible filtering** - Filter by platform, date range, or year
- **Task-attributed reports** - LLM-powered session summarization and task grouping with multi-backend support (Apple FM, Claude, Codex, Gemini, Kiro, MiniMax)
- **Export to JSON** - Generate data for external visualization tools
- **Social Platform** - Share your usage, compete on leaderboards, and view public profiles
## Installation
### Quick Start
```bash
# 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`](https://www.npmjs.com/package/swc)) that installs `@tokscale/cli`. Both install the same CLI with the native Rust core (`@tokscale/core`) included.
### Prerequisites
- [Node.js](https://nodejs.org/) or [Bun](https://bun.sh/)
- (Optional) Rust toolchain for building native module from source
### Development Setup
For local development or building from source:
```bash
# 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:
```bash
# 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
Use `tokscale --offline` for local reports without network requests. Prepare portable pricing caches with `tokscale pricing refresh --no-spinner` while connected. See [offline reporting](docs/offline.md) for supported commands and cache behavior.
### Basic Commands
```bash
# 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:
- **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/`) 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](#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). Until toggled, the TUI follows the terminal background reported by `COLORFGBG`
- `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](#configuration))
### Group-By Strategies
Press `g` in the TUI or use `--group-by` in `--light`/`--json` mode to control how model rows are aggregated:
| Strategy | Flag | TUI Default | Effect |
|----------|------|-------------|--------|
| **Model** | `--group-by model` | โ | One row per model โ merges all clients and providers |
| **Client + Model** | `--group-by client,model` | | One row per client-model pair |
| **Client + Provider + Model** | `--group-by client,provider,model` | | Most granular โ no merging |
| **Workspace + Model** | `--group-by workspace,model` | | Group local usage by workspace key, then model โ add [`--merge-worktrees`](#per-workspace-cost) to fold git worktrees into their repo |
| **Session + Model** | `--group-by session,model` | | One row per `session_id` and model โ attribute cost to a specific agent-CLI session |
| **Client + Session + Model** | `--group-by client,session,model` | | One row per client, session, and model โ useful for multi-agent runners that join on `session_id` |
| **Machine + Model** | `--group-by machine,model` | | One row per machine label and model โ see [Per-machine usage](#per-machine-usage) |
**`--group-by model`** (most consolidated)
| Clients | Providers | Model | Cost |
|---------|-----------|-------|------|
| OpenCode, Claude, Amp | github-copilot, anthropic | claude-opus-4-5 | $2,424 |
| OpenCode, Claude | anthropic, github-copilot | claude-sonnet-4-5 | $1,332 |
**`--group-by client,model`** (CLI default)
| Client | Provider | Model | Cost |
|--------|----------|-------|------|
| OpenCode | github-copilot, anthropic | claude-opus-4-5 | $1,368 |
| Claude | anthropic | claude-opus-4-5 | $970 |
**`--group-by client,provider,model`** (most granular)
| Client | Provider | Model | Cost |
|--------|----------|-------|------|
| OpenCode | github-copilot | claude-opus-4-5 | $1,200 |
| OpenCode | anthropic | claude-opus-4-5 | $168 |
| Claude | anthropic | claude-opus-4-5 | $970 |
**`--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:
```json
{
"groupBy": "session,model",
"entries": [
{
"sessionId": "019e1e27-af49-7cd1-89b7-7bad1c3f3be2",
"client": "codex",
"provider": "openai",
"model": "gpt-5",
"input": 25251,
"output": 47,
"cacheRead": 1920,
"cacheWrite": 0,
"reasoning": 40,
"messageCount": 12,
"cost": 0.0123
}
]
}
```
Use `--group-by client,session,model` when you also need the client name on every row (one spawn across all 20+ supported CLIs at once).
#### Per-workspace cost
`--group-by workspace,model` attributes usage to the directory an agent ran in, so you can see what a given project cost:
```bash
# 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]`).
#### Per-machine usage
If you copy other machines' session folders into local directories and add them with `scanner.extraScanPaths`, give each folder a machine label with `scanner.machineLabels`. Every session file under a labeled folder counts toward that machine; everything else counts toward `scanner.localMachineLabel` (default `"local"`):
```json
{
"scanner": {
"extraScanPaths": {
"codex": ["/Users/me/mirrors/steven/.codex/sessions"],
"claude": ["/Users/me/mirrors/steven/.claude/projects"]
},
"machineLabels": {
"/Users/me/mirrors/steven": "steven"
},
"localMachineLabel": "laptop"
}
}
```
A folder matches every file beneath it, compared on whole path components (case-insensitively on Windows); when folders nest, the longest one wins. Then group by machine:
```bash
# One row per (machine, model), with a Machine column
tokscale models --light --group-by machine,model
# JSON entries carry a `machine` field in this mode only
tokscale models --json --group-by machine,model
```
In the TUI, press `g` โ **Machine + Model**.
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.** `/.claude/worktrees/` (what agent CLIs create) and `/.git/worktrees/` are recognized from the path alone; a worktree checked out elsewhere (`git worktree add ../feature-x`) is recognized by reading its `.git` pointer file back to the repository. A repo reached through two different path spellings (a symlink and its target) still stays two rows, because a workspace identity is compared as a string. Totals are unaffected either way โ usage is split across rows, never lost or double counted.
- **Rows that would show the same name are qualified with their parent directory.** A label is the directory's own name, so `~/work/api` and `~/oss/api` would both read `api`; colliding labels gain as many leading path segments as it takes to tell them apart (`work/api`, `oss/api`), and when no path segment can โ the same directory recorded by two clients under different key formats โ the row is qualified with its workspace key instead. Grouping is unaffected โ this only changes the displayed text.
- **Clients that never record a workspace roll up into a single `Unknown workspace` row.** Roughly half the supported clients (including gemini, cursor, amp, droid, roocode, kilocode, goose, and Copilot's OTEL path) do not write one, so their usage cannot be attributed to a directory.
### Filtering by Platform
Use `--client` (short `-c`) to scope reports to one or more clients. The flag is repeatable, accepts comma-separated values, and works with every report command:
```bash
# 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`, `proma`, `bb`.
> **Breaking change (v4.0.0):** The per-client boolean flags (`--opencode`, `--claude`, `--codex`, etc.) have been removed and now error. Use the canonical `--client`/`-c` flag instead โ e.g. `tokscale --client opencode,claude`.
### Date Filtering
Date filters work across all commands that generate reports (`tokscale`, `tokscale models`, `tokscale monthly`, `tokscale graph`):
```bash
# Quick date shortcuts
tokscale --today # Today only
tokscale --yesterday # Yesterday only
tokscale --week # Last 7 days
tokscale --month # Current calendar month
# Custom date range (inclusive, local timezone)
tokscale --since 2024-01-01 --until 2024-12-31
# Filter by year
tokscale --year 2024
# Combine with other options
tokscale models --week --client claude --json
tokscale monthly --month --benchmark
```
> **Note**: Date filters use your local timezone. Both `--since` and `--until` are inclusive.
> **v2.2.0 note**: Session active-time daily buckets also use your local timezone, so users outside UTC may see active-time dates align with local token/cost report days instead of UTC day boundaries.
### Pricing Lookup
Look up real-time pricing for any model:
```bash
# Look up model pricing
tokscale pricing "claude-3-5-sonnet-20241022"
tokscale pricing "gpt-4o"
tokscale pricing "grok-code"
# Force specific provider source
tokscale pricing "grok-code" --provider openrouter
tokscale pricing "claude-3-5-sonnet" --provider litellm
# Inspect custom pricing overrides
tokscale pricing list-overrides
```
**Lookup Strategy:**
The pricing lookup uses a multi-step resolution strategy:
1. **Custom Pricing Overrides** - Exact user-defined entries from `~/.config/tokscale/custom-pricing.json`
2. **Exact Match** - Direct lookup in LiteLLM/OpenRouter databases
3. **Alias Resolution** - Resolves friendly names (e.g., `big-pickle` โ `glm-4.7`)
4. **Tier Suffix Stripping** - Removes quality tiers (`gpt-5.2-xhigh` โ `gpt-5.2`)
5. **Version Normalization** - Handles version formats (`claude-3-5-sonnet` โ `claude-3.5-sonnet`)
6. **Provider Prefix Matching** - Tries common prefixes (`anthropic/`, `openai/`, etc.)
7. **Cursor Model Pricing** - Hardcoded pricing for models not yet in LiteLLM/OpenRouter (e.g., `gpt-5.3-codex`)
8. **Fuzzy Matching** - Word-boundary matching for partial model names
### Custom Pricing Overrides
Create `custom-pricing.json` in Tokscale's config directory (`~/.config/tokscale/custom-pricing.json` on macOS/Linux by default; the same directory resolved by `TOKSCALE_CONFIG_DIR` when set) to override prices for model IDs that upstream pricing databases do not yet cover correctly.
```json
{
"models": {
"accounts/fireworks/routers/kimi-k2p6-turbo": {
"input_cost_per_million_tokens": 2.00,
"output_cost_per_million_tokens": 8.00,
"cache_read_input_token_cost_per_million_tokens": 0.30,
"source": "https://docs.fireworks.ai/serverless/pricing",
"notes": "Fireworks Kimi K2.6 Turbo (preview)"
},
"accounts/fireworks/models/kimi-k2p6": {
"input_cost_per_million_tokens": 0.95,
"output_cost_per_million_tokens": 4.00,
"cache_read_input_token_cost_per_million_tokens": 0.16
},
"kimi-k2p6-turbo": {
"input_cost_per_million_tokens": 2.00,
"output_cost_per_million_tokens": 8.00
}
}
}
```
The JSON schema is available at [schemas/custom-pricing.schema.json](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:
| Preferred (Original) | Deprioritized (Reseller) |
|---------------------|-------------------------|
| `xai/` (Grok) | `azure_ai/` |
| `anthropic/` (Claude) | `bedrock/` |
| `openai/` (GPT) | `vertex_ai/` |
| `google/` (Gemini) | `together_ai/` |
| `meta-llama/` | `fireworks_ai/` |
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).
#### Billing-channel pricing
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](docs/provider-pricing.md).
### Social
```bash
# 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
```
#### Unpriced usage is excluded from submission
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](#custom-pricing-overrides)) โ an explicit `0` declares a genuinely free model โ then re-run `tokscale submit --dry-run` until no warnings remain. `tokscale pricing ` 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
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.
```bash
# Enable periodic submission. Uses launchd on macOS, systemd user timers on Linux
# when available, cron as a Linux fallback, and Windows Task Scheduler on Windows.
tokscale autosubmit enable --interval 24h
# Keep the same client and date filters you would pass to submit.
tokscale autosubmit enable --interval 2h --client opencode,claude --week
# Show saved settings and the last run/error.
tokscale autosubmit status
tokscale autosubmit status --json
# Run once now, even if the saved interval has not elapsed.
tokscale autosubmit run --force
# Disable autosubmit and remove the scheduler entry.
tokscale autosubmit disable
```
Scheduled runs are non-interactive: they never prompt for GitHub auth or star confirmation. Run `tokscale login --token tt_xxx` once, or set `TOKSCALE_API_TOKEN` in the scheduler environment. Tokscale records scheduler state in `settings.json`, writes logs under `~/.config/tokscale/autosubmit/`, and uses a lock file so overlapping scheduler ticks do not submit twice.
### Cursor IDE Commands
Cursor IDE support uses Cursor's usage-events API. Tokscale caches usage at `~/.config/tokscale/cursor-cache/usage.json` (or `${TOKSCALE_CONFIG_DIR}/cursor-cache/` when overridden) for the active account and `usage.account-.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`.
```bash
# 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-.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 ` for one run, or save `cursor.syncTimeoutSeconds` in `settings.json` (by default `~/.config/tokscale/settings.json`; see [Configuration](#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.
`tokscale submit` also syncs Cursor usage before uploading. It defaults to a 15-second budget, honors `cursor.syncTimeoutSeconds` from `settings.json` when configured, and accepts `--timeout ` (or `--cursor-timeout `) to override the budget for that submission.
```json
{
"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 Commands
Antigravity sync currently works on macOS and Linux only. The Antigravity-enabled editor must be running and its local language server available; tokscale reads usage from that local language server and caches normalized artifacts locally.
```bash
# Check whether tokscale can see running Antigravity language servers
tokscale antigravity status
# Sync usage from local Antigravity language servers into tokscale's cache
tokscale antigravity sync
# Delete the cached Antigravity artifacts
tokscale antigravity purge-cache
```
**Cache location**: `~/.config/tokscale/antigravity-cache/`
**How it works**: `tokscale antigravity sync` discovers local Antigravity session candidates, fetches confirmed usage data from the local language server RPC, and stores normalized JSONL artifacts for tokscale-core to parse later. Run sync before reports if you want the freshest Antigravity data.
### Trae Commands
Trae ([ByteDance's AI IDE](https://www.trae.ai/)) 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.
```bash
# 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.
#### Sync-lock recovery during upgrades
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 Commands
Warp/Oz does not expose local token transcripts. Tokscale only syncs the aggregate request and spend counters returned by Warp's GraphQL API, then reports them as `warp` / `aggregate-requests` rows with zero token buckets.
```bash
# Save a bearer token or Cookie header copied from an authenticated Warp request
tokscale warp login
# Inspect credential/cache state and diagnostics
tokscale warp status
# Sync aggregate requests and spend into tokscale's local cache
tokscale warp sync
# Remove saved credentials; add --purge-cache to delete synced usage too
tokscale warp logout --purge-cache
```
**Cache location**: `~/.config/tokscale/warp-cache/usage.json`
**How it works**: `tokscale warp sync` calls Warp's authenticated GraphQL API for account and workspace aggregate counters. Tokscale preserves request counts as message counts and vendor-reported spend as cost, but it never converts requests into synthetic tokens. Warp is excluded from default `submit` data because the public leaderboard accepts token-attributed usage, not aggregate request counters.
### Task-Attributed Report
The `report` command generates a task-attributed usage breakdown. It uses an LLM to summarize each session into a short title and category, then groups related sessions into high-level task clusters for a bird's-eye view of where your tokens went.
```bash
# 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:**
| Backend | Command | Notes |
|---------|---------|-------|
| `apple-fm` | (default) | On-device Apple Foundation Models via native Rust FFI (no Python). Enabled in the prebuilt Apple Silicon (macOS arm64) binary; runs on macOS 26+ with Apple Intelligence on, and transparently falls back to a built-in Rust heuristic everywhere else (Intel Macs, older macOS, Linux, Windows) โ so the default works on every platform. |
| `claude` | `claude -p` | Requires Claude Code CLI installed and authenticated. |
| `codex` | `codex --quiet` | Requires Codex CLI installed and authenticated. |
| `gemini` | `gemini -p` | Requires Gemini CLI installed and authenticated. |
| `kiro` | `kiro --non-interactive` | Requires Kiro CLI installed and authenticated. |
| `minimax` | (HTTP API) | OpenAI-compatible chat-completions API, so no CLI is needed. Set `MINIMAX_API_KEY` or `MINIMAX_API_TOKEN`. Defaults to `MiniMax-M3.1-Flash` on the global endpoint (`https://api.minimax.io/v1`); set `MINIMAX_API_REGION=cn` to use `https://api.minimaxi.com/v1`, and `MINIMAX_MODEL` to select another model (for example `MiniMax-M3`). |
**How it works:**
1. Sessions are scanned and inserted into a local SQLite wiki database (`wiki.db` in your platform config dir โ e.g. `~/.config/tokscale/` on Linux, `~/Library/Application Support/tokscale/` on macOS)
2. Unsummarized sessions are sent to the chosen LLM backend in batches, which returns a title, category, description, and complexity for each
3. A second LLM pass groups all titled sessions into 3โ8 high-level task clusters (e.g. "Kiro Auth", "Tokscale Report", "System Config")
4. Results are cached in the wiki DB โ subsequent runs skip already-summarized sessions
**Example output:**
```
Task Group Sess Tokens Cost
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Tokscale Development 19 4.2B $22.66
Add task-attributed report command
Implement wiki DB schema
Fix pricing lookup for new models
System Config 28 2.1B $10.06
Configure OpenCode workspace settings
Update shell aliases
Kiro Auth 4 890.5M $3.10
Implement JWT refresh flow
```
### Subscription Usage
Tokscale can fetch and display your real-time subscription quota across AI providers. This shows how much of your plan you've used and when limits reset.
```bash
# Show subscription usage for all detected providers
tokscale usage
# Output as JSON (for scripting)
tokscale usage --json
# Lightweight terminal output (no TUI)
tokscale usage --light
```
In the TUI, navigate to the **Usage** tab to see subscription data. Use `[Refresh]` to refresh subscription quotas. The keyboard refresh shortcut `r` uses the same refresh path.
> **Note**: Subscription quotas and balances are **vendor-reported** โ tokscale calls each provider's own quota endpoint and surfaces the response verbatim. Numbers reflect what the provider reports (which is also what shows up in their official dashboards) and are not independently verified against tokscale's own usage tracking.
#### Supported Providers
| Provider | Auth Method | Metrics | Setup |
|----------|-------------|---------|-------|
| **Claude** | OAuth (credentials file or macOS Keychain) | Session (5hr), Weekly, model-scoped quotas | Run `claude` to log in |
| **Codex** (OpenAI) | OAuth (Codex auth, saved Tokscale accounts, or OpenCode's `$XDG_DATA_HOME/opencode/auth.json`) | Session, Weekly quotas | Use `[Add Codex]`, run `codex`, import with `tokscale codex import --name work`, or connect OpenAI with ChatGPT Plus/Pro in OpenCode |
| **Z.ai** | API key (env var) | Token limits, Web Searches | Set `ZAI_API_KEY` or `GLM_API_KEY` |
| **Amp** | API key (`~/.local/share/amp/secrets.json`) | Free tier balance, Credits | Run `amp` to log in |
| **GitHub Copilot** | GitHub token (keychain or `~/.config/gh/hosts.yml`) | Premium interactions, Chat quotas | Run `gh auth login` |
| **Cursor** | Desktop `state.vscdb` JWT (or macOS Keychain `cursor-access-token`, or JWT inside a saved `tokscale cursor login` session) | Cursor Models and Other Models plan quotas (one Weekly pool on unified plans) | Sign in to Cursor desktop, or run `tokscale cursor login` |
| **Grok Bot** | Cursor desktop JWT (with macOS Keychain refresh when available) | Weekly personal quota | Sign in to Cursor desktop; shown when a personal quota is available |
| **Grok** | OAuth (`~/.grok/auth.json`) | Included credits (weekly or monthly), subscription plan | Run `grok login` |
| **Kimi** | OAuth (`~/.kimi/credentials/kimi-code.json`) | Session, Weekly quotas | Run `kimi` to log in |
| **MiniMax** | API key (env var) | Prompt quotas per model | Set `MINIMAX_API_KEY` or `MINIMAX_API_TOKEN` |
| **MiniMax Token Plan** | API key (env var) | Interval + weekly remaining-percent quotas (per region: CN minimaxi.com + Global minimax.io) | Set `MINIMAX_TOKEN_PLAN_CN_KEY` and/or `MINIMAX_TOKEN_PLAN_GLOBAL_KEY` |
| **OpenCode Go** | API key (`~/.local/share/opencode/auth.json` or env var) | Rolling, Weekly, Monthly quotas | Run `/connect` in OpenCode, or set `OPENCODE_API_KEY` |
| **Sakana** (Fugu) | Session cookie (env var or file) โ billing-console HTML scrape, no public API | 5-hour, Weekly quota windows (plan tier + monthly price as metadata) | Set `SAKANA_SESSION_COOKIE` (see [docs/providers/sakana.md](docs/providers/sakana.md)) |
Providers are auto-detected โ only those with valid credentials are shown. If a provider is missing, ensure you've logged in or set the required environment variable.
#### Codex Multi-Account Usage
Tokscale can save multiple Codex OAuth accounts for subscription usage display. The TUI Usage tab groups saved accounts under one **Codex** section. The active account is marked with `*`; inactive accounts can be selected with `[Use]`; account removal uses `[Remove]` followed by `[Confirm]`.
To add an account without leaving the TUI, click `[Add Codex]` in the Usage tab. Tokscale starts `codex login` with a temporary `CODEX_HOME`, displays the login output in the Usage tab, imports the resulting auth into Tokscale's saved account store, and then refreshes usage. This keeps the login isolated and does not switch the current Codex auth; click `[Use]` on a saved account when you want Tokscale to write that account into the real Codex auth file.
The CLI commands are still available for scripted or manual account management, plus a separate opt-in account-activity snapshot:
```bash
# 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.
#### Example Output
```
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Session 85% left [=========---] resets in 2h 15m โ
โ Weekly 72% left [========----] resets Fri 3pm โ
โ Plan Max 20x โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Session 40% left [=====-------] resets in 4h 30m โ
โ Weekly 90% left [==========--] resets Mon 12am โ
โ Account user@example.com โ
โ Plan Pro โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
### Example Output (`--light` version)
### Configuration
Tokscale stores settings in `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:
```json
{
"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"
]
}
}
}
```
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `colorPalette` | string | `"blue"` | TUI color theme (green, halloween, teal, blue, pink, purple, orange, monochrome, ylgnbu, graphite, lagoon, dusk, tokyo-night, catppuccin, solarized, gruvbox, gruvbox-material, one-dark) |
| `glyphs` | `"auto"` \| `"unicode"` \| `"ascii"` | `"auto"` | TUI glyph policy. `auto` probes the terminal's ambiguous-character width at startup; use `unicode` or `ascii` to override detection for terminals that do not answer the probe correctly. Invalid values safely fall back to `auto`. |
| `includeUnusedModels` | boolean | `false` | Show models with zero tokens in reports |
| `autoRefreshEnabled` | boolean | `false` | Enable auto-refresh in TUI |
| `autoRefreshMs` | number | `60000` | Auto-refresh interval (30000-3600000ms) |
| `nativeTimeoutMs` | number | `300000` | Maximum time for native subprocess processing (5000-3600000ms) |
| `defaultClients` | string[] | `[]` | Client filter applied when no `--client/-c` flag is passed. Accepts the same ids as `--client` (e.g. `["opencode", "claude", "synthetic"]`). Unknown ids are silently dropped. CLI flags always override this list completely โ no merging. |
| `usage.disabledProviders` | string[] | `[]` | Subscription-usage providers to skip before credential discovery or network access. Valid ids (case-insensitive; surrounding whitespace ignored): `claude`, `codex`, `zai`, `amp`, `antigravity`, `copilot`, `cursor`, `grok-bot`, `grok`, `kimi`, `minimax`, `minimax-token-plan`, `warp`, `sakana`, and `opencode-go`. Legacy `grok-build`, `grok_build`, and `Grok Build` aliases also select `grok`. Unknown ids are ignored. Disabled providers are also hidden from cached TUI cards and diagnostics. Changes apply to the next `tokscale usage` run or TUI launch/refresh. |
| `light.writeCache` | boolean | `false` | When true, `tokscale --light` overwrites the TUI cache atomically after rendering. CLI flags `--write-cache` / `--no-write-cache` override per-invocation. |
| `minutelyTabEnabled` | boolean | `false` | Show the per-minute Minutely tab in the TUI and aggregate per-minute usage during data loading. Default-off because minute-granularity is a niche/diagnostic view for most users and the per-minute bucketing has a non-trivial cost on large datasets. |
| `autosubmit` | object | disabled | Saved `tokscale autosubmit` state: interval, client/date filters, scheduler backend, last run time, and last error. Prefer `tokscale autosubmit enable/status/disable` over editing this object by hand. |
| `cursor.syncTimeoutSeconds` | number | unset | Overall time budget, in seconds (1-86400), for each account's usage download in `tokscale cursor sync` and pre-report sync in `tokscale submit`. When unset, the budget starts at 120 s and grows with the number of usage events Cursor reports (15 s default during submit). `tokscale cursor sync --timeout ` and `tokscale submit --timeout ` override it for one run. See [Cursor IDE Commands](#cursor-ide-commands). |
| `scanner.extraScanPaths` | object | `{}` | Additional per-client scan roots for sessions outside Tokscale's default home-root locations |
| `scanner.machineLabels` | object | `{}` | Machine label for each folder, as `{ "": "