tokdash 0.5.5

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

[!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

Run (from source)

pip install -e .

# Option A: run directly
python3 main.py

# Option B: CLI wrapper (same server)
./tokdash serve

Open: http://localhost:55423

If port conflicts:

• python3 main.py --port <port>
• ./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)

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 keeps no store of its own, so if a client deletes its old logs, that usage disappears from Tokdash too — a past month can 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 why Tokdash doesn't ship its own snapshot store, 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.