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

Tokdash, a local dashboard for tracking AI token usage and costs across coding tools like Claude Code and Gemini CLI, launched with performance improvements of up to 30x over previous versions. The open-source tool provides exact token counts, session exploration, quota tracking, and privacy-focused local data storage.

Local token & cost dashboard for AI coding tools Try it without installing → tokdash.github.io/demo Performance: 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 history-retention . Features features Supported clients /JingbiaoMei/Tokdash/blob/main/docs/SUPPORTED CLIENTS.md Quick start quick-start Configuration configuration Privacy & security privacy--security API local api-local Cost Accuracy Note cost-accuracy-note History retention history-retention Roadmap roadmap Contributing / security contributing--security Project structure project-structure License license 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 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 quota-tracking-optional Themes and app polish : 10 style themes, light/dark mode, and PWA install support Linux including WSL2 : supported macOS: supported Windows native : experimental - Python 3.10+ - One or more supported clients /JingbiaoMei/Tokdash/blob/main/docs/SUPPORTED CLIENTS.md installed Recommended isolated install: pipx install tokdash If you do not use pipx: python3 -m pip install --user tokdash 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 tokdash doctor doctor checks the runtime, background service, configured port, data paths, and update-check status. Use tokdash doctor --json for automation. 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 . 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 <user @<host . 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. 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. For full onboarding details, including runtime choices, WSL/systemd behavior, macOS launchd, Tailscale, bundling, update checks, and safe uninstall semantics, see . docs/ONBOARDING.md Tokdash can power daily/weekly/monthly OpenClaw usage reports by querying the local API on a schedule. 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. Fetch the installation guide and follow it: curl -s https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/openclaw reporting/AGENTS.md 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/ /JingbiaoMei/Tokdash/blob/main/docs/examples/statusline — copy one into ~/.claude/scripts/ and add the statusLine block to ~/.claude/settings.json :→ one line: statusline-minimal.sh Claude Sonnet 4.6 📁 myproject | 📊 12.3M $4.56 today → a four-row dashboard with today + week totals and a top-3 per-tool breakdown statusline-full.sh → the same one-line output as the minimal template, for Claude Code running natively on Windows PowerShell, no statusline.ps1 curl / jq needed All are read-only, localhost-only, and fail silently if Tokdash isn't running. See the folder README /JingbiaoMei/Tokdash/blob/main/docs/examples/statusline/README.md for install/config and docs/API.md /JingbiaoMei/Tokdash/blob/main/docs/API.md for the endpoint reference. Prefer to roll your own? Hand your agent this prompt and point it at docs/API.md /JingbiaoMei/Tokdash/blob/main/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." 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://<machine .<tailnet .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 . No telemetry : Tokdash does not intentionally send your data anywhere. Local parsing : usage is computed from local session files see supported clients /JingbiaoMei/Tokdash/blob/main/docs/SUPPORTED CLIENTS.md . 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 remote access; avoid --bind 0.0.0.0 unless you understand it listens on all interfaces and have firewall/auth in place. Tailscale Serve is read-only for write endpoints by design because proxied requests fail Tokdash's loopback write gate; use SSH forwarding when you need authenticated remote writes. The Quota tab shows subscription utilization windows and reset timers, from two data sources. Local logs no network : Codex records its own quota in session files, so the Codex 5-hour/weekly windows work out of the box — but they update only when you use Codex, and the logs never contain reset credits or metered-feature windows. Live polling off by default, per-provider consent : Tokdash calls the provider's own quota endpoint with the sign-in your CLI already has — fresher, adds Codex reset credits and metered features, and is the only source for Claude Code and Antigravity quota: tokdash quota consent --codex-api on --claude-api on --antigravity-api on tokdash quota consent --poll-interval 30 background poll cadence: 15, 30, 60 or 120 min tokdash quota consent --enabled off master switch: turn ALL quota tracking off tokdash quota poll tokdash quota show Master switch. quota.enabled default on turns all quota work on or off — session scanning, network polling, and snapshot writes. Toggle it from the Quota tab or with tokdash quota consent --enabled on|off . When it is off or the TOKDASH QUOTA POLL=0 kill switch is set , the background poller idles completely, POST /api/quota/refresh returns a "quota tracking disabled" error, and the tab shows an enable quota tracking card instead of data. Per-provider consent keys keep their narrower network-only meaning. Poll interval. The background poller snapshots every 30 minutes by default. Choose 15/30/60/120 minutes from the Quota tab, during tokdash setup , or with tokdash quota consent --poll-interval N ; it is saved as quota.poll interval minutes in config.json . The TOKDASH QUOTA POLL INTERVAL env var seconds, floor 300 overrides the saved value, and the tab shows which source is active. Interval changes apply on the next poll cycle without restarting the server. Codex session ingestion is incremental — after a one-time backfill of your history, each cycle only tail-reads session files that grew, so a steady-state poll costs single-digit milliseconds. When enabled, Tokdash reads credentials from $CODEX HOME/auth.json , Claude's CLAUDE CODE OAUTH TOKEN override or $CLAUDE CONFIG DIR/.credentials.json , and ~/.gemini/antigravity-cli/antigravity-oauth-token , then calls only the corresponding provider quota endpoints. On macOS, Claude Code stores its credentials in the Keychain rather than .credentials.json ; if neither the env var nor .credentials.json exists, Tokdash reads the Keychain item Claude Code-credentials directly — read-only, and the first read may show a one-time Keychain permission prompt. If the Keychain is unavailable locked, denied, headless session , set CLAUDE CODE OAUTH TOKEN create one with claude setup-token as an override. Tokdash never refreshes or writes provider credentials. TOKDASH QUOTA POLL=0 is a hard kill switch for all quota tracking. tokdash export excludes quota data by default; use --include-quota only when you intentionally want it in the JSON. tokdash setup offers an optional quota step per-provider network consent, default No, plus the poll interval , and tokdash doctor reports the quota state: master switch, per-provider consent, kill switch, effective interval and its source, last poll time, and the stored snapshot count. Quota snapshots and their history live in the local usage database usage.sqlite3 , enabled by default and are kept indefinitely by default — set TOKDASH QUOTA RETENTION DAYS to a positive number of days to prune older snapshots. If you opt out of local persistence with TOKDASH USAGE DB=0 , the Quota tab loses its main data path: no snapshot history is kept, the background poller does not run, and the tab only shows in-memory results from a manual Refresh network providers with consent for the lifetime of the current server process. Keep the usage DB enabled the default for normal quota tracking. 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|pi agent&period=... append &include review sessions=true to include Codex review/permission sessions, hidden by default GET /api/quota and GET /api/quota/history subscription quota snapshots; network refresh is write-gated and opt-in GET /api/stats contribution calendar & statistics Example: curl 'http://127.0.0.1:55423/api/usage?period=today' Full API reference: docs/API.md /JingbiaoMei/Tokdash/blob/main/docs/API.md — schema, parameters, and response shapes for every endpoint. 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 the Pricing tab writes there and it fully replaces the bundled rates . Either way they may lag real provider pricing — use as an estimate and verify against your billing source if it matters. 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 . See docs/ROADMAP.md . - Contributing guide: docs/CONTRIBUTING.md - Security policy: docs/SECURITY.md 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/ Onboarding guide, API docs, release notes, and agent prompts MIT License - see LICENSE .