Tokdash docs

August 21, 2026 · View on GitHub

Root

  • Contributing — how to propose changes and the manual release checklist pointer.
  • Security policy — how to report a vulnerability and the write-protection model.

guides/ — task-oriented setup guides

  • Onboarding — setup, doctor, update, and uninstall, Tokdash's Python-native service lifecycle.
  • Remote access — reaching a Tokdash instance from another machine (Tailscale Serve, SSH forwarding, wildcard binding).
  • Statusline templates — ready-made Claude Code statusline scripts (bash + PowerShell) that read local Tokdash totals.
  • Background service & agents — run Tokdash as a systemd/launchd service, the health-probe auto-restart, and the OpenClaw reporting cron.

reference/ — lookup material

  • API reference — the local HTTP API (FastAPI) for token usage, costs, and session data.
  • Supported clients — which coding tools Tokdash reads usage from and how detection works.
  • History retention — why Tokdash's past months can shrink, and how to prevent it.
  • Day boundaries — Tokdash buckets by your local day; why a provider's own usage page shows a different number.

development/ — maintainer workflows, release history, and design notes

  • Changelog — notable changes to the project, release by release.
  • Releasing — checklist for manual PyPI/Git tag/GitHub Releases publishing.
  • Roadmap — notes on planned and deferred work.
  • Companion release guide — tagging the menu-bar/tray app, the unsigned GitHub binaries, and the Microsoft Store (MSIX) track.

development/technical-notes/ — public technical notes and research

  • Usage-cache identity — how the persistent usage cache separates parse identity, billing provenance and pricing identity, and what each kind of change costs.
  • Codex usage counting — how Tokdash avoids double-counting Codex usage from MultiAgent V2 subagent replay.
  • Windows support plan — status and design of native Windows support.
  • Windows client data paths — research backing the Windows-support pass, per-client path survey.
  • DeepSeek Harness support design - implementation plan for durable dsh token usage and Session Explorer tracking.
  • Reasonix support design - implementation plan for Reasonix token usage, per-request stats mapping, and Session Explorer tracking.
  • ZCode support design - how Tokdash reads ZCode's local SQLite database for token and cost, and the token-accounting rules it follows.