tokdash 0.6.0

Local token & cost dashboard for AI coding tools

English  |  中文

Local token & cost dashboard for AI coding tools

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

v0.6.0: about 30× faster than pre-0.6.0 cold usage scans, and 15× faster than ccusage in the same local benchmark.

[!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 — a one-line config change per client prevents it (History retention).

Table of Contents

• Live demo
• Features
• Supported clients
• Platform support
• Quick start
• Configuration
• Privacy & security
• API (local)
• Cost Accuracy Note
• History retention
• Roadmap
• Contributing / security
• Project structure
• License

Features

• Exact token counts: Input/Output/Cache token breakdowns
• Statusline integration [new]: drop a live token-usage indicator into Claude Code's statusline (or any agent that can hit a local HTTP endpoint) — see Quick start
• Custom date ranges: Flatpickr date picker + quick range buttons (Today, Last 7 Days, This Month, etc.)
• Contribution calendar: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
• Session explorer: per-session drill-down for Codex, Claude Code, and OpenCode
• 10 style themes: Elevated, Classic, Vibrant, Midnight, Paper, Liquid, Terminal, Brutalist, Arcade, Studio
• Light & dark mode: auto-detects system preference, manual toggle
• PWA support: installable as a progressive web app

Live demo

A static demo of the current dashboard is hosted at tokdash.github.io/demo — no install required. (The project home page is tokdash.github.io.)

The demo runs the unmodified Tokdash frontend against an in-browser shim that returns deterministic, fully synthetic data. You can:

• switch between Overview / Sessions / Stats / Pricing tabs,
• pick any date range (or the Today / 7-day / 30-day shortcuts),
• toggle light/dark and all 10 style themes,
• drill into a synthetic Codex / Claude Code / OpenCode session,
• browse the read-only pricing database.

Source for the demo lives at tokdash/tokdash.github.io. Nothing is uploaded; nothing is read from your machine.

Platform support

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

Quick start

Prerequisites

• Python 3.10+
• One or more supported clients installed

Install (pip)

pip install tokdash
tokdash serve

Open: http://localhost:55423

If port conflicts:

• tokdash serve --port <port>

If you want to access Tokdash from another device (recommended):

• Tailscale Serve (private to your tailnet): tailscale serve 55423
• SSH port-forward: ssh -L 55423:127.0.0.1:55423 <user>@<host>

Binding to 0.0.0.0 is possible, but not recommended: it listens on all interfaces and can expose the dashboard beyond your LAN (VPN/Wi-Fi/etc.). Only do this if you understand the risk and have firewall/auth in place.

Run in background

See docs/agents/systemd/BACKGROUND_RUN.md for:

• Linux systemd (user service) template
• macOS launchd (LaunchAgent) template
• Optional /health watchdog that auto-restarts a wedged service

For Humans

Copy and paste this prompt to your LLM agent (Claude Code, AmpCode, Cursor, etc.):

Install and configure Tokdash to run in the background by following the instructions here:
https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/systemd/AGENTS.md

Or read the Background Run guide, but seriously, let an agent do it.

For LLM Agents

Fetch the installation guide and follow it:

curl -s https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/systemd/AGENTS.md

Updating Tokdash

If you installed Tokdash with pip and are running it via systemd:

# 1. Upgrade the package
pip install --upgrade tokdash

# 2. Restart the systemd service to pick up changes
systemctl --user daemon-reload
systemctl --user restart tokdash

# 3. Verify the new version
pip show tokdash | grep Version
systemctl --user status tokdash --no-pager

# 4. Test the API is responding
curl 'http://127.0.0.1:55423/api/usage?period=today'

View logs if needed:

journalctl --user -u tokdash -f

OpenClaw digest (scheduled reports)

Tokdash can power daily/weekly/monthly OpenClaw usage reports by querying the local API on a schedule.

For Humans

Copy and paste this prompt to your LLM agent (Claude Code, AmpCode, Cursor, etc.):

Install and configure scheduled Tokdash usage reports for OpenClaw by following the instructions here:
https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/openclaw_reporting/AGENTS.md

Or read the guide yourself, but seriously, let an agent do it.

For LLM Agents

Fetch the installation guide and follow it:

curl -s https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/openclaw_reporting/AGENTS.md

Statusline integration

The local API can power a statusline item in your coding agent (Claude Code, etc.) showing live token/cost stats. Hand your agent this prompt:

"I would like to add a statusline item from the tokdash endpoint's API; it should show the total tokens used today."

Point it at docs/API.md for endpoint details and let it wire the rest.

Configuration

Tokdash is localhost-only by default.

• TOKDASH_HOST (default: 127.0.0.1)
• TOKDASH_PORT (default: 55423)
• TOKDASH_CACHE_TTL (default: 120 seconds)
• TOKDASH_COMPUTE_CONCURRENCY (default: 2) — cap on simultaneous heavy history reparses; excess cold requests return a fast 503 instead of saturating the server under load
• TOKDASH_LIMIT_CONCURRENCY (default: 64) — uvicorn connection cap (backpressure)
• TOKDASH_KEEPALIVE (default: 5 seconds) — uvicorn keep-alive timeout
• TOKDASH_ALLOW_ORIGINS (comma-separated, default: empty)
• TOKDASH_ALLOW_ORIGIN_REGEX (default allows only localhost/127.0.0.1)
• TOKDASH_NO_RETENTION_NOTICE (set to 1 to silence the history-retention reminder printed on tokdash serve)

Persistent usage DB (default on):

Tokdash maintains a local SQLite index at ~/.tokdash/usage.sqlite3 by default. It stores parsed token rows and Codex/Claude session summaries so repeated dashboard and API reads can use indexed SQL instead of reparsing every source log. Source logs remain the source of truth; the DB is a local performance index, and Tokdash falls back to live parsing if it is disabled or unavailable.

• TOKDASH_USAGE_DB (default: 1) — set to 0, false, no, or off to disable the persistent usage DB
• TOKDASH_DATA_DIR (default: ~/.tokdash) — base directory for Tokdash local state
• TOKDASH_USAGE_DB_PATH (default: $TOKDASH_DATA_DIR/usage.sqlite3) — explicit SQLite file path
• TOKDASH_USAGE_DB_DURABLE (default: 1) — keep already indexed rows if a source file temporarily disappears or a parser returns no rows; set to 0 for strict source replacement
• TOKDASH_USAGE_DB_WATCH (default: 0) — set to 1 to run a background sync loop inside tokdash serve
• TOKDASH_USAGE_DB_WATCH_INTERVAL (default: 30 seconds) — sync interval for tokdash db watch and the serve-time watch loop

DB maintenance commands:

tokdash db status --pretty
tokdash db sync --pretty
tokdash db verify --verify-period today --pretty
tokdash db repair --dry-run --pretty
tokdash db resync --pretty
tokdash db watch --pretty

Example (remote access via Tailscale Serve; recommended):

tokdash serve --bind 127.0.0.1 --port 55423
tailscale serve --bg 55423

By default tokdash serve opens the dashboard in your browser once on startup. Pass --no-open to disable this (it is also skipped automatically in headless/SSH environments and in the background service templates).

Privacy & security

• No telemetry: Tokdash does not intentionally send your data anywhere.
• Local parsing: usage is computed from local session files (see supported clients).
• Server exposure: Tokdash binds to 127.0.0.1 by default. Prefer Tailscale Serve or SSH tunneling for remote access; avoid --bind 0.0.0.0 unless you understand it listens on all interfaces and have firewall/auth in place.

API (local)

Tokdash is a local HTTP server. Common endpoints:

• GET /api/usage?period=today|week|month|N
• GET /api/usage?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
• GET /api/tools?period=... (coding tools only)
• GET /api/openclaw?period=... (OpenClaw only)
• GET /api/sessions?tool=codex|claude|opencode&period=...
• GET /api/stats (contribution calendar & statistics)

Example:

curl 'http://127.0.0.1:55423/api/usage?period=today'

Full API reference: docs/API.md — schema, parameters, and response shapes for every endpoint.

Cost Accuracy Note

Token counts depend on what each client logs locally. Costs are computed from src/tokdash/pricing_db.json and may lag real provider pricing — use as an estimate and verify against your billing source if it matters.

History retention

Tokdash reads each client's local session logs and also keeps a local SQLite performance index. The index can keep rows Tokdash has already seen, but it cannot recover logs that were deleted before they were indexed, and it is not a replacement for keeping the original client history. If a client deletes old logs before Tokdash syncs them, a past month can still read lower than when you first recorded it. Only two supported clients do this by default, and both are a one-line fix:

• Claude Code deletes sessions older than cleanupPeriodDays (default 30 days) at startup. Add this to your existing ~/.claude/settings.json (and any alternate CLAUDE_CONFIG_DIR):

  { "cleanupPeriodDays": 3650 }
  

• Gemini CLI deletes sessions older than 30 days. Disable it in ~/.gemini/settings.json; if a project has .gemini/settings.json, make the same change there because workspace settings override user settings:

  { "general": { "sessionRetention": { "enabled": false } } }
  

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/HISTORY_RETENTION.md.

Roadmap

See docs/ROADMAP.md.

Contributing / security

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

Project structure

tokdash/
├── main.py                 # Source entrypoint (python3 main.py)
├── tokdash                 # Source CLI wrapper (./tokdash serve)
├── src/
│   └── tokdash/
│       ├── cli.py
│       ├── api.py                # FastAPI routes/app
│       ├── compute.py            # Aggregation/merging logic
│       ├── dateutil.py           # Shared date-range parsing
│       ├── sessions.py           # Session explorer logic
│       ├── pricing.py            # PricingDatabase wrapper
│       ├── assets.py             # Static asset management
│       ├── model_normalization.py
│       ├── pricing_db.json
│       ├── sources/
│       │   ├── openclaw.py       # OpenClaw session log parser
│       │   └── coding_tools.py   # Local coding tools parsers
│       └── static/
│           ├── index.html        # Single-page dashboard
│           ├── theme-config.js   # Theme palettes & heatmap colors
│           └── themes.css        # Per-theme CSS overrides
└── docs/                   # Roadmap + background-run docs + agent prompts

License

MIT License - see LICENSE.