Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jingbiaomei--tokdash/badge.svg)](/listings/jingbiaomei--tokdash)

HTML

<a href="/listings/jingbiaomei--tokdash"><img src="/api/listings/jingbiaomei--tokdash/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. <p align="center">
  2. <a href="README.md">English</a> &nbsp;|&nbsp; <a href="README_CN.md">中文</a> &nbsp;|&nbsp; <a href="README_JA.md">日本語</a> &nbsp;|&nbsp; <a href="README_KO.md">한국어</a> &nbsp;|&nbsp; <a href="README_ES.md">Español</a> &nbsp;|&nbsp; <a href="README_PT.md">Português</a>
  3. </p>
  4. <p align="center">
  5. <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>
  6. </p>
  7. <p align="center">
  8. <b>Local token &amp; cost dashboard for AI coding tools</b>
  9. </p>
  10. <p align="center">
  11. <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>
  12. <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>
  13. <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>
  14. <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>
  15. <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>
  16. <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>
  17. <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>
  18. <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>
  19. <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>
  20. <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>
  21. <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>
  22. <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>
  23. <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>
  24. <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>
  25. <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>
  26. <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>
  27. <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>
  28. <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>
  29. <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>
  30. <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>
  31. <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>
  32. <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>
  33. <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>
  34. <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>
  35. <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>
  36. <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>
  37. <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>
  38. <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>
  39. </p>
  40. <p align="center">
  41. <img src="https://img.shields.io/badge/FastAPI-009688?style=flat&logo=fastapi&logoColor=white" alt="FastAPI" />
  42. <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white" alt="Python" />
  43. <img src="https://img.shields.io/badge/License-MIT-green?style=flat" alt="License" />
  44. <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>
  45. <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>
  46. <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>
  47. <a href="https://pypi.org/project/tokdash/"><img src="https://img.shields.io/pypi/v/tokdash?style=flat" alt="PyPI" /></a>
  48. </p>
  49. <p align="center">
  50. <b>Try it without installing → <a href="https://tokdash.github.io/demo/">tokdash.github.io/demo</a></b>
  51. </p>
  52. > [!NOTE]
  53. > **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)
  54. >
  55. > **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.
  56. ## Table of Contents
  57. - [Quick start](#quick-start)
  58. - [One package, four views](#one-package-four-views)
  59. - [WebUI](#webui)
  60. - [Terminal dashboard (TUI)](#terminal-dashboard-tui)
  61. - [Companion status bar app](#companion-status-bar-app)
  62. - [Statusline](#statusline)
  63. - [Install & run](#install--run)
  64. - [Features](#features)
  65. - [Quota tracking (optional)](#quota-tracking-optional)
  66. - [Cost accuracy note](#cost-accuracy-note)
  67. - [History retention](#history-retention)
  68. - [Roadmap](#roadmap)
  69. - [Contributing / security](#contributing--security)
  70. - [Documentation](#documentation)
  71. - [License](#license)
  72. ## Quick start
  73. ```bash
  74. pipx install tokdash
  75. tokdash setup
  76. ```
  77. That's it. `tokdash setup` detects the runtime, installs a managed one if
  78. needed, registers a local service, and prints the dashboard URL —
  79. `http://127.0.0.1:55423`. Full options, first-run notes, and updates live in
  80. [Install & run](#install--run); prefer to look around first? The
  81. [live demo](https://tokdash.github.io/demo/) runs on the real UI.
  82. ## One package, four views
  83. One local package, one local data index — and four ways to read it. Every surface
  84. parses the same session logs on your own machine, so the browser dashboard, the
  85. terminal, the menu bar, and your agent's statusline always agree.
  86. | View | What it is | Reach for it when |
  87. |---|---|---|
  88. | **[WebUI](#webui)** | The full dashboard: Overview, Sessions, Stats, Report, Quota, Servers | You want the whole picture, charts, and drill-down |
  89. | **[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 |
  90. | **[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 |
  91. | **[Statusline](#statusline)** | A live token/cost item inside your agent's statusline | You want the cost ticker exactly where you type |
  92. ### WebUI
  93. The dashboard is a single page served by the local FastAPI app: exact input /
  94. cache / output token breakdowns, per-tool and per-model tables, a contribution
  95. heatmap, a week/month/year **Report**, per-provider **Quota** windows with reset
  96. countdowns, and a **Servers** tab that combines and compares several machines.
  97. Click any screenshot to open the [live demo](https://tokdash.github.io/demo/).
  98. <table>
  99. <tr>
  100. <td align="center">
  101. <b>Overview</b><br />
  102. <a href="https://tokdash.github.io/demo/">
  103. <picture>
  104. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-overview-en-dark.png" />
  105. <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" />
  106. </picture>
  107. </a>
  108. </td>
  109. <td align="center">
  110. <b>Usage Report</b><br />
  111. <a href="https://tokdash.github.io/demo/">
  112. <picture>
  113. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-report-en-dark.png" />
  114. <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" />
  115. </picture>
  116. </a>
  117. </td>
  118. </tr>
  119. <tr>
  120. <td align="center">
  121. <b>Quota tracking</b><br />
  122. <a href="https://tokdash.github.io/demo/">
  123. <picture>
  124. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-quota-en-dark.png" />
  125. <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" />
  126. </picture>
  127. </a>
  128. </td>
  129. <td align="center">
  130. <b>Multiple servers, one total</b><br />
  131. <a href="https://tokdash.github.io/demo/">
  132. <picture>
  133. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-servers-en-dark.png" />
  134. <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" />
  135. </picture>
  136. </a>
  137. </td>
  138. </tr>
  139. </table>
  140. <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>
  141. ### Terminal dashboard (TUI)
  142. Prefer to stay in the terminal? `tokdash tui` opens **seven panes** —
  143. **Overview**, **Sessions**, **Stats**, **Report**, **Speed**, **Quota** and
  144. **Pricing** — without a browser, reading the same local index (and the shared
  145. on-disk database when a `tokdash serve` is running beside it). `F1`–`F7` jump
  146. between them, `v` lists them.
  147. <table>
  148. <tr>
  149. <td align="center">
  150. <b>TUI — Overview</b><br />
  151. <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-tui-overview.png" alt="tokdash tui Overview tab" width="470" />
  152. </td>
  153. <td align="center">
  154. <b>TUI — Quota</b><br />
  155. <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-tui-quota.png" alt="tokdash tui Quota tab" width="470" />
  156. </td>
  157. </tr>
  158. </table>
  159. ```bash
  160. tokdash tui
  161. ```
  162. <details>
  163. <summary>Keyboard</summary>
  164. | Key | Action |
  165. |---|---|
  166. | `q` | Quit |
  167. | `r` | Reload the current pane |
  168. | `F1`–`F7` | Overview / Sessions / Stats / Report / Speed / Quota / Pricing (`1` / `2` / `3` still jump to Overview / Report / Quota) |
  169. | `v` | Pick a view from the list |
  170. | `t` `d` `w` `m` `y` `a` | Set the shared range: today, yesterday, this week, this month, this year, all time |
  171. | `p` | More ranges (the strip's **More**); on Stats, an earlier year |
  172. | `P` | Stats: a later year, back up to the trailing 365 days |
  173. | `c` | Type an exact custom date range |
  174. | `[` / `]` | Step the range one whole period earlier / later — never into the future |
  175. | `0` | Back to today |
  176. | `/` | Search the focused table |
  177. | `s` | Cycle the sort of the focused table |
  178. | `enter` / `esc` | Open the selected row / close it |
  179. | `h` | Choose sources (Sessions and Speed) |
  180. | `H` | Walk Speed's sources one at a time |
  181. | `k` | Pick the Speed series |
  182. | `x` | Toggle the timing set (Speed) |
  183. | `b` | Cycle the Speed bucket |
  184. | `u` | Poll quota (Quota pane only) |
  185. | `?` | Help overlay with all keys |
  186. </details>
  187. <details>
  188. <summary>One-shot report CLI</summary>
  189. For a one-shot report you can pipe or script:
  190. ```bash
  191. tokdash report --period week
  192. ```
  193. The period is a flag, not a positional argument. Accepted values: `today` (the
  194. default), `week`, `month`, `year`, `all`, a number of days, or `Nd/Nw/Nm/Ny`
  195. shorthand; `week`, `month` and `year` are the same calendar-aligned windows the
  196. web Report tab shows. `tokdash report` also accepts `--json`, `--pretty` and
  197. `--output <file>`, following the same conventions as `tokdash export`.
  198. </details>
  199. ### Companion status bar app
  200. An optional native menu-bar app for macOS and notification-area app for Windows:
  201. a compact, read-only view of the Tokdash service without the dashboard open.
  202. <table>
  203. <tr>
  204. <td align="center">
  205. <a href="https://apps.microsoft.com/detail/9ppnmpdq8b52">
  206. <picture>
  207. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-mac-dark.png" />
  208. <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" />
  209. </picture>
  210. </a>
  211. </td>
  212. <td align="center">
  213. <picture>
  214. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/companion/demo-win-dark.png" />
  215. <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" />
  216. </picture>
  217. </td>
  218. </tr>
  219. <tr>
  220. <td align="center"><sub><b>macOS</b> menu bar</sub></td>
  221. <td align="center"><sub><b>Windows</b> notification area</sub></td>
  222. </tr>
  223. </table>
  224. **Windows — Microsoft Store** (recommended, signed by Microsoft, requires Windows 11):
  225. <p>
  226. <a href="https://apps.microsoft.com/detail/9ppnmpdq8b52?mode=direct">
  227. <picture>
  228. <source media="(prefers-color-scheme: dark)" srcset="https://get.microsoft.com/images/en-us%20light.svg" />
  229. <img src="https://get.microsoft.com/images/en-us%20dark.svg" alt="Get Tokdash Companion from the Microsoft Store" width="200" />
  230. </picture>
  231. </a>
  232. </p>
  233. **Direct download** — the [latest companion release](https://github.com/JingbiaoMei/Tokdash/releases?q=companion-v):
  234. a universal DMG (`arm64` + `x86_64`, macOS 14+) and a self-contained portable ZIP
  235. (`x64`, Windows 11; Windows on Arm via x64 emulation).
  236. <details>
  237. <summary>What it shows, and how setup works</summary>
  238. - Today's cost, tokens, messages, and month-to-date usage
  239. - Combined totals and server-grouped quota from multiple Tokdash endpoints
  240. - Codex, Claude, Kimi, MiniMax, Antigravity, Grok, and Z.ai quota windows
  241. - Relative reset times and optional low-quota notifications
  242. - System language detection plus English, Simplified Chinese, Japanese, Korean, Spanish, and Portuguese
  243. - No telemetry, credential discovery, port scanning, or direct log parsing
  244. Setup: run **Tokdash 1.5.2 or newer** ([Install & run](#install--run)), install the
  245. companion, and it connects to `http://127.0.0.1:55423` by default — its settings
  246. let you add, test, name, or remove explicit endpoints, including private Tailscale
  247. Serve URLs. The companion only contacts the endpoints you configure; low-quota
  248. notifications and launch at login are opt-in.
  249. > [!WARNING]
  250. > The GitHub Releases binaries are **unsigned**. macOS Gatekeeper and Windows
  251. > SmartScreen will show an unknown-publisher warning. Download only from this
  252. > repository, verify the included `SHA256SUMS`, and continue only if you trust
  253. > the release. The Microsoft Store build is signed by Microsoft and is not
  254. > affected; macOS signing and notarization are planned for a later release.
  255. Checksum, update, and removal instructions live in the
  256. [companion release guide](companion/docs/RELEASE.md).
  257. </details>
  258. ### Statusline
  259. The local API can power a statusline item in your coding agent showing live
  260. token/cost stats:
  261. <p align="center">
  262. <img src="https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/assets/demo-statusline.png" alt="Tokdash statusline integration example" width="900" />
  263. </p>
  264. Ready-made templates (bash and PowerShell), install/config, and the endpoint
  265. reference live in **[`docs/guides/statusline/`](docs/guides/statusline/)**.
  266. ## Install & run
  267. ### Platform support
  268. - **Linux (including WSL2):** supported
  269. - **macOS:** supported
  270. - **Windows (native):** experimental
  271. **Prerequisites:** Python **3.10+** and one or more
  272. [supported clients](docs/reference/SUPPORTED_CLIENTS.md).
  273. ### Install
  274. Recommended isolated install:
  275. ```bash
  276. pipx install tokdash
  277. ```
  278. If you do not use pipx:
  279. ```bash
  280. python3 -m pip install --user tokdash
  281. ```
  282. ### First run
  283. Run the onboarding wizard:
  284. ```bash
  285. tokdash setup
  286. ```
  287. The wizard configures a reversible user-level background service when the platform supports
  288. one, then prints the dashboard URL (default: `http://127.0.0.1:55423`). If no supported
  289. service manager is available, it records setup state and prints foreground run guidance. It
  290. uses localhost-first defaults, does not require `sudo` for the local service, and keeps your
  291. usage history unless you later uninstall with `--purge`.
  292. For a non-interactive setup from an agent, script, or bundle, run
  293. `tokdash setup --auto --json`; to preview what setup would change, `tokdash setup --dry-run`.
  294. To expose the dashboard explicitly on all network interfaces with writes disabled, run
  295. `tokdash setup --bind 0.0.0.0`; review the [remote-access guide](docs/guides/REMOTE_ACCESS.md) first.
  296. Then check the install:
  297. ```bash
  298. tokdash doctor
  299. ```
  300. `doctor` checks the runtime, background service, configured port, data paths, and update-check
  301. status. Use `tokdash doctor --json` for automation.
  302. ### Update or remove
  303. ```bash
  304. tokdash update # upgrade the managed runtime and restart the service when possible
  305. tokdash uninstall # reverse exactly what setup created; keeps usage history by default
  306. ```
  307. `update` only drives install methods Tokdash can safely manage. If your runtime was installed
  308. by a package manager Tokdash does not own, it prints the exact manual guidance instead of
  309. mutating that environment.
  310. <details>
  311. <summary>Existing installs: migration from before v1.0</summary>
  312. If you installed Tokdash before the onboarding flow, upgrade first:
  313. ```bash
  314. pipx upgrade tokdash
  315. # or: python3 -m pip install --user -U tokdash
  316. ```
  317. Then run `tokdash doctor` and `tokdash setup` when you want Tokdash to manage the background
  318. service. If you already have a hand-written systemd or launchd service, setup does **not**
  319. silently replace it: it refuses unmarked `tokdash.service` / plist files by default. Keep
  320. managing that service yourself, remove it before setup, or run `tokdash setup --force` after
  321. checking `tokdash setup --dry-run`. `--force` also handles pre-1.0 services that already
  322. occupy port `55423` but do not expose the new `/health` fingerprint: it rewrites and restarts
  323. the existing `tokdash.service`. Use `tokdash setup --no-service` to skip service creation.
  324. If your current setup uses a conda/system/user-pip interpreter and you want `tokdash update`
  325. to manage future upgrades, migrate the service to Tokdash's setup-owned venv:
  326. ```bash
  327. # Upgrade the tokdash command you are about to run, for example:
  328. python3 -m pip install --user -U tokdash
  329. # or, for a conda base install:
  330. conda run -n base python -m pip install -U tokdash
  331. tokdash setup --runtime venv --force
  332. tokdash doctor
  333. ```
  334. This keeps your usage history under `~/.tokdash`, rewrites the user service to run
  335. `~/.tokdash/runtime/python-venv/bin/python -m tokdash`, and lets future `tokdash update`
  336. upgrade that managed venv and restart the service. If you installed with pipx, you can
  337. instead keep the pipx runtime and upgrade with `tokdash update` or `pipx upgrade tokdash`.
  338. </details>
  339. ### Foreground fallback
  340. If you only want a one-off foreground process:
  341. ```bash
  342. tokdash serve
  343. ```
  344. Open `http://127.0.0.1:55423`. Use `tokdash serve --port <port>` if the default port is busy.
  345. By default `tokdash serve` opens the dashboard in your browser once on startup; pass
  346. `--no-open` to disable it. A bare `tokdash` with no command just prints the command help
  347. and exits — it no longer starts `tokdash serve` behind your back.
  348. For full onboarding details — runtime choices, WSL/systemd behavior, macOS launchd,
  349. Tailscale, bundling, update checks, and safe uninstall semantics — see
  350. **[`docs/guides/ONBOARDING.md`](docs/guides/ONBOARDING.md)**. For remote access through
  351. Tailscale Serve, SSH forwarding, or an explicit network bind, see
  352. **[`docs/guides/REMOTE_ACCESS.md`](docs/guides/REMOTE_ACCESS.md)**.
  353. ## Features
  354. - **Exact token counts**: Input/Output/Cache token breakdowns
  355. - **Session explorer**: per-session drill-down
  356. - **Contribution calendar**: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
  357. - **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
  358. - **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)
  359. - **Terminal dashboard** *[new]*: `tokdash tui` — Overview, Sessions, Stats, Report, Speed, Quota and Pricing in the terminal, no browser required
  360. - **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
  361. - **Statusline integration**: a live token-usage indicator inside Claude Code's statusline (or any agent that can hit a local HTTP endpoint)
  362. - **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).
  363. - **Themes and app polish**: 17 style themes, light/dark mode, PWA install support, UI in six languages
  364. ## Supported clients
  365. Tokdash reads the local session logs of **27 supported agents** — the pill row
  366. above names them; the full matrix (usage & cost / Session Explorer coverage,
  367. per-client data paths, overrides, and source-specific accounting notes) is in
  368. **[Supported clients](docs/reference/SUPPORTED_CLIENTS.md)**.
  369. ## Quota tracking (optional)
  370. The Quota tab shows subscription utilization windows and reset countdowns for
  371. **nine providers**. Codex's 5-hour/weekly windows work out of the box from local
  372. logs (treat them as an estimate); accurate Codex consumption and every other
  373. provider — Claude Code, Antigravity, MiniMax, Kimi Code, Grok, Z.ai, OpenCode
  374. Go, Command Code — come from **opt-in live polling**: Tokdash calls each
  375. provider's own quota endpoint with the sign-in your CLI already has. Off by
  376. default, per-provider consent, results kept in the local database.
  377. The consent commands, master switch, poll cadence, and per-provider credential
  378. notes are in **[`docs/reference/QUOTA.md`](docs/reference/QUOTA.md)**.
  379. ## Cost Accuracy Note
  380. 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.
  381. ## History retention
  382. > [!IMPORTANT]
  383. > **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.
  384. Tokdash reads each client's **local** session logs; the local SQLite index cannot
  385. recover logs deleted before they were indexed. Only two supported clients delete
  386. old sessions by default, and both are a one-line fix:
  387. - **Claude Code**: add `{ "cleanupPeriodDays": 3650 }` to `~/.claude/settings.json` (and any alternate `CLAUDE_CONFIG_DIR`).
  388. - **Gemini CLI**: set `{ "general": { "sessionRetention": { "enabled": false } } }` in `~/.gemini/settings.json` (workspace settings override user settings).
  389. Every other supported client keeps history indefinitely by default. For the full
  390. per-client survey, fix details, and what the local SQLite index does and does not
  391. preserve, see **[docs/reference/HISTORY_RETENTION.md](docs/reference/HISTORY_RETENTION.md)**.
  392. ## Roadmap
  393. See `docs/development/ROADMAP.md`.
  394. ## Contributing / security
  395. - Contributing guide: `docs/CONTRIBUTING.md`
  396. - Security policy: `docs/SECURITY.md`
  397. ## Documentation
  398. Full documentation lives in **[`docs/`](docs/README.md)** (start at the index), grouped into:
  399. - **[guides/](docs/guides/)** — task-oriented setup: onboarding, remote access, statusline, background service.
  400. - **[reference/](docs/reference/)** — lookup material: API reference, configuration, quota internals, supported clients, history retention.
  401. - **[development/](docs/development/)** — changelog, releasing, roadmap, and public `technical-notes/`.
  402. ## License
  403. MIT License - see `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.