Tokdash
Agent Dashboard: Visualization and analytics for Sessions and Quota Usage. Track, analyze, and optimize token usage across providers with heatmaps, cost tracking, token counting and quota resets..
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/JingbiaoMei/Tokdash with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/JingbiaoMei/Tokdash'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/jingbiaomei--tokdash)HTML
<a href="/listings/jingbiaomei--tokdash"><img src="/api/listings/jingbiaomei--tokdash/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
pipx install tokdash tokdash setup
That's it. `tokdash setup` detects the runtime, installs a managed one if needed, registers a local service, and prints the dashboard URL — `http://127.0.0.1:55423`. Full options, first-run notes, and updates live in [Install & run](#install--run); prefer to look around first? The [live demo](https://tokdash.github.io/demo/) runs on the real UI.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 505 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <a href="README.md">English</a> | <a href="README_CN.md">中文</a> | <a href="README_JA.md">日本語</a> | <a href="README_KO.md">한국어</a> | <a href="README_ES.md">Español</a> | <a href="README_PT.md">Português</a>
- </p>
- <p align="center">
- <a href="https://tokdash.github.io/"><img src="https://raw.githubusercontent.com/JingbiaoMei/tokdash/main/docs/assets/tokdash_logo_full.png" alt="Tokdash" width="420" /></a>
- </p>
- <p align="center">
- <b>Local token & cost dashboard for AI coding tools</b>
- </p>
- <p align="center">
- <a href="https://opencode.ai/" title="OpenCode"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/opencode.png" alt="OpenCode" height="34"></a>
- <a href="https://openai.com/codex/" title="Codex"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/codex.png" alt="Codex" height="34"></a>
- <a href="https://www.claude.com/product/claude-code" title="Claude Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/claude.png" alt="Claude Code" height="34"></a>
- <a href="https://github.com/google-gemini/gemini-cli" title="Gemini CLI"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/gemini.png" alt="Gemini CLI" height="34"></a>
- <a href="https://antigravity.google/" title="Antigravity"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/antigravity.png" alt="Antigravity" height="34"></a>
- <a href="https://openclaw.ai/" title="OpenClaw"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/openclaw.png" alt="OpenClaw" height="34"></a>
- <a href="https://github.com/MoonshotAI/kimi-cli" title="Kimi CLI"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/kimi.png" alt="Kimi CLI" height="34"></a>
- <a href="https://mimo.xiaomi.com/coder" title="MiMo Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/mimo.png" alt="MiMo Code" height="34"></a>
- <a href="https://grok.com/build" title="Grok Build"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/grok.png" alt="Grok Build" height="34"></a>
- <a href="https://pi.dev/" title="Pi"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/pi.png" alt="Pi" height="34"></a>
- <a href="https://omp.sh/" title="omp"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/omp.png" alt="omp" height="34"></a>
- <a href="https://kilocode.ai/" title="Kilo Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/kilocode.png" alt="Kilo Code" height="34"></a>
- <a href="https://cline.bot/" title="Cline"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/cline.png" alt="Cline" height="34"></a>
- <a href="https://github.com/features/copilot" title="GitHub Copilot CLI"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/copilot.png" alt="GitHub Copilot CLI" height="34"></a>
- <a href="https://hermes-agent.nousresearch.com/" title="Hermes"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/hermes.png" alt="Hermes" height="34"></a>
- <a href="https://github.com/deepseek-ai/deepseek-harness" title="DeepSeek Harness"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/dsh.png" alt="DeepSeek Harness" height="34"></a>
- <a href="https://reasonix.io/" title="Reasonix"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/reasonix.png" alt="Reasonix" height="34"></a>
- <a href="https://zcode.z.ai" title="ZCode"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/zcode.png" alt="ZCode" height="34"></a>
- <a href="https://www.workbuddy.ai/" title="WorkBuddy"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/workbuddy.png" alt="WorkBuddy" height="34"></a>
- <a href="https://qoder.com/" title="Qoder IDE"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/qoder-ide.png" alt="Qoder IDE" height="34"></a>
- <a href="https://qoder.com/" title="Qoder CLI"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/qoder-cli.png" alt="Qoder CLI" height="34"></a>
- <a href="https://zed.dev/" title="Zed"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/zed.png" alt="Zed" height="34"></a>
- <a href="https://github.com/QwenLM/qwen-code" title="Qwen Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/qwen-code.png" alt="Qwen Code" height="34"></a>
- <a href="https://charm.land/crush" title="Crush"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/crush.png" alt="Crush" height="34"></a>
- <a href="https://dev.meta.ai/docs/muse-code" title="Muse Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/muse.png" alt="Muse Code" height="34"></a>
- <a href="https://freebuff.com/" title="Freebuff"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/freebuff.png" alt="Freebuff" height="34"></a>
- <a href="https://github.com/MiniMax-AI/minimax-code" title="MiniMax Code"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/minimax.png" alt="MiniMax Code" height="34"></a>
- <a href="https://devin.ai/cli" title="Devin CLI"><img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/agents/pills/devin.png" alt="Devin CLI" height="34"></a>
- </p>
- <p align="center">
- <img src="https://img.shields.io/badge/FastAPI-009688?style=flat&logo=fastapi&logoColor=white" alt="FastAPI" />
- <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white" alt="Python" />
- <img src="https://img.shields.io/badge/License-MIT-green?style=flat" alt="License" />
- <a href="https://tokdash.github.io/"><img src="https://img.shields.io/badge/Website-tokdash.github.io-1E40AF?style=flat&logo=githubpages&logoColor=white" alt="Website" /></a>
- <a href="https://tokdash.github.io/demo/"><img src="https://img.shields.io/badge/Live%20Demo-tokdash.github.io%2Fdemo-F59E0B?style=flat&logo=githubpages&logoColor=white" alt="Live Demo" /></a>
- <a href="https://github.com/JingbiaoMei/Tokdash/actions/workflows/ci.yml"><img src="https://github.com/JingbiaoMei/Tokdash/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
- <a href="https://pypi.org/project/tokdash/"><img src="https://img.shields.io/pypi/v/tokdash?style=flat" alt="PyPI" /></a>
- </p>
- <p align="center">
- <b>Try it without installing → <a href="https://tokdash.github.io/demo/">tokdash.github.io/demo</a></b>
- </p>
- > [!NOTE]
- > **Multiple machines, one dashboard.** Add the Tokdash instances running on WSL, a Mac, or any other box in Settings: every view combines whatever you select, the Servers tab compares the machines side by side, and the Quota tab keeps each provider's window bars and reset countdowns grouped per machine. [Remote access →](docs/guides/REMOTE_ACCESS.md) · [quota tracking →](#quota-tracking-optional)
- >
- > **Also from the same author: [Cosyncing](https://github.com/cosyncing/cosyncing).** Synchronize and control your agents — from CLI to GUI, from desktop to phone. Cosyncing keeps your coding agents in sync across your own network.
- ## Table of Contents
- - [Quick start](#quick-start)
- - [One package, four views](#one-package-four-views)
- - [WebUI](#webui)
- - [Terminal dashboard (TUI)](#terminal-dashboard-tui)
- - [Companion status bar app](#companion-status-bar-app)
- - [Statusline](#statusline)
- - [Install & run](#install--run)
- - [Features](#features)
- - [Quota tracking (optional)](#quota-tracking-optional)
- - [Cost accuracy note](#cost-accuracy-note)
- - [History retention](#history-retention)
- - [Roadmap](#roadmap)
- - [Contributing / security](#contributing--security)
- - [Documentation](#documentation)
- - [License](#license)
- ## Quick start
- ```bash
- pipx install tokdash
- tokdash setup
- ```
- That's it. `tokdash setup` detects the runtime, installs a managed one if
- needed, registers a local service, and prints the dashboard URL —
- `http://127.0.0.1:55423`. Full options, first-run notes, and updates live in
- [Install & run](#install--run); prefer to look around first? The
- [live demo](https://tokdash.github.io/demo/) runs on the real UI.
- ## One package, four views
- One local package, one local data index — and four ways to read it. Every surface
- parses the same session logs on your own machine, so the browser dashboard, the
- terminal, the menu bar, and your agent's statusline always agree.
- | View | What it is | Reach for it when |
- |---|---|---|
- | **[WebUI](#webui)** | The full dashboard: Overview, Sessions, Stats, Report, Quota, Servers | You want the whole picture, charts, and drill-down |
- | **[TUI](#terminal-dashboard-tui)** | `tokdash tui` — seven panes in the terminal: Overview, Sessions, Stats, Report, Speed, Quota, Pricing | You live in the terminal and want the numbers without a browser |
- | **[Companion](#companion-status-bar-app)** | Native menu-bar (macOS) / notification-area (Windows) app | You want today's spend and quota visible all day, dashboard closed |
- | **[Statusline](#statusline)** | A live token/cost item inside your agent's statusline | You want the cost ticker exactly where you type |
- ### WebUI
- The dashboard is a single page served by the local FastAPI app: exact input /
- cache / output token breakdowns, per-tool and per-model tables, a contribution
- heatmap, a week/month/year **Report**, per-provider **Quota** windows with reset
- countdowns, and a **Servers** tab that combines and compares several machines.
- Click any screenshot to open the [live demo](https://tokdash.github.io/demo/).
- <table>
- <tr>
- <td align="center">
- <b>Overview</b><br />
- <a href="https://tokdash.github.io/demo/">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-overview-en-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-overview-en-light.png" alt="Tokdash overview dashboard - click for live demo" width="470" />
- </picture>
- </a>
- </td>
- <td align="center">
- <b>Usage Report</b><br />
- <a href="https://tokdash.github.io/demo/">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-report-en-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-report-en-light.png" alt="Tokdash usage report - click for live demo" width="470" />
- </picture>
- </a>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>Quota tracking</b><br />
- <a href="https://tokdash.github.io/demo/">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-quota-en-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-quota-en-light.png" alt="Tokdash quota tracking - click for live demo" width="470" />
- </picture>
- </a>
- </td>
- <td align="center">
- <b>Multiple servers, one total</b><br />
- <a href="https://tokdash.github.io/demo/">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-servers-en-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-servers-en-light.png" alt="Tokdash Servers tab comparing machines - click for live demo" width="470" />
- </picture>
- </a>
- </td>
- </tr>
- </table>
- <p align="center"><sub>Light and dark follow your OS appearance. The app ships 17 style themes, light/dark modes, PWA install, and six UI languages (English / 中文 / 日本語 / 한국어 / Español / Português).</sub></p>
- ### Terminal dashboard (TUI)
- Prefer to stay in the terminal? `tokdash tui` opens **seven panes** —
- **Overview**, **Sessions**, **Stats**, **Report**, **Speed**, **Quota** and
- **Pricing** — without a browser, reading the same local index (and the shared
- on-disk database when a `tokdash serve` is running beside it). `F1`–`F7` jump
- between them, `v` lists them.
- <table>
- <tr>
- <td align="center">
- <b>TUI — Overview</b><br />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-tui-overview.png" alt="tokdash tui Overview tab" width="470" />
- </td>
- <td align="center">
- <b>TUI — Quota</b><br />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-tui-quota.png" alt="tokdash tui Quota tab" width="470" />
- </td>
- </tr>
- </table>
- ```bash
- tokdash tui
- ```
- <details>
- <summary>Keyboard</summary>
- | Key | Action |
- |---|---|
- | `q` | Quit |
- | `r` | Reload the current pane |
- | `F1`–`F7` | Overview / Sessions / Stats / Report / Speed / Quota / Pricing (`1` / `2` / `3` still jump to Overview / Report / Quota) |
- | `v` | Pick a view from the list |
- | `t` `d` `w` `m` `y` `a` | Set the shared range: today, yesterday, this week, this month, this year, all time |
- | `p` | More ranges (the strip's **More**); on Stats, an earlier year |
- | `P` | Stats: a later year, back up to the trailing 365 days |
- | `c` | Type an exact custom date range |
- | `[` / `]` | Step the range one whole period earlier / later — never into the future |
- | `0` | Back to today |
- | `/` | Search the focused table |
- | `s` | Cycle the sort of the focused table |
- | `enter` / `esc` | Open the selected row / close it |
- | `h` | Choose sources (Sessions and Speed) |
- | `H` | Walk Speed's sources one at a time |
- | `k` | Pick the Speed series |
- | `x` | Toggle the timing set (Speed) |
- | `b` | Cycle the Speed bucket |
- | `u` | Poll quota (Quota pane only) |
- | `?` | Help overlay with all keys |
- </details>
- <details>
- <summary>One-shot report CLI</summary>
- For a one-shot report you can pipe or script:
- ```bash
- tokdash report --period week
- ```
- The period is a flag, not a positional argument. Accepted values: `today` (the
- default), `week`, `month`, `year`, `all`, a number of days, or `Nd/Nw/Nm/Ny`
- shorthand; `week`, `month` and `year` are the same calendar-aligned windows the
- web Report tab shows. `tokdash report` also accepts `--json`, `--pretty` and
- `--output <file>`, following the same conventions as `tokdash export`.
- </details>
- ### Companion status bar app
- An optional native menu-bar app for macOS and notification-area app for Windows:
- a compact, read-only view of the Tokdash service without the dashboard open.
- <table>
- <tr>
- <td align="center">
- <a href="https://apps.microsoft.com/detail/9ppnmpdq8b52">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-mac-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-mac-light.png" alt="Tokdash Companion Status Bar App on macOS" width="300" />
- </picture>
- </a>
- </td>
- <td align="center">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-win-dark.png" />
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-win-light.png" alt="Tokdash Companion Status Bar App on Windows" width="300" />
- </picture>
- </td>
- </tr>
- <tr>
- <td align="center"><sub><b>macOS</b> menu bar</sub></td>
- <td align="center"><sub><b>Windows</b> notification area</sub></td>
- </tr>
- </table>
- **Windows — Microsoft Store** (recommended, signed by Microsoft, requires Windows 11):
- <p>
- <a href="https://apps.microsoft.com/detail/9ppnmpdq8b52?mode=direct">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://get.microsoft.com/images/en-us%20light.svg" />
- <img src="https://get.microsoft.com/images/en-us%20dark.svg" alt="Get Tokdash Companion from the Microsoft Store" width="200" />
- </picture>
- </a>
- </p>
- **Direct download** — the [latest companion release](https://github.com/JingbiaoMei/Tokdash/releases?q=companion-v):
- a universal DMG (`arm64` + `x86_64`, macOS 14+) and a self-contained portable ZIP
- (`x64`, Windows 11; Windows on Arm via x64 emulation).
- <details>
- <summary>What it shows, and how setup works</summary>
- - Today's cost, tokens, messages, and month-to-date usage
- - Combined totals and server-grouped quota from multiple Tokdash endpoints
- - Codex, Claude, Kimi, MiniMax, Antigravity, Grok, and Z.ai quota windows
- - Relative reset times and optional low-quota notifications
- - System language detection plus English, Simplified Chinese, Japanese, Korean, Spanish, and Portuguese
- - No telemetry, credential discovery, port scanning, or direct log parsing
- Setup: run **Tokdash 1.5.2 or newer** ([Install & run](#install--run)), install the
- companion, and it connects to `http://127.0.0.1:55423` by default — its settings
- let you add, test, name, or remove explicit endpoints, including private Tailscale
- Serve URLs. The companion only contacts the endpoints you configure; low-quota
- notifications and launch at login are opt-in.
- > [!WARNING]
- > The GitHub Releases binaries are **unsigned**. macOS Gatekeeper and Windows
- > SmartScreen will show an unknown-publisher warning. Download only from this
- > repository, verify the included `SHA256SUMS`, and continue only if you trust
- > the release. The Microsoft Store build is signed by Microsoft and is not
- > affected; macOS signing and notarization are planned for a later release.
- Checksum, update, and removal instructions live in the
- [companion release guide](companion/docs/RELEASE.md).
- </details>
- ### Statusline
- The local API can power a statusline item in your coding agent showing live
- token/cost stats:
- <p align="center">
- <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-statusline.png" alt="Tokdash statusline integration example" width="900" />
- </p>
- Ready-made templates (bash and PowerShell), install/config, and the endpoint
- reference live in **[`docs/guides/statusline/`](docs/guides/statusline/)**.
- ## Install & run
- ### Platform support
- - **Linux (including WSL2):** supported
- - **macOS:** supported
- - **Windows (native):** experimental
- **Prerequisites:** Python **3.10+** and one or more
- [supported clients](docs/reference/SUPPORTED_CLIENTS.md).
- ### Install
- Recommended isolated install:
- ```bash
- pipx install tokdash
- ```
- If you do not use pipx:
- ```bash
- python3 -m pip install --user tokdash
- ```
- ### First run
- Run the onboarding wizard:
- ```bash
- 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, run
- `tokdash setup --auto --json`; to preview what setup would change, `tokdash setup --dry-run`.
- To expose the dashboard explicitly on all network interfaces with writes disabled, run
- `tokdash setup --bind 0.0.0.0`; review the [remote-access guide](docs/guides/REMOTE_ACCESS.md) first.
- Then check the install:
- ```bash
- 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
- ```bash
- 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.
- <details>
- <summary>Existing installs: migration from before v1.0</summary>
- If you installed Tokdash before the onboarding flow, upgrade first:
- ```bash
- 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:
- ```bash
- # 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`.
- </details>
- ### Foreground fallback
- If you only want a one-off foreground process:
- ```bash
- tokdash serve
- ```
- Open `http://127.0.0.1:55423`. Use `tokdash serve --port <port>` if the default port is busy.
- By default `tokdash serve` opens the dashboard in your browser once on startup; pass
- `--no-open` to disable it. A bare `tokdash` with no command just prints the command help
- and exits — it no longer starts `tokdash serve` behind your back.
- For full onboarding details — runtime choices, WSL/systemd behavior, macOS launchd,
- Tailscale, bundling, update checks, and safe uninstall semantics — see
- **[`docs/guides/ONBOARDING.md`](docs/guides/ONBOARDING.md)**. For remote access through
- Tailscale Serve, SSH forwarding, or an explicit network bind, see
- **[`docs/guides/REMOTE_ACCESS.md`](docs/guides/REMOTE_ACCESS.md)**.
- ## Features
- - **Exact token counts**: Input/Output/Cache token breakdowns
- - **Session explorer**: per-session drill-down
- - **Contribution calendar**: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
- - **Report tab**: a week / month / year-to-date report of your own agent activity, with a shareable card for each tier of detail. Every export writes a light and a dark PNG
- - **Quota tab**: subscription window bars with reset countdowns for nine providers. Codex windows work out of the box from local logs; most other sources need opt-in [live polling](#quota-tracking-optional)
- - **Terminal dashboard** *[new]*: `tokdash tui` — Overview, Sessions, Stats, Report, Speed, Quota and Pricing in the terminal, no browser required
- - **Companion status bar app**: spend and subscription quota from the macOS menu bar or Windows notification area — on the [Microsoft Store](https://apps.microsoft.com/detail/9ppnmpdq8b52) for Windows
- - **Statusline integration**: a live token-usage indicator inside Claude Code's statusline (or any agent that can hit a local HTTP endpoint)
- - **Multi-server views**: add WSL, macOS, and other Tokdash servers in Settings; combine usage across any selection while keeping quota grouped by machine. See [remote access](docs/guides/REMOTE_ACCESS.md).
- - **Themes and app polish**: 17 style themes, light/dark mode, PWA install support, UI in six languages
- ## Supported clients
- Tokdash reads the local session logs of **27 supported agents** — the pill row
- above names them; the full matrix (usage & cost / Session Explorer coverage,
- per-client data paths, overrides, and source-specific accounting notes) is in
- **[Supported clients](docs/reference/SUPPORTED_CLIENTS.md)**.
- ## Quota tracking (optional)
- The Quota tab shows subscription utilization windows and reset countdowns for
- **nine providers**. Codex's 5-hour/weekly windows work out of the box from local
- logs (treat them as an estimate); accurate Codex consumption and every other
- provider — Claude Code, Antigravity, MiniMax, Kimi Code, Grok, Z.ai, OpenCode
- Go, Command Code — come from **opt-in live polling**: Tokdash calls each
- provider's own quota endpoint with the sign-in your CLI already has. Off by
- default, per-provider consent, results kept in the local database.
- The consent commands, master switch, poll cadence, and per-provider credential
- notes are in **[`docs/reference/QUOTA.md`](docs/reference/QUOTA.md)**.
- ## Cost Accuracy Note
- 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. Either way they may lag real provider pricing — use as an estimate and verify against your billing source if it matters.
- ## History retention
- > [!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.
- Tokdash reads each client's **local** session logs; the local SQLite index cannot
- recover logs deleted before they were indexed. Only two supported clients delete
- old sessions by default, and both are a one-line fix:
- - **Claude Code**: add `{ "cleanupPeriodDays": 3650 }` to `~/.claude/settings.json` (and any alternate `CLAUDE_CONFIG_DIR`).
- - **Gemini CLI**: set `{ "general": { "sessionRetention": { "enabled": false } } }` in `~/.gemini/settings.json` (workspace settings override user settings).
- 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/reference/HISTORY_RETENTION.md](docs/reference/HISTORY_RETENTION.md)**.
- ## Roadmap
- See `docs/development/ROADMAP.md`.
- ## Contributing / security
- - Contributing guide: `docs/CONTRIBUTING.md`
- - Security policy: `docs/SECURITY.md`
- ## Documentation
- Full documentation lives in **[`docs/`](docs/README.md)** (start at the index), grouped into:
- - **[guides/](docs/guides/)** — task-oriented setup: onboarding, remote access, statusline, background service.
- - **[reference/](docs/reference/)** — lookup material: API reference, configuration, quota internals, supported clients, history retention.
- - **[development/](docs/development/)** — changelog, releasing, roadmap, and public `technical-notes/`.
- ## License
- MIT License - see `LICENSE`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.