All releases

v0.0.1 - Initial Release

v0.0.1 View on GitHub ->

Initial release of tokenuse, a local-only Rust TUI for exploring AI coding tool token and cost usage. The package and the installed command are both tokenuse.

Highlights

  • Read session files already on disk and render a dense terminal dashboard for spend by day, project, tool, model, shell command, and MCP server.
  • Durable local usage archive at <config dir>/tokenuse/archive.db; startup loads archived history immediately, then syncs local tool sources only to append newly discovered records.
  • Background refresher syncs the archive every 15 minutes and on the r key; the status bar shows reloading… while it runs and flips to reloaded · N calls when it finishes.
  • No API keys, no proxy, no telemetry. The default build has zero network dependencies.
  • Falls back to bundled sample data when no local sessions are found, with the status surfaced in the title bar.
  • Exports default to the user's Downloads folder, show the active destination before writing, and include a session-only folder picker.
  • The Deep Dive page uses a denser content-sized grid, removes the duplicate status summary strip, and gives detail-heavy panels more useful space.

Supported Tools

  • Claude Code: ~/.claude/projects/ and Claude Desktop local agent sessions, with exact token and cache usage, tool calls, Bash commands, and MCP tools.
  • Cursor: Cursor state.vscdb, with exact tokens when present and chars / 4 estimates for Agent KV and zero-token rows.
  • Codex: ~/.codex/sessions/**/rollout-*.jsonl, with per-turn token_count events, cached input, reasoning output, and tool calls.
  • GitHub Copilot: ~/.copilot/session-state/ and VS Code Copilot Chat transcripts, with legacy output tokens when present and estimated transcript usage.

Project names are normalised across tools: paths are folded to the nearest existing Git root and rendered with the shortest unique suffix.

Pages And Modals

  • Dashboard: summary totals, daily activity, project and project/tool spend, top sessions, models, core tools, shell commands, and MCP servers. The Deep Dive tab keeps compact panels compact while giving project, model, command, and MCP detail tables more useful room.
  • Usage: per-tool 24-hour activity histogram and plan-side rate limit windows.
  • Session drill-down: per-call timestamp, model, cost, in/out tokens, cache, tools used, and a single-line prompt snippet.
  • Configuration: currency override and local data refresh actions for currency rates and LiteLLM pricing.
  • Help, project picker, currency picker, session picker, export picker: searchable modals reachable from any page.

Pricing And Currency

  • Pricing is computed from an embedded LiteLLM-derived snapshot. A locally downloaded pricing-snapshot.json in the tokenuse config directory takes precedence.
  • Refresh the embedded snapshot with cargo run --features refresh-prices -- --refresh-prices.
  • Currency display defaults to USD; aggregation always stores cost_usd and formats values through the active rate table.
  • The embedded currency/rates.json snapshot is generated from Frankfurter and refreshed nightly by refresh-currency.yml. Regenerate manually with cargo run --features refresh-currency -- --generate-currency-json.

Export

Press e on the Dashboard to export the current filtered view (period, tool, project) to JSON, CSV, SVG, or PNG. Output defaults to the user's Downloads folder with timestamped, slugged filenames so prior runs are never overwritten. If a platform Downloads directory is unavailable, tokenuse falls back to ~/Downloads and then <config dir>/tokenuse/exports/.

The export picker shows the active destination folder before writing. Press f or b in the export picker to open a terminal folder picker and choose a different destination for the current session. The folder picker is directory-only and session-only: choosing Use this folder updates the running dashboard, but does not write a setting to config.json.

Install

macOS and Linux users can install with Homebrew:

brew install russmckendrick/tap/tokenuse

Pre-built binaries are published for Linux, macOS, and Windows from GitHub Releases. The installed executable is tokenuse.

CLI

  • tokenuse launches the interactive dashboard.
  • tokenuse --list-projects syncs the archive, prints the project inventory, and exits.
  • tokenuse --version and tokenuse --help print the build version and the flag reference.
  • tokenuse --refresh-prices and tokenuse --generate-currency-json are gated behind the refresh-prices and refresh-currency Cargo features and only run on builds that opt into network access.

Notes

  • This is the first public release; the dashboard layout, configuration surface, and adapter behaviour may still evolve before a stable 1.0.
  • Tool ingestion is read-only and runs entirely against local files. Imported history is retained in tokenuse's archive even if the original tool history is later removed.
  • There is no live file watcher; the 15-minute background refresher and the r key are the only auto-refresh signals.
  • Historical costs are stored as import-time USD values. Pricing snapshot refreshes apply to newly imported calls, not already archived rows.
  • A terminal at least 120x40 is recommended; smaller terminals show a resize notice in place of the full dashboard.

Full Changelog: https://github.com/russmckendrick/tokenuse/commits/v0.0.1

Full Changelog: https://github.com/russmckendrick/tokenuse/commits/v0.0.1