If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/junhoyeo/tokscale shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 19 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live junhoyeo/tokscale repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/junhoyeo/tokscale.

What it runs against: a local clone of junhoyeo/tokscale — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in junhoyeo/tokscale | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of junhoyeo/tokscale. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/junhoyeo/tokscale.git
#   cd tokscale
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of junhoyeo/tokscale and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "junhoyeo/tokscale(\\.git)?\\b" \\
  && ok "origin remote is junhoyeo/tokscale" \\
  || miss "origin remote is not junhoyeo/tokscale (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/tokscale-cli/src/main.rs" \\
  && ok "crates/tokscale-cli/src/main.rs" \\
  || miss "missing critical file: crates/tokscale-cli/src/main.rs"
test -f "crates/tokscale-core/src/lib.rs" \\
  && ok "crates/tokscale-core/src/lib.rs" \\
  || miss "missing critical file: crates/tokscale-core/src/lib.rs"
test -f "crates/tokscale-core/src/clients.rs" \\
  && ok "crates/tokscale-core/src/clients.rs" \\
  || miss "missing critical file: crates/tokscale-core/src/clients.rs"
test -f "crates/tokscale-cli/src/tui/mod.rs" \\
  && ok "crates/tokscale-cli/src/tui/mod.rs" \\
  || miss "missing critical file: crates/tokscale-cli/src/tui/mod.rs"
test -f "crates/tokscale-core/src/parser.rs" \\
  && ok "crates/tokscale-core/src/parser.rs" \\
  || miss "missing critical file: crates/tokscale-core/src/parser.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/junhoyeo/tokscale"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Tokscale is a high-performance CLI tool and TUI dashboard (written in Rust) that aggregates and visualizes token usage and costs across 25+ AI coding agents (Claude, Cursor, OpenCode, Kimi, Gemini, etc.). It tracks prompt/completion tokens, model usage patterns, and costs with a native Ratatui-based terminal UI, cross-platform support, and a web dashboard with 2D/3D contribution graphs. Monorepo workspace with two crates: crates/tokscale-core (shared token parsing/cost calculation engine) and crates/tokscale-cli (Clap CLI + Ratatui TUI frontend). Cross-platform config via dirs XDG paths, SQLite persistence for historical data via Rusqlite bundled, and async I/O via Tokio. Data ingestion from 25+ client log formats parsed and aggregated in the core crate.

AI coding agent power users and developers who run multiple copilot-style tools (Cursor, Claude Code, OpenClaw, Pi, etc.) and need centralized visibility into token spend, model usage trends, and cost tracking across all their tools in one place—particularly those who want a fast, cross-platform CLI alternative to web dashboards.

Actively developed and production-ready. v2.1.0 released with native Rust TUI, 2k+ GitHub stars, comprehensive CI/CD (GitHub Actions for native builds, coverage, publishing), extensive test coverage badge, and multi-language documentation (English, Korean, Japanese, Chinese). Last commits and releases are recent, indicating active maintenance.

Low risk for established use. Single maintainer (junhoyeo) and moderate dependency footprint (Tokio, Ratatui, Reqwest, SQLite via Rusqlite), but all are mature and well-maintained. The bundled SQLite (rusqlite with bundled feature) reduces platform-specific build issues. Main risk: the web dashboard and backend infrastructure (implicit from README mentions) are not fully visible in the file list, suggesting potential hidden complexity or external service dependencies.

Recent focus on v2 features: native Rust TUI with Ratatui (evidenced by multiple TUI screenshots in assets), cross-platform mouse selection support (MOUSE_SELECTION.md), expanded client support (24+ agents in asset names), and dashboard visualizations (3D contributions graph). CI workflows show active native binary builds for multiple platforms and npm publishing of CLI binaries.

git clone https://github.com/junhoyeo/tokscale.git
cd tokscale
cargo build --release
cargo run --bin tokscale-cli -- --help

Or install via npm: npm install -g tokscale (published to npmjs). Requires Rust 1.70+ and Cargo.

Daily commands: For CLI: cargo run --bin tokscale-cli -- <command> (see Clap derive on binary). For TUI dashboard: cargo run --bin tokscale-cli (no args launches interactive TUI mode). For web dashboard (if built): likely in a separate TypeScript workspace (suggested by .npmrc and bun.lock presence, though not detailed in provided file list).

• crates/tokscale-cli/src/main.rs — Entry point for the CLI application; orchestrates initialization, authentication, and TUI/command routing.
• crates/tokscale-core/src/lib.rs — Core library root exposing clients, parsers, aggregators, and pricing logic used by all CLI features.
• crates/tokscale-core/src/clients.rs — Defines traits and implementations for extracting token usage from multiple AI coding agents (Claude, Cursor, Gemini, etc.).
• crates/tokscale-cli/src/tui/mod.rs — TUI application state and event loop; core of the interactive dashboard visualization.
• crates/tokscale-core/src/parser.rs — Parses log and configuration files from various coding agents to extract token usage events.
• crates/tokscale-core/src/aggregator.rs — Aggregates parsed token events by time, client, model, and cost; computes statistics for visualization.
• Cargo.toml — Workspace configuration defining version, dependencies (rayon, simd-json, reqwest, ratatui), and member crates.

Add Support for a New AI Coding Agent

1. Define the client struct and implement the Client trait in crates/tokscale-core/src/clients.rs, adding methods to parse agent logs and extract token usage. (crates/tokscale-core/src/clients.rs)
2. Register the new client in the clients module's client detection logic so parser.rs can identify logs from the new agent. (crates/tokscale-core/src/parser.rs)
3. Add pricing data for the agent's models in crates/tokscale-core/src/pricing/ if needed. (crates/tokscale-core/src/pricing/aliases.rs)
4. Add the agent logo/icon asset to .github/assets/client-<name>.png for display in the UI. (.github/assets)

Add a New Dashboard Tab or Visualization

1. Create a new UI module under crates/tokscale-cli/src/tui/ui/, e.g., crates/tokscale-cli/src/tui/ui/new_view.rs with a render function. (crates/tokscale-cli/src/tui/ui/new_view.rs)
2. Register the new module in crates/tokscale-cli/src/tui/ui/mod.rs and add it to the enum of displayable screens. (crates/tokscale-cli/src/tui/ui/mod.rs)
3. Add event handling in crates/tokscale-cli/src/tui/app.rs to switch to the new screen on user input. (crates/tokscale-cli/src/tui/app.rs)
4. Update the footer help text in crates/tokscale-cli/src/tui/ui/footer.rs to indicate the new keybinding. (crates/tokscale-cli/src/tui/ui/footer.rs)

Add a New CLI Command

1. Create a new handler function in crates/tokscale-cli/src/commands/mod.rs or a new submodule under crates/tokscale-cli/src/commands/. (crates/tokscale-cli/src/commands/mod.rs)
2. Add the subcommand argument to the clap parser in crates/tokscale-cli/src/main.rs and route to the handler. (crates/tokscale-cli/src/main.rs)
3. Implement the command logic using core functionality from tokscale-core (parser, aggregator, etc.). (crates/tokscale-core/src/lib.rs)

• Rust + Cargo workspace — Type safety and performance-critical parsing/aggregation of token events across multiple agents; multi-crate structure separates core logic from CLI UI.
• Ratatui (TUI framework) — Cross-platform terminal UI with minimal dependencies; enables rich interactive dashboard without external GUI frameworks.
• SIMD-JSON + serde — Fast deserialization of log files from multiple AI agents; SIMD acceleration critical for parsing large token event streams.
• Rayon (data parallelism) — Parallel parsing of logs from multiple agents; speeds up initial scan and aggregation on multi-core systems.
• Reqwest (async HTTP) — Non-blocking API calls to leaderboard submission and authentication endpoints.
• Chrono — Timezone-aware date/time handling for accurate daily/hourly bucketing and wrapped-year summaries.

• Multi-crate workspace (tokscale-core + tokscale-cli) rather than single monolithic crate
  • Why: Allows core parsing/aggregation logic to be reused by web dashboard or other clients without pulling in TUI dependencies.
  • Consequence: Slightly more complex

1. SQLite bundling: rusqlite with bundled feature auto-compiles SQLite; build can be slow on first compile (one-time cost). 2. XDG paths: Config and cache stored via dirs crate using XDG_CONFIG_HOME on Unix, %APPDATA% on Windows—relative paths don't work, must use standard system locations. 3. Token parsing logic: Each agent (Claude, Cursor, OpenAI, etc.) has different log formats; adding support requires reverse-engineering client-specific JSON schema (documented in AGENTS.md but not in code comments). 4. Async shutdown: Tokio runtime requires clean shutdown signal handling (see signal-hook dependency)—terminating TUI mid-operation without proper cleanup can corrupt SQLite database. 5. No env vars documented: Configuration method not visible in file list; likely stored in config files at XDG_CONFIG_HOME/tokscale/ but not explicitly listed.

• Token-level billing and pricing models — Tokscale's core value is accurate cost tracking across models (GPT-4, Claude 3, Gemini) with different input/output token prices; understanding how LLM providers charge per-token is essential to add new models or fix pricing bugs
• SIMD JSON parsing — Tokscale uses simd-json over standard serde_json for parsing large log files from multiple agents; knowing SIMD acceleration is key to understanding performance characteristics and limitations
• Ratatui TUI framework and immediate-mode rendering — V2 uses Ratatui for the native terminal UI; contributors must understand stateful widget composition, event loops, and constraint-based layout to modify TUI features
• SQLite for cross-platform local persistence — Tokscale uses Rusqlite with bundled SQLite to store historical token/cost data locally without external database; understanding schema design and prepared statements is needed for data storage features
• Log file aggregation from heterogeneous sources — The core challenge: 25+ AI tools (Claude, Cursor, OpenAI, Kimi, etc.) all write logs in different formats; the parser architecture must be extensible; understanding walkdir + format detection pattern is key
• Async I/O with Tokio and multi-threaded parallelism (Rayon) — Tokscale uses Tokio for HTTP requests to APIs and file I/O, plus Rayon for parallel parsing of large log files; understanding when to use async vs multi-threaded is critical for performance tuning
• Cross-platform native binary distribution (GitHub Actions + npm) — Tokscale publishes pre-built binaries for Windows/macOS/Linux via GitHub Actions and npm; understanding the build matrix, stripping, and LTO is needed to fix platform-specific bugs or add new platforms

• charmbracelet/bubbletea — Go-based TUI framework; tokscale chose Ratatui (Rust equivalent) for similar composable widget-based design but with Rust performance
• oven-sh/bun — Present in bun.lock; likely used for frontend/web dashboard tooling (not visible in Rust crates); ecosystem companion for web layer
• openai/openai-python — Token counting reference; Tokscale reimplements OpenAI token math for pricing; useful for understanding cost calculation patterns across models
• anthropic/anthropic-sdk-python — Claude API reference; Tokscale parses Claude Code logs; understanding token limits and model pricing from official SDK helps with parser accuracy
• zed-industries/zed — Zed editor integration visible in assets (client-zed.webp); Tokscale may integrate with Zed's copilot features; understanding Zed's token tracking helps with compatibility

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for tokscale-cli auth module (crates/tokscale-cli/src/auth.rs)

The auth.rs module handles critical authentication logic but has no visible test coverage. Given the repo tracks CI coverage (.github/badges/coverage.svg) and has a test_coverage.yml workflow, adding unit tests for authentication flows (token validation, session management, error cases) would improve reliability and catch regressions early. This is a high-value security-adjacent module.

• [ ] Create crates/tokscale-cli/src/auth_tests.rs or add #[cfg(test)] mod tests to auth.rs
• [ ] Write tests for auth state initialization, token refresh, and failure scenarios
• [ ] Run cargo test --package tokscale-cli and verify coverage improvements
• [ ] Update test_coverage.yml if needed to ensure auth.rs coverage is tracked

Add integration tests for TUI data layer (crates/tokscale-cli/src/tui/data/mod.rs)

The TUI data module is responsible for loading and transforming token usage data from multiple sources. No test files exist for this critical path. Adding integration tests that mock data sources and verify the data transformation pipeline would prevent UI rendering bugs and ensure consistency across client types (OpenAI, Claude, Cursor, etc.).

• [ ] Create crates/tokscale-cli/tests/tui_data_integration_test.rs
• [ ] Mock database queries and API responses for multiple client types referenced in .github/assets/
• [ ] Test data aggregation, filtering, and statistics computation (daily, models views shown in tui-daily.png, tui-models.png)
• [ ] Add fixtures for sample token usage across different agents (OpenCode, Cursor, Gemini, etc.)

Add CLI snapshot/regression tests for wrapped command output (crates/tokscale-cli/src/commands/wrapped.rs)

The wrapped command generates year-end stats shown in hero-wrapped-2025.png assets and has custom rendering logic but no tests verifying output format or correctness. Using a snapshot testing library (e.g., insta crate), add tests to prevent accidental changes to the wrapped visualization that users rely on for sharing.

• [ ] Add insta = "1" to [dev-dependencies] in crates/tokscale-cli/Cargo.toml
• [ ] Create crates/tokscale-cli/tests/wrapped_snapshot_test.rs
• [ ] Write tests that generate wrapped output with mock data and snapshot the formatted results
• [ ] Test output for different user scenarios (zero usage, high usage, multi-client)
• [ ] Document snapshot review process in CONTRIBUTING.md for future PRs

• Add unit tests for token parser in crates/tokscale-core/src/parsers/ for a new agent (e.g., 'Hermes' or 'Kilocode' visible in asset names but parsing logic not in file list). Parser tests should validate edge cases like multi-turn conversations and token count mismatches.
• Expand AGENTS.md documentation with concrete JSON schema examples for 3-5 agents (currently only listing names in assets); include log file locations and parsing rules so contributors can add new agent support without reverse-engineering.
• Create crates/tokscale-cli/tests/integration_test.rs testing end-to-end CLI workflow: load a sample multi-agent log, aggregate costs, and verify TUI renders without panic. Coverage badge suggests some tests exist but integration suite appears incomplete.

The codebase demonstrates a reasonable security posture with well-maintained Rust dependencies and proper use of async/await patterns. However, there are opportunities for improvement: (1) Vendored native TLS and SQLite introduce update lag risks, (2) CI/CD lacks security scanning (cargo-audit), (3) Broad feature exposure increases attack surface, and (4) Dependency version management could be stricter. No hardcoded secrets were detected in the file structure. The application handles sensitive token data, making security auditing and dependency management particularly important. Recommended immediate actions: add cargo-audit to CI/CD, switch TLS backend to rustls if possible, and narrow dependency feature flags.

• Medium · Vendored Native TLS Dependencies — Cargo.toml - workspace.dependencies - reqwest. The reqwest dependency uses 'native-tls-vendored' feature which bundles OpenSSL. This can lead to security issues if the vendored OpenSSL version is not kept up-to-date with security patches. Vendored dependencies are harder to patch across the supply chain. Fix: Consider using 'rustls' as the TLS backend instead of 'native-tls-vendored'. If native-tls is required, implement automated dependency updates and security scanning (e.g., cargo-audit in CI/CD).
• Medium · SQLite Bundled Dependencies — Cargo.toml - workspace.dependencies - rusqlite. rusqlite uses the 'bundled' feature which vendors SQLite C code. This creates maintenance burden for security updates and potential issues if SQLite vulnerabilities are discovered. Fix: Regularly audit bundled SQLite versions. Consider using system SQLite if the target platform supports it. Implement automated CVE scanning for bundled C dependencies.
• Low · Incomplete Security Audit Coverage — .github/workflows/. No evidence of cargo-audit or security scanning in the CI/CD workflows. The repository has GitHub Actions workflows for build, test, and publish, but none appear to include security auditing steps. Fix: Add a security audit workflow that runs 'cargo audit' on every commit or pull request. Include SAST (Static Application Security Testing) tools in the CI/CD pipeline.
• Low · Broad Feature Exposure in ratatui — Cargo.toml - workspace.dependencies - ratatui. The ratatui dependency includes 'all-widgets' feature which enables all optional features. This increases the attack surface unnecessarily if not all widgets are used. Fix: Audit which ratatui widgets are actually used in the codebase and replace 'all-widgets' with specific feature flags (e.g., 'default', 'widget-*'). This reduces dependencies and potential vulnerabilities.
• Low · Permissive Dependency Version Ranges — Cargo.toml - workspace.dependencies. Most dependencies use version ranges (e.g., '1.0', '0.14') without upper bounds or tighter constraints. This allows automatic updates to potentially breaking versions that could introduce security issues. Fix: Use more restrictive version specifications (e.g., '=X.Y.Z' or '^X.Y.Z') for critical dependencies. Implement regular dependency update reviews in the development process.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.