# jingbiaomei/tokdash architecture

> Architecture diagram of the GitHub repository jingbiaomei/tokdash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jingbiaomei/tokdash
- Repository: https://github.com/jingbiaomei/tokdash

## Overview

Tokdash is a local dashboard for token usage, cost, activity, and provider quotas across AI coding tools. The main path is CLI or dashboard access, local log discovery and parsing, usage computation and persistence, then reporting through the web UI, TUI, or desktop companions. Setup and lifecycle management are a separate capability; quota polling and multi-server companion views are additional branches. Some major modules are represented from the README and source index because their implementation excerpts were not provided, so uncertain internal links are omitted.

Main entry points: [`src/tokdash/cli.py`](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/cli.py) (CLI), [`src/tokdash/compute.py`](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/compute.py) (Usage computation), [`src/tokdash/tui/app.py`](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/tui/app.py) (Terminal dashboard), [`companion/windows/TokdashCompanion/MultiServerTokdashClient.cs`](https://github.com/jingbiaomei/tokdash/blob/main/companion/windows/TokdashCompanion/MultiServerTokdashClient.cs) (Windows multi-server client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and setup"]
  node_cli["CLI<br/>[cli.py]"]
  node_setup["Setup lifecycle<br/>[engine.py]"]
  node_install_paths["Install paths<br/>[paths.py]"]
  node_manifest["Install manifest<br/>[manifest.py]"]
end

subgraph group_usage["Usage pipeline"]
  node_sessions["Session parsing<br/>[sessions.py]"]
  node_coding_tools["Tool parsers<br/>[coding_tools.py]"]
  node_openclaw["OpenClaw parser<br/>[openclaw.py]"]
  node_clientpaths["Client paths<br/>[clientpaths.py]"]
  node_compute["Usage computation<br/>[compute.py]"]
  node_pricing["Pricing<br/>[pricing.py]"]
  node_usage_store[("Usage store<br/>[usage_store.py]")]
end

subgraph group_quota["Quota tracking"]
  node_quota["Quota pollers<br/>[__init__.py]"]
  node_quota_config["Quota configuration<br/>[config.py]"]
end

subgraph group_views["Dashboard views"]
  node_api["Web API<br/>[api.py]"]
  node_tui["Terminal dashboard<br/>[app.py]"]
  node_tui_report["Terminal reports<br/>[report.py]"]
end

subgraph group_companion["Desktop companions"]
  node_mac_store["macOS companion"]
  node_mac_client["macOS API client"]
  node_win_store["Windows companion<br/>[CompanionStore.cs]"]
  node_win_client["Windows multi-server client"]
end

node_user(("User"))
node_tokdash_service{{"Tokdash service"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"runs setup"| node_setup
node_setup -->|"resolves paths"| node_install_paths
node_setup -->|"records lifecycle"| node_manifest
node_cli -->|"computes usage"| node_compute
node_compute -->|"uses session data"| node_sessions
node_compute -->|"uses parsers"| node_coding_tools
node_compute -->|"uses parser"| node_openclaw
node_compute -->|"applies rates"| node_pricing
node_compute -->|"stores usage"| node_usage_store
node_sessions -->|"resolves logs"| node_clientpaths
node_coding_tools -->|"resolves logs"| node_clientpaths
node_cli -->|"loads quota"| node_quota
node_quota -->|"reads settings"| node_quota_config
node_cli -->|"serves dashboard"| node_api
node_user -->|"views dashboard"| node_api
node_cli -->|"launches TUI"| node_tui
node_cli -->|"runs reports"| node_tui_report
node_tui -->|"loads usage"| node_compute
node_tui -->|"loads sessions"| node_sessions
node_tui -->|"reads stored data"| node_usage_store
node_mac_store -->|"fetches dashboard data"| node_mac_client
node_mac_client -->|"requests API"| node_tokdash_service
node_win_store -->|"fetches server data"| node_win_client
node_win_client -->|"fans out requests"| node_win_client
node_win_client -.->|"requests API"| node_tokdash_service

click node_cli "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/cli.py"
click node_setup "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/engine.py"
click node_install_paths "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/paths.py"
click node_manifest "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/manifest.py"
click node_api "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/api.py"
click node_sessions "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sessions.py"
click node_coding_tools "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/coding_tools.py"
click node_openclaw "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/openclaw.py"
click node_clientpaths "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/clientpaths.py"
click node_compute "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/compute.py"
click node_pricing "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/pricing.py"
click node_usage_store "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/usage_store.py"
click node_quota "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/quota/__init__.py"
click node_quota_config "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/quota/config.py"
click node_tui "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/tui/app.py"
click node_tui_report "https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/tui/report.py"
click node_mac_store "https://github.com/jingbiaomei/tokdash/blob/main/companion/macos/TokdashCompanion/CompanionStore.swift"
click node_mac_client "https://github.com/jingbiaomei/tokdash/blob/main/companion/macos/TokdashCompanion/TokdashClient.swift"
click node_win_store "https://github.com/jingbiaomei/tokdash/blob/main/companion/windows/TokdashCompanion/CompanionStore.cs"
click node_win_client "https://github.com/jingbiaomei/tokdash/blob/main/companion/windows/TokdashCompanion/MultiServerTokdashClient.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_setup,node_install_paths,node_manifest,node_user toneBlue
class node_sessions,node_coding_tools,node_openclaw,node_clientpaths,node_compute,node_pricing,node_usage_store toneAmber
class node_quota,node_quota_config toneMint
class node_api,node_tui,node_tui_report toneRose
class node_mac_store,node_mac_client,node_win_store,node_win_client,node_tokdash_service toneIndigo
```

## Components

### Entry and setup

- [CLI](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/cli.py): `src/tokdash/cli.py`
- [Setup lifecycle](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/engine.py): `src/tokdash/onboard/engine.py`
- [Install paths](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/paths.py): `src/tokdash/onboard/paths.py`
- [Install manifest](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/onboard/manifest.py): `src/tokdash/onboard/manifest.py`

### Usage pipeline

- [Session parsing](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sessions.py): `src/tokdash/sessions.py`
- [Tool parsers](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/coding_tools.py): `src/tokdash/sources/coding_tools.py`
- [OpenClaw parser](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/openclaw.py): `src/tokdash/sources/openclaw.py`
- [Client paths](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/clientpaths.py): `src/tokdash/clientpaths.py`
- [Usage computation](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/compute.py): `src/tokdash/compute.py`
- [Pricing](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/pricing.py): `src/tokdash/pricing.py`
- [Usage store](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/usage_store.py): `src/tokdash/usage_store.py`

### Quota tracking

- [Quota pollers](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/quota/__init__.py): `src/tokdash/sources/quota/__init__.py`
- [Quota configuration](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/sources/quota/config.py): `src/tokdash/sources/quota/config.py`

### Dashboard views

- [Web API](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/api.py): `src/tokdash/api.py`
- [Terminal dashboard](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/tui/app.py): `src/tokdash/tui/app.py`
- [Terminal reports](https://github.com/jingbiaomei/tokdash/blob/main/src/tokdash/tui/report.py): `src/tokdash/tui/report.py`

### Desktop companions

- [macOS companion](https://github.com/jingbiaomei/tokdash/blob/main/companion/macos/TokdashCompanion/CompanionStore.swift): `companion/macos/TokdashCompanion/CompanionStore.swift`
- [macOS API client](https://github.com/jingbiaomei/tokdash/blob/main/companion/macos/TokdashCompanion/TokdashClient.swift): `companion/macos/TokdashCompanion/TokdashClient.swift`
- [Windows companion](https://github.com/jingbiaomei/tokdash/blob/main/companion/windows/TokdashCompanion/CompanionStore.cs): `companion/windows/TokdashCompanion/CompanionStore.cs`
- [Windows multi-server client](https://github.com/jingbiaomei/tokdash/blob/main/companion/windows/TokdashCompanion/MultiServerTokdashClient.cs): `companion/windows/TokdashCompanion/MultiServerTokdashClient.cs`

### Other components

- **User**
- **Tokdash service**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- CLI → Setup lifecycle: runs setup (evidence: `src/tokdash/cli.py`)
- Setup lifecycle → Install paths: resolves paths (evidence: `src/tokdash/onboard/engine.py`)
- Setup lifecycle → Install manifest: records lifecycle (evidence: `src/tokdash/onboard/engine.py`)
- CLI → Usage computation: computes usage (evidence: `src/tokdash/cli.py`)
- Usage computation → Session parsing: uses session data (evidence: `src/tokdash/compute.py`)
- Usage computation → Tool parsers: uses parsers (evidence: `src/tokdash/compute.py`)
- Usage computation → OpenClaw parser: uses parser (evidence: `src/tokdash/compute.py`)
- Usage computation → Pricing: applies rates (evidence: `src/tokdash/compute.py`)
- Usage computation → Usage store: stores usage (evidence: `src/tokdash/compute.py`)
- Session parsing → Client paths: resolves logs (evidence: `src/tokdash/sessions.py`)
- Tool parsers → Client paths: resolves logs (evidence: `src/tokdash/sources/coding_tools.py`)
- CLI → Quota pollers: loads quota (evidence: `src/tokdash/cli.py`)
- Quota pollers → Quota configuration: reads settings (evidence: `src/tokdash/sources/quota/__init__.py`)
- CLI → Web API: serves dashboard (evidence: `src/tokdash/cli.py`)
- User → Web API: views dashboard (evidence: `README.md`)
- CLI → Terminal dashboard: launches TUI (evidence: `src/tokdash/cli.py`)
- CLI → Terminal reports: runs reports (evidence: `src/tokdash/cli.py`)
- Terminal dashboard → Usage computation: loads usage (evidence: `src/tokdash/tui/app.py`)
- Terminal dashboard → Session parsing: loads sessions (evidence: `src/tokdash/tui/app.py`)
- Terminal dashboard → Usage store: reads stored data (evidence: `src/tokdash/tui/app.py`)
- macOS companion → macOS API client: fetches dashboard data (evidence: `companion/macos/TokdashCompanion/CompanionStore.swift`)
- macOS API client → Tokdash service: requests API (evidence: `companion/macos/TokdashCompanion/TokdashClient.swift`)
- Windows companion → Windows multi-server client: fetches server data (evidence: `companion/windows/TokdashCompanion/CompanionStore.cs`)
- Windows multi-server client → Windows multi-server client: fans out requests (evidence: `companion/windows/TokdashCompanion/MultiServerTokdashClient.cs`)
- Windows multi-server client → Tokdash service: requests API