Tokdash

English  |  中文  |  日本語  |  한국어  |  Español  |  Português

Local token & cost dashboard for AI coding tools

Try it without installing → tokdash.github.io/demo

[!NOTE]
Multiple machines, one dashboard. Add the Tokdash instances running on WSL, a Mac, or any other box in Settings: every view combines whatever you select, the Servers tab compares the machines side by side, and the Quota tab keeps each provider's window bars and reset countdowns grouped per machine. Remote access → · quota tracking →

Also from the same author: Cosyncing. Synchronize and control your agents — from CLI to GUI, from desktop to phone. Cosyncing keeps your coding agents in sync across your own network.

Table of Contents

• Quick start
• One package, four views
  • WebUI
  • Terminal dashboard (TUI)
  • Companion status bar app
  • Statusline
• Install & run
• Features
• Quota tracking (optional)
• Cost accuracy note
• History retention
• Roadmap
• Contributing / security
• Documentation
• License

Quick start

pipx install tokdash
tokdash setup

That's it. tokdash setup detects the runtime, installs a managed one if
needed, registers a local service, and prints the dashboard URL —
http://127.0.0.1:55423. Full options, first-run notes, and updates live in
Install & run; prefer to look around first? The
live demo runs on the real UI.

One package, four views

One local package, one local data index — and four ways to read it. Every surface
parses the same session logs on your own machine, so the browser dashboard, the
terminal, the menu bar, and your agent's statusline always agree.

WebUI

The dashboard is a single page served by the local FastAPI app: exact input /
cache / output token breakdowns, per-tool and per-model tables, a contribution
heatmap, a week/month/year Report, per-provider Quota windows with reset
countdowns, and a Servers tab that combines and compares several machines.
Click any screenshot to open the live demo.

Overview	Usage Report
Quota tracking	Multiple servers, one total

_{Light and dark follow your OS appearance. The app ships 17 style themes, light/dark modes, PWA install, and six UI languages (English / 中文 / 日本語 / 한국어 / Español / Português).}

Terminal dashboard (TUI)

Prefer to stay in the terminal? tokdash tui opens the Overview, Report,
and Quota tabs without a browser, reading the same local index (and the
shared on-disk database when a tokdash serve is running beside it).

TUI — Overview

TUI — Quota

tokdash tui

tokdash report --period week

Companion status bar app

An optional native menu-bar app for macOS and notification-area app for Windows:
a compact, read-only view of the Tokdash service without the dashboard open.

macOS menu bar	Windows notification area

Windows — Microsoft Store (recommended, signed by Microsoft, requires Windows 11):

Direct download — the latest companion release:
a universal DMG (arm64 + x86_64, macOS 14+) and a self-contained portable ZIP
(x64, Windows 11; Windows on Arm via x64 emulation).

Statusline

The local API can power a statusline item in your coding agent showing live
token/cost stats:

Ready-made templates (bash and PowerShell), install/config, and the endpoint
reference live in docs/guides/statusline/.

Install & run

Platform support

• Linux (including WSL2): supported
• macOS: supported
• Windows (native): experimental

Prerequisites: Python 3.10+ and one or more
supported clients.

Install

Recommended isolated install:

pipx install tokdash

If you do not use pipx:

python3 -m pip install --user tokdash

First run

Run the onboarding wizard:

tokdash setup

The wizard configures a reversible user-level background service when the platform supports
one, then prints the dashboard URL (default: http://127.0.0.1:55423). If no supported
service manager is available, it records setup state and prints foreground run guidance. It
uses localhost-first defaults, does not require sudo for the local service, and keeps your
usage history unless you later uninstall with --purge.

For a non-interactive setup from an agent, script, or bundle, run
tokdash setup --auto --json; to preview what setup would change, tokdash setup --dry-run.
To expose the dashboard explicitly on all network interfaces with writes disabled, run
tokdash setup --bind 0.0.0.0; review the remote-access guide first.

Then check the install:

tokdash doctor

doctor checks the runtime, background service, configured port, data paths, and update-check
status. Use tokdash doctor --json for automation.

Update or remove

tokdash update       # upgrade the managed runtime and restart the service when possible
tokdash uninstall    # reverse exactly what setup created; keeps usage history by default

update only drives install methods Tokdash can safely manage. If your runtime was installed
by a package manager Tokdash does not own, it prints the exact manual guidance instead of
mutating that environment.

pipx upgrade tokdash
# or: python3 -m pip install --user -U tokdash

# Upgrade the tokdash command you are about to run, for example:
python3 -m pip install --user -U tokdash
# or, for a conda base install:
conda run -n base python -m pip install -U tokdash
tokdash setup --runtime venv --force
tokdash doctor

Foreground fallback

If you only want a one-off foreground process:

tokdash serve

Open http://127.0.0.1:55423. Use tokdash serve --port <port> if the default port is busy.
By default tokdash serve opens the dashboard in your browser once on startup; pass
--no-open to disable it. A bare tokdash with no command just prints the command help
and exits — it no longer starts tokdash serve behind your back.

For full onboarding details — runtime choices, WSL/systemd behavior, macOS launchd,
Tailscale, bundling, update checks, and safe uninstall semantics — see
docs/guides/ONBOARDING.md. For remote access through
Tailscale Serve, SSH forwarding, or an explicit network bind, see
docs/guides/REMOTE_ACCESS.md.

Features

• Exact token counts: Input/Output/Cache token breakdowns
• Session explorer: per-session drill-down
• Contribution calendar: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
• Report tab: a week / month / year-to-date report of your own agent activity, with a shareable card for each tier of detail. Every export writes a light and a dark PNG
• Quota tab: subscription window bars with reset countdowns for nine providers. Codex windows work out of the box from local logs; most other sources need opt-in live polling
• Terminal dashboard [new]: tokdash tui — Overview, Report and Quota in the terminal, no browser required
• Companion status bar app: spend and subscription quota from the macOS menu bar or Windows notification area — on the Microsoft Store for Windows
• Statusline integration: a live token-usage indicator inside Claude Code's statusline (or any agent that can hit a local HTTP endpoint)
• Multi-server views: add WSL, macOS, and other Tokdash servers in Settings; combine usage across any selection while keeping quota grouped by machine. See remote access.
• Themes and app polish: 17 style themes, light/dark mode, PWA install support, UI in six languages

Supported clients

Tokdash reads the local session logs of 27 supported agents — the pill row
above names them; the full matrix (usage & cost / Session Explorer coverage,
per-client data paths, overrides, and source-specific accounting notes) is in
Supported clients.

Quota tracking (optional)

The Quota tab shows subscription utilization windows and reset countdowns for
nine providers. Codex's 5-hour/weekly windows work out of the box from local
logs (treat them as an estimate); accurate Codex consumption and every other
provider — Claude Code, Antigravity, MiniMax, Kimi Code, Grok, Z.ai, OpenCode
Go, Command Code — come from opt-in live polling: Tokdash calls each
provider's own quota endpoint with the sign-in your CLI already has. Off by
default, per-provider consent, results kept in the local database.

The consent commands, master switch, poll cadence, and per-provider credential
notes are in docs/reference/QUOTA.md.

Cost Accuracy Note

Token counts depend on what each client logs locally. Costs are computed from the bundled pricing database (src/tokdash/pricing_db.json) by default, or from your saved dashboard pricing override at <data_dir>/pricing_db.json when present. Either way they may lag real provider pricing — use as an estimate and verify against your billing source if it matters.

History retention

[!IMPORTANT]
Keep your history. Claude Code and Gemini CLI delete local sessions older than ~30 days by default, so Tokdash's earlier months can silently shrink.

Tokdash reads each client's local session logs; the local SQLite index cannot
recover logs deleted before they were indexed. Only two supported clients delete
old sessions by default, and both are a one-line fix:

• Claude Code: add { "cleanupPeriodDays": 3650 } to ~/.claude/settings.json (and any alternate CLAUDE_CONFIG_DIR).
• Gemini CLI: set { "general": { "sessionRetention": { "enabled": false } } } in ~/.gemini/settings.json (workspace settings override user settings).

Every other supported client keeps history indefinitely by default. For the full
per-client survey, fix details, and what the local SQLite index does and does not
preserve, see docs/reference/HISTORY_RETENTION.md.

Roadmap

See docs/development/ROADMAP.md.

Contributing / security

• Contributing guide: docs/CONTRIBUTING.md
• Security policy: docs/SECURITY.md

Documentation

Full documentation lives in docs/ (start at the index), grouped into:

• guides/ — task-oriented setup: onboarding, remote access, statusline, background service.
• reference/ — lookup material: API reference, configuration, quota internals, supported clients, history retention.
• development/ — changelog, releasing, roadmap, and public technical-notes/.

License

MIT License - see LICENSE.