Show HN: Tokdash – a local dashboard for AI token and quota tracking

Notifications You must be signed in to change notification settings

Fork 5

Star 27

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

110 Commits

110 Commits

.github/workflows

.github/workflows

docs

docs

scripts

scripts

src/tokdash

src/tokdash

tests

tests

.gitignore

.gitignore

LICENSE

LICENSE

MANIFEST.in

MANIFEST.in

README.md

README.md

README_CN.md

README_CN.md

main.py

main.py

pyproject.toml

pyproject.toml

requirements-dev.txt

requirements-dev.txt

tokdash

tokdash

Repository files navigation

Table of Contents

Features

Supported clients

Quick start

Platform support

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 Statusline integration

Contribution calendar: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics

Session explorer: per-session drill-down

Quota tab [new]: subscription window bars with reset countdowns for Codex, Claude Code, and Antigravity. Codex windows work out of the box from local logs; Codex reset credits, metered features, and all Claude/Antigravity quota need opt-in live polling

Themes and app polish: 10 style themes, light/dark mode, and PWA install support

Overview

Sessions

Monthly usage heatmap

Yearly usage heatmap

Quota tracking

Codex quota and reset credits

Quick start

Platform support

Linux (including WSL2): supported

macOS: supported

Windows (native): experimental

Prerequisites

Python 3.10+

One or more supported clients installed

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:

tokdash setup --auto --json

To preview what setup would change:

tokdash setup --dry-run

Verify

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. For managed runtimes, update reports the Tokdash version before and after the upgrade; if the version is unchanged, it says Tokdash is already at that version instead of implying a new package was installed.

Existing installs: migration from before v1.0

If you installed Tokdash before the onboarding flow, upgrade first:

pipx upgrade tokdash

or: python3 -m pip install --user -U tokdash

Then run tokdash doctor and tokdash setup when you want Tokdash to manage the background service. If you already have a hand-written systemd or launchd service, setup does not silently replace it: it refuses unmarked tokdash.service / plist files by default. Keep managing that service yourself, remove it before setup, or run tokdash setup --force after checking tokdash setup --dry-run. --force also handles pre-1.0 services that already occupy port 55423 but do not expose the new /health fingerprint: it rewrites and restarts the existing tokdash.service. Use tokdash setup --no-service to skip service creation.

If your current setup uses a conda/system/user-pip interpreter and you want tokdash update to manage future upgrades, migrate the service to Tokdash's setup-owned venv:

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

This keeps your usage history under ~/.tokdash, rewrites the user service to run ~/.tokdash/runtime/python-venv/bin/python -m tokdash, and lets future tokdash update upgrade that managed venv and restart the service. If you installed with pipx, you can instead keep the pipx runtime and upgrade with tokdash update or pipx upgrade tokdash.

Remote access

Tokdash stays loopback-bound by default. For remote access, prefer:

interactive tokdash setup, which can offer an explicit Tailscale Serve step when available,

SSH forwarding: ssh -L 55423:127.0.0.1:55423 @.

Some Tailscale installs require operator permission before a non-root user can configure Serve. If Tailscale denies the Serve config, the interactive wizard can offer the one-time sudo tailscale set --operator=$USER step and then retry tailscale serve. Tokdash uses the /tokdash path on your tailnet host, so it does not claim the domain root if you already serve other tools there. After Serve succeeds, setup prints the exact https://...ts.net/tokdash URL to open from your tailnet.

Tailscale Serve is read-only for mutating dashboard/API actions because proxied requests fail Tokdash's loopback write gate. Use SSH forwarding when you need trusted remote writes.

Tailscale on Windows: the Windows Tailscale client installs both a GUI and a tailscale CLI, and tailscale serve works the same way from PowerShell/cmd once the client is running. Native Windows support has initial CI and smoke-test coverage, but the Tailscale Serve + native Windows combination has not yet been validated end to end against Tokdash, so treat that specific path as experimental until confirmed.

Binding Tokdash directly to 0.0.0.0 is possible but not recommended because the local API is not an internet-facing authenticated service.

Foreground fallback

If you only want a one-off foreground process:

tokdash serve

Open http://127.0.0.1:55423. Use tokdash serve --port if the default port is busy.

For full onboarding details, including runtime choices, WSL/systemd behavior, macOS launchd, Tailscale, bundling, update checks, and safe uninstall semantics, see docs/ONBOARDING.md.

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.

Ready-made templates live in docs/examples/statusline/ — copy one into ~/.claude/scripts/ and add the statusLine block to ~/.claude/settings.json:

statusline-minimal.sh → one line: [Claude Sonnet 4.6] 📁 myproject | 📊 12.3M ($4.56) today

statusline-full.sh → a four-row dashboard with today + week totals and a top-3 per-tool breakdown

statusline.ps1 → the same one-line output as the minimal template, for Claude Code running natively on Windows (PowerShell, no curl/jq needed)

All are read-only, localhost-only, and fail silently if Tokdash isn't running. See the folder README for install/config and docs/API.md for the endpoint reference.

Prefer to roll your own? Hand your agent this prompt and point it at docs/API.md:

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

Configuration

Tokdash is localhost-only by default.

TOKDASH_HOST (default: 127.0.0.1)

TOKDASH_PORT (default: 55423)

TOKDASH_CACHE_TTL (default: 600 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

Remote access through Tailscale Serve:

tokdash setup

When the wizard offers Tailscale Serve, confirm it.

Setup prints the exact https://...ts.net/tokdash URL after Serve succeeds.

If you manage Tailscale yourself after setup has started Tokdash on the default port:

tailscale serve --bg --https=443 --set-path=/tokdash http://127.0.0.1:55423

Open https://..ts.net/tokdash. Stop that manual Serve rule with tailscale serve --https=443 --set-path=/tokdash off. tokdash uninstall only reverts Tailscale Serve rules that the setup wizard created and recorded. Tailscale Serve remains read-only for mutating dashboard/API actions; use SSH forwarding when you need trusted remote writes.

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).

Optional quota polling: the Quota tab is local-only by default. Per-provider API polling can be enabled from the tab or with tokdash quota consent; it uses your local CLI credentials only to call that provider's own quota endpoint, and stores responses in the local usage SQLite DB.

Server exposure: Tokdash binds to 127.0.0.1 by default. Prefer Tailscale Serve or SSH tunneling for rem

[truncated for AI cost control]