{"slug": "show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking", "title": "Show HN: Tokdash – a local dashboard for AI token and quota tracking", "summary": "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.", "body_md": "**Local token & cost dashboard for AI coding tools**\n\n**Try it without installing → tokdash.github.io/demo**\n\n**Performance: about 30× faster than pre-0.6.0 cold usage scans, and 15× faster than ccusage in the same local benchmark.**\n\nImportant\n\n**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)).\n\n[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)\n\n**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\n\n**Linux (including WSL2):** supported**macOS:** supported**Windows (native):** experimental\n\n- Python\n**3.10+** - One or more\n[supported clients](/JingbiaoMei/Tokdash/blob/main/docs/SUPPORTED_CLIENTS.md)installed\n\nRecommended isolated install:\n\n```\npipx install tokdash\n```\n\nIf you do not use pipx:\n\n```\npython3 -m pip install --user tokdash\n```\n\nRun the onboarding wizard:\n\n```\ntokdash setup\n```\n\nThe wizard configures a reversible user-level background service when the platform supports\none, then prints the dashboard URL (default: `http://127.0.0.1:55423`\n\n). If no supported\nservice manager is available, it records setup state and prints foreground run guidance. It\nuses localhost-first defaults, does not require `sudo`\n\nfor the local service, and keeps your\nusage history unless you later uninstall with `--purge`\n\n.\n\nFor a non-interactive setup from an agent, script, or bundle:\n\n```\ntokdash setup --auto --json\n```\n\nTo preview what setup would change:\n\n```\ntokdash setup --dry-run\ntokdash doctor\n```\n\n`doctor`\n\nchecks the runtime, background service, configured port, data paths, and update-check\nstatus. Use `tokdash doctor --json`\n\nfor automation.\n\n```\ntokdash update       # upgrade the managed runtime and restart the service when possible\ntokdash uninstall    # reverse exactly what setup created; keeps usage history by default\n```\n\n`update`\n\nonly drives install methods Tokdash can safely manage. If your runtime was installed\nby a package manager Tokdash does not own, it prints the exact manual guidance instead of\nmutating that environment. For managed runtimes, `update`\n\nreports the Tokdash version before\nand after the upgrade; if the version is unchanged, it says Tokdash is already at that version\ninstead of implying a new package was installed.\n\n## Existing installs: migration from before v1.0\n\nIf you installed Tokdash before the onboarding flow, upgrade first:\n\n```\npipx upgrade tokdash\n# or: python3 -m pip install --user -U tokdash\n```\n\nThen run `tokdash doctor`\n\nand `tokdash setup`\n\nwhen you want Tokdash to manage the background\nservice. If you already have a hand-written systemd or launchd service, setup does **not**\nsilently replace it: it refuses unmarked `tokdash.service`\n\n/ plist files by default. Keep\nmanaging that service yourself, remove it before setup, or run `tokdash setup --force`\n\nafter\nchecking `tokdash setup --dry-run`\n\n. `--force`\n\nalso handles pre-1.0 services that already\noccupy port `55423`\n\nbut do not expose the new `/health`\n\nfingerprint: it rewrites and restarts\nthe existing `tokdash.service`\n\n. Use `tokdash setup --no-service`\n\nto skip service creation.\n\nIf your current setup uses a conda/system/user-pip interpreter and you want `tokdash update`\n\nto manage future upgrades, migrate the service to Tokdash's setup-owned venv:\n\n```\n# Upgrade the tokdash command you are about to run, for example:\npython3 -m pip install --user -U tokdash\n# or, for a conda base install:\nconda run -n base python -m pip install -U tokdash\ntokdash setup --runtime venv --force\ntokdash doctor\n```\n\nThis keeps your usage history under `~/.tokdash`\n\n, rewrites the user service to run\n`~/.tokdash/runtime/python-venv/bin/python -m tokdash`\n\n, and lets future `tokdash update`\n\nupgrade that managed venv and restart the service. If you installed with pipx, you can\ninstead keep the pipx runtime and upgrade with `tokdash update`\n\nor `pipx upgrade tokdash`\n\n.\n\nTokdash stays loopback-bound by default. For remote access, prefer:\n\n- interactive\n`tokdash setup`\n\n, which can offer an explicit Tailscale Serve step when available, - SSH forwarding:\n`ssh -L 55423:127.0.0.1:55423 <user>@<host>`\n\n.\n\nSome Tailscale installs require operator permission before a non-root user can configure Serve.\nIf Tailscale denies the Serve config, the interactive wizard can offer the one-time\n`sudo tailscale set --operator=$USER`\n\nstep and then retry `tailscale serve`\n\n. Tokdash uses\nthe `/tokdash`\n\npath on your tailnet host, so it does not claim the domain root if you already\nserve other tools there. After Serve succeeds, setup prints the exact\n`https://...ts.net/tokdash`\n\nURL to open from your tailnet.\n\nTailscale 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.\n\n**Tailscale on Windows:** the Windows Tailscale client installs both a GUI and a `tailscale`\n\nCLI, and `tailscale serve`\n\nworks the same way from PowerShell/cmd once the client is\nrunning. Native Windows support has initial CI and smoke-test coverage, but the\nTailscale Serve + native Windows combination has not yet been validated end to end\nagainst Tokdash, so treat that specific path as experimental until confirmed.\n\nBinding Tokdash directly to `0.0.0.0`\n\nis possible but not recommended because the local API is\nnot an internet-facing authenticated service.\n\nIf you only want a one-off foreground process:\n\n```\ntokdash serve\n```\n\nOpen `http://127.0.0.1:55423`\n\n. Use `tokdash serve --port <port>`\n\nif the default port is busy.\n\nFor full onboarding details, including runtime choices, WSL/systemd behavior, macOS launchd,\nTailscale, bundling, update checks, and safe uninstall semantics, see\n.\n\n`docs/ONBOARDING.md`\n\nTokdash can power daily/weekly/monthly OpenClaw usage reports by querying the local API on a schedule.\n\nCopy and paste this prompt to your LLM agent (Claude Code, AmpCode, Cursor, etc.):\n\n```\nInstall and configure scheduled Tokdash usage reports for OpenClaw by following the instructions here:\nhttps://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/openclaw_reporting/AGENTS.md\n\nOr read the guide yourself, but seriously, let an agent do it.\n```\n\nFetch the installation guide and follow it:\n\n```\ncurl -s https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/agents/openclaw_reporting/AGENTS.md\n```\n\nThe local API can power a statusline item in your coding agent (Claude Code, etc.) showing live token/cost stats.\n\n**Ready-made templates** live in [ docs/examples/statusline/](/JingbiaoMei/Tokdash/blob/main/docs/examples/statusline) — copy one into\n\n`~/.claude/scripts/`\n\nand add the `statusLine`\n\nblock to `~/.claude/settings.json`\n\n:→ one line:`statusline-minimal.sh`\n\n`[Claude Sonnet 4.6] 📁 myproject | 📊 12.3M ($4.56) today`\n\n→ a four-row dashboard with today + week totals and a top-3 per-tool breakdown`statusline-full.sh`\n\n→ the same one-line output as the minimal template, for Claude Code running natively on Windows (PowerShell, no`statusline.ps1`\n\n`curl`\n\n/`jq`\n\nneeded)\n\nAll 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.\n\nPrefer to roll your own? Hand your agent this prompt and point it at [ docs/API.md](/JingbiaoMei/Tokdash/blob/main/docs/API.md):\n\n\"I would like to add a statusline item from the tokdash endpoint's API; it should show the total tokens used today.\"\n\nTokdash is **localhost-only by default**.\n\n`TOKDASH_HOST`\n\n(default:`127.0.0.1`\n\n)`TOKDASH_PORT`\n\n(default:`55423`\n\n)`TOKDASH_CACHE_TTL`\n\n(default:`600`\n\nseconds)`TOKDASH_COMPUTE_CONCURRENCY`\n\n(default:`2`\n\n) — cap on simultaneous heavy history reparses; excess cold requests return a fast`503`\n\ninstead of saturating the server under load`TOKDASH_LIMIT_CONCURRENCY`\n\n(default:`64`\n\n) — uvicorn connection cap (backpressure)`TOKDASH_KEEPALIVE`\n\n(default:`5`\n\nseconds) — uvicorn keep-alive timeout`TOKDASH_ALLOW_ORIGINS`\n\n(comma-separated, default: empty)`TOKDASH_ALLOW_ORIGIN_REGEX`\n\n(default allows only localhost/127.0.0.1)`TOKDASH_NO_RETENTION_NOTICE`\n\n(set to`1`\n\nto silence the history-retention reminder printed on`tokdash serve`\n\n)\n\nPersistent usage DB (default on):\n\nTokdash maintains a local SQLite index at `~/.tokdash/usage.sqlite3`\n\nby 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.\n\n`TOKDASH_USAGE_DB`\n\n(default:`1`\n\n) — set to`0`\n\n,`false`\n\n,`no`\n\n, or`off`\n\nto disable the persistent usage DB`TOKDASH_DATA_DIR`\n\n(default:`~/.tokdash`\n\n) — base directory for Tokdash local state`TOKDASH_USAGE_DB_PATH`\n\n(default:`$TOKDASH_DATA_DIR/usage.sqlite3`\n\n) — explicit SQLite file path`TOKDASH_USAGE_DB_DURABLE`\n\n(default:`1`\n\n) — keep already indexed rows if a source file temporarily disappears or a parser returns no rows; set to`0`\n\nfor strict source replacement`TOKDASH_USAGE_DB_WATCH`\n\n(default:`0`\n\n) — set to`1`\n\nto run a background sync loop inside`tokdash serve`\n\n`TOKDASH_USAGE_DB_WATCH_INTERVAL`\n\n(default:`30`\n\nseconds) — sync interval for`tokdash db watch`\n\nand the serve-time watch loop\n\nDB maintenance commands:\n\n```\ntokdash db status --pretty\ntokdash db sync --pretty\ntokdash db verify --verify-period today --pretty\ntokdash db repair --dry-run --pretty\ntokdash db resync --pretty\ntokdash db watch --pretty\n```\n\nRemote access through Tailscale Serve:\n\n```\ntokdash setup\n# When the wizard offers Tailscale Serve, confirm it.\n# Setup prints the exact https://...ts.net/tokdash URL after Serve succeeds.\n```\n\nIf you manage Tailscale yourself after setup has started Tokdash on the default port:\n\n```\ntailscale serve --bg --https=443 --set-path=/tokdash http://127.0.0.1:55423\n```\n\nOpen `https://<machine>.<tailnet>.ts.net/tokdash`\n\n. Stop that manual Serve rule with\n`tailscale serve --https=443 --set-path=/tokdash off`\n\n. `tokdash uninstall`\n\nonly reverts\nTailscale Serve rules that the setup wizard created and recorded. Tailscale Serve remains\nread-only for mutating dashboard/API actions; use SSH forwarding when you need trusted remote\nwrites.\n\nBy default `tokdash serve`\n\nopens the dashboard in your browser once on startup. Pass `--no-open`\n\nto disable this (it is also skipped automatically in headless/SSH environments and in the background service templates).\n\n**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`\n\n; 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`\n\nby default. Prefer Tailscale Serve or SSH tunneling for remote access; avoid`--bind 0.0.0.0`\n\nunless 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.\n\nThe 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:\n\n```\ntokdash quota consent --codex-api on --claude-api on --antigravity-api on\ntokdash quota consent --poll-interval 30      # background poll cadence: 15, 30, 60 or 120 min\ntokdash quota consent --enabled off           # master switch: turn ALL quota tracking off\ntokdash quota poll\ntokdash quota show\n```\n\n**Master switch.** `quota.enabled`\n\n(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`\n\n. When it is off (or the `TOKDASH_QUOTA_POLL=0`\n\nkill switch is set), the background poller idles completely, `POST /api/quota/refresh`\n\nreturns 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.\n\n**Poll interval.** The background poller snapshots every **30 minutes** by default. Choose 15/30/60/120 minutes from the Quota tab, during `tokdash setup`\n\n, or with `tokdash quota consent --poll-interval N`\n\n; it is saved as `quota.poll_interval_minutes`\n\nin `config.json`\n\n. The `TOKDASH_QUOTA_POLL_INTERVAL`\n\nenv 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.\n\nWhen enabled, Tokdash reads credentials from `$CODEX_HOME/auth.json`\n\n, Claude's `CLAUDE_CODE_OAUTH_TOKEN`\n\noverride or `$CLAUDE_CONFIG_DIR/.credentials.json`\n\n, and `~/.gemini/antigravity-cli/antigravity-oauth-token`\n\n, then calls only the corresponding provider quota endpoints. On macOS, Claude Code stores its credentials in the Keychain rather than `.credentials.json`\n\n; if neither the env var nor `.credentials.json`\n\nexists, Tokdash reads the Keychain item (`Claude Code-credentials`\n\n) 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`\n\n(create one with `claude setup-token`\n\n) as an override. Tokdash never refreshes or writes provider credentials. `TOKDASH_QUOTA_POLL=0`\n\nis a hard kill switch for all quota tracking. `tokdash export`\n\nexcludes quota data by default; use `--include-quota`\n\nonly when you intentionally want it in the JSON.\n\n`tokdash setup`\n\noffers an optional quota step (per-provider network consent, default No, plus the poll interval), and `tokdash doctor`\n\nreports the quota state: master switch, per-provider consent, kill switch, effective interval and its source, last poll time, and the stored snapshot count.\n\nQuota snapshots and their history live in the local usage database (`usage.sqlite3`\n\n, enabled by default) and are **kept indefinitely by default** — set `TOKDASH_QUOTA_RETENTION_DAYS`\n\nto a positive number of days to prune older snapshots. If you opt out of local persistence with `TOKDASH_USAGE_DB=0`\n\n, 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.\n\nTokdash is a local HTTP server. Common endpoints:\n\n`GET /api/usage?period=today|week|month|N`\n\n`GET /api/usage?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD`\n\n`GET /api/tools?period=...`\n\n(coding tools only)`GET /api/openclaw?period=...`\n\n(OpenClaw only)`GET /api/sessions?tool=codex|claude|opencode|pi_agent&period=...`\n\n(append`&include_review_sessions=true`\n\nto include Codex review/permission sessions, hidden by default)`GET /api/quota`\n\nand`GET /api/quota/history`\n\n(subscription quota snapshots; network refresh is write-gated and opt-in)`GET /api/stats`\n\n(contribution calendar & statistics)\n\nExample:\n\n```\ncurl 'http://127.0.0.1:55423/api/usage?period=today'\n```\n\nFull API reference: [ docs/API.md](/JingbiaoMei/Tokdash/blob/main/docs/API.md) — schema, parameters, and response shapes for every endpoint.\n\nToken counts depend on what each client logs locally. Costs are computed from the bundled pricing database (`src/tokdash/pricing_db.json`\n\n) by default, or from your saved dashboard pricing override at `<data_dir>/pricing_db.json`\n\nwhen 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.\n\nTokdash 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:\n\n**Claude Code** deletes sessions older than`cleanupPeriodDays`\n\n(**default 30 days**) at startup. Add this to your existing`~/.claude/settings.json`\n\n(and any alternate`CLAUDE_CONFIG_DIR`\n\n):\n\n```\n{ \"cleanupPeriodDays\": 3650 }\n```\n\n**Gemini CLI** deletes sessions older than 30 days. Disable it in`~/.gemini/settings.json`\n\n; if a project has`.gemini/settings.json`\n\n, make the same change there because workspace settings override user settings:\n\n```\n{ \"general\": { \"sessionRetention\": { \"enabled\": false } } }\n```\n\nEvery 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**.\n\nSee `docs/ROADMAP.md`\n\n.\n\n- Contributing guide:\n`docs/CONTRIBUTING.md`\n\n- Security policy:\n`docs/SECURITY.md`\n\n```\ntokdash/\n├── main.py                 # Source entrypoint (python3 main.py)\n├── tokdash                 # Source CLI wrapper (./tokdash serve)\n├── src/\n│   └── tokdash/\n│       ├── cli.py\n│       ├── api.py                # FastAPI routes/app\n│       ├── compute.py            # Aggregation/merging logic\n│       ├── dateutil.py           # Shared date-range parsing\n│       ├── sessions.py           # Session explorer logic\n│       ├── pricing.py            # PricingDatabase wrapper\n│       ├── assets.py             # Static asset management\n│       ├── model_normalization.py\n│       ├── pricing_db.json\n│       ├── sources/\n│       │   ├── openclaw.py       # OpenClaw session log parser\n│       │   └── coding_tools.py   # Local coding tools parsers\n│       └── static/\n│           ├── index.html        # Single-page dashboard\n│           ├── theme-config.js   # Theme palettes & heatmap colors\n│           └── themes.css        # Per-theme CSS overrides\n└── docs/                   # Onboarding guide, API docs, release notes, and agent prompts\n```\n\nMIT License - see `LICENSE`\n\n.", "url": "https://wpnews.pro/news/show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking", "canonical_source": "https://github.com/JingbiaoMei/Tokdash", "published_at": "2026-07-04 11:53:02+00:00", "updated_at": "2026-07-04 12:20:23.025697+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-infrastructure"], "entities": ["Tokdash", "Claude Code", "Gemini CLI", "Codex", "Antigravity"], "alternates": {"html": "https://wpnews.pro/news/show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking", "markdown": "https://wpnews.pro/news/show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking.md", "text": "https://wpnews.pro/news/show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking.txt", "jsonld": "https://wpnews.pro/news/show-hn-tokdash-a-local-dashboard-for-ai-token-and-quota-tracking.jsonld"}}