Metadata-Version: 2.4
Name: tokdash
Version: 2.6.11
Summary: Local token & cost dashboard for AI coding tools
Author: Jingbiao Mei
License: MIT License
        
        Copyright (c) 2026 Jingbiao Mei
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/JingbiaoMei/tokdash
Project-URL: Repository, https://github.com/JingbiaoMei/tokdash
Project-URL: Issues, https://github.com/JingbiaoMei/tokdash/issues
Project-URL: Changelog, https://github.com/JingbiaoMei/tokdash/blob/main/docs/development/CHANGELOG.md
Keywords: token,cost,dashboard,llm,ai,codex,claude,gemini,antigravity,kimi
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: packaging>=21.0
Requires-Dist: zstandard>=0.23
Requires-Dist: textual<9,>=8.0.0
Dynamic: license-file

<p align="center">
  <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>
</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 &amp; 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>
</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` — Overview, Report and Quota in the terminal | 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 the **Overview**, **Report**,
and **Quota** tabs without a browser, reading the same local index (and the
shared on-disk database when a `tokdash serve` is running beside it).

<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` | Refresh the current tab |
| `1` / `2` / `3` | Switch to Overview / Report / Quota |
| `t` `w` `m` `y` `a` | Jump to a period directly (both period tabs; `t`/`a` are Overview-only) |
| `p` | Next time window (forward-only cycle) |
| `[` / `]` | Step one whole calendar period back / forward — never into the future |
| `0` | Back to today |
| `u` | Poll quota (Quota tab 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, Report and Quota 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`.
