tokmon 0.28.1 → 0.28.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +156 -234
  2. package/THIRD_PARTY_NOTICES.md +62 -0
  3. package/dist/{bootstrap-ink-L7QSJBMS.js → bootstrap-ink-WG4WG3R2.js} +1579 -1135
  4. package/dist/chunk-7CH6S7BR.js +447 -0
  5. package/dist/{chunk-CVKCVHS7.js → chunk-CFKUZCMB.js} +70 -310
  6. package/dist/chunk-HNWEJ6MS.js +1094 -0
  7. package/dist/chunk-JZSZEHVD.js +406 -0
  8. package/dist/{chunk-S33XIUAW.js → chunk-P57DVFNH.js} +277 -49
  9. package/dist/{chunk-4HU4EI5T.js → chunk-P5JN5DDX.js} +25 -46
  10. package/dist/chunk-TN6V7XSL.js +512 -0
  11. package/dist/chunk-USKOQIE3.js +278 -0
  12. package/dist/chunk-UYPDMVW5.js +21 -0
  13. package/dist/{cli-command-75LP4IDS.js → cli-command-MD3RJRP4.js} +249 -15
  14. package/dist/cli.js +6 -6
  15. package/dist/{config-HXFJTNLM.js → config-3DGZ47F7.js} +23 -3
  16. package/dist/daemon-EMOA36WB.js +377 -0
  17. package/dist/daemon-handle-JHE5MKMI.js +11 -0
  18. package/dist/server-EPSH52DR.js +12 -0
  19. package/dist/web/assets/{Area-CMXvOw33.js → Area-stRnp8Km.js} +1 -1
  20. package/dist/web/assets/analytics-moZZt9L_.js +2 -0
  21. package/dist/web/assets/breakdown-km9w7myU.js +4 -0
  22. package/dist/web/assets/button-DrX04Cc2.js +1 -0
  23. package/dist/web/assets/{chart-cZoLgpmG.js → chart-D0CtuL2k.js} +1 -1
  24. package/dist/web/assets/explore-B11uNJV1.js +22 -0
  25. package/dist/web/assets/index-RDhXsCNG.js +83 -0
  26. package/dist/web/assets/index-ZmOS8p9O.css +1 -0
  27. package/dist/web/assets/models-DYbZnY34.js +2 -0
  28. package/dist/web/assets/overview-CruICbfJ.js +2 -0
  29. package/dist/web/assets/panel-xckM3_GC.js +1 -0
  30. package/dist/web/assets/settings-sheet-G-BTSIF6.js +1 -0
  31. package/dist/web/assets/share-sheet-weIdd4DW.js +2 -0
  32. package/dist/web/assets/timeline-BHgniliZ.js +1 -0
  33. package/dist/web/index.html +30 -4
  34. package/package.json +13 -4
  35. package/site/THIRD_PARTY_NOTICES.md +83 -0
  36. package/site/public/fonts/OFL.txt +93 -0
  37. package/dist/chunk-3RTWFGGD.js +0 -275
  38. package/dist/chunk-FMP3P2WV.js +0 -299
  39. package/dist/chunk-HP5UZCXP.js +0 -436
  40. package/dist/chunk-SMPY52EV.js +0 -125
  41. package/dist/chunk-XDA5RJST.js +0 -193
  42. package/dist/daemon-CL4FJW26.js +0 -219
  43. package/dist/daemon-handle-QQLJE46Y.js +0 -10
  44. package/dist/server-EUO7CWYH.js +0 -11
  45. package/dist/web/assets/analytics-DqdZXOJL.js +0 -2
  46. package/dist/web/assets/breakdown-kOSSJ3mI.js +0 -4
  47. package/dist/web/assets/explore-vcsM8K9I.js +0 -22
  48. package/dist/web/assets/index-BErCXT7f.css +0 -1
  49. package/dist/web/assets/index-DH3dOnbg.js +0 -83
  50. package/dist/web/assets/models-B5ikm83_.js +0 -2
  51. package/dist/web/assets/overview-DD1kP8CP.js +0 -2
  52. package/dist/web/assets/panel-DTQBwExW.js +0 -1
  53. package/dist/web/assets/primitives-C36qJlA2.js +0 -1
  54. package/dist/web/assets/settings-sheet-_i2zTQjf.js +0 -1
  55. package/dist/web/assets/share-sheet-BLHmrFbm.js +0 -2
  56. package/dist/web/assets/timeline-B4uG-Emo.js +0 -1
  57. package/dist/web/assets/use-dialog-trap-bfaXEMz9.js +0 -1
package/README.md CHANGED
@@ -1,286 +1,208 @@
1
- # tokmon
2
-
3
- Terminal dashboard for **Claude Code**, **Codex**, **Cursor**, **Copilot**, **opencode**, **pi**, **Antigravity**, **Gemini**, and **Grok** — usage, costs, and rate limits, all in one place.
4
-
5
- Built with [Ink](https://github.com/vadimdemedes/ink) and TypeScript.
1
+ <p align="center">
2
+ <img src="site/public/icon.svg" width="96" height="96" alt="Tokmon">
3
+ </p>
4
+
5
+ <h1 align="center">tokmon</h1>
6
+
7
+ <p align="center">
8
+ Usage, cost, and rate-limit tracking for the coding tools on your machine.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/tokmon"><img alt="npm" src="https://img.shields.io/npm/v/tokmon?style=flat-square&color=6caa71"></a>
13
+ <a href="https://github.com/DavidIlie/tokmon/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/DavidIlie/tokmon?style=flat-square&color=7ccbcd"></a>
14
+ <a href="https://github.com/DavidIlie/tokmon/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/DavidIlie/tokmon/ci.yml?style=flat-square&label=CI"></a>
15
+ <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-bd7bcd?style=flat-square"></a>
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="#install">Install</a> ·
20
+ <a href="#providers">Providers</a> ·
21
+ <a href="docs/README.md">Docs</a> ·
22
+ <a href="https://github.com/DavidIlie/tokmon/releases">Desktop downloads</a>
23
+ </p>
6
24
 
7
25
  ![tokmon dashboard](screenshot.png)
8
26
 
9
- ## Quick Start
27
+ Tokmon collects the usage data your coding tools already keep locally, then
28
+ shows it in a terminal dashboard, a local web app, and a desktop tray app. The
29
+ three clients use one local daemon, so their totals, account names, limits, and
30
+ settings stay in sync.
10
31
 
11
- ```bash
12
- npx tokmon
13
- ```
32
+ It currently understands Claude Code, Codex, Cursor, Copilot, opencode, pi,
33
+ Antigravity, Gemini, and Grok.
14
34
 
15
- Or with pnpm:
35
+ ## Install
16
36
 
17
- ```bash
18
- pnpm dlx tokmon
19
- ```
20
-
21
- ### Global Install
37
+ Run the terminal dashboard without installing anything:
22
38
 
23
39
  ```bash
24
- npm install -g tokmon
40
+ npx tokmon
25
41
  ```
26
42
 
27
- Then run `tokmon`. On first launch you'll pick which providers to track; press `q` to quit any time.
28
-
29
- ## CLI Data Queries
30
-
31
- Scripts and coding agents can query the same daemon directly without opening the interactive dashboard:
43
+ Or install the CLI globally:
32
44
 
33
45
  ```bash
34
- tokmon usage # current-month usage by provider/account/model
35
- tokmon usage --period week --provider codex
36
- tokmon usage --model opus --json # stable machine-readable schema
37
- tokmon usage --period all --json --compact
38
- tokmon providers --json # accounts plus local config/auth/usage paths
39
- tokmon snapshot --refresh # complete raw daemon snapshot
40
- tokmon config path # tokmon config file location
46
+ npm install -g tokmon
47
+ tokmon
41
48
  ```
42
49
 
43
- `usage` refreshes local history by default; use `--cached` for the fastest cached answer or `--refresh` to refresh billing as well. JSON reports include `schemaVersion`, exact provider/account source IDs, per-model token and cost fields, and a `sources` collection that maps every model row to its provider home and discovered local paths. Run `tokmon usage --help` or `tokmon providers --help` for every filter and example.
44
-
45
- ## Providers
46
-
47
- **Usage providers** — full cost & token history (Today / Week / Month, sparkline, per-model table):
48
-
49
- | Provider | What it reads | What you get |
50
- |----------|---------------|--------------|
51
- | **Claude** | `~/.claude/projects/**/*.jsonl` | Cost & token history, plan (e.g. Max 20x), live 5h / weekly / Sonnet limits |
52
- | **Codex** | `~/.codex/sessions/**/rollout-*.jsonl` | Cost & token history, plan, live 5h / weekly limits, credit balance |
53
- | **Cursor** | Cursor API usage events + local `composerData` | Cost & token history (Today / Week / Month), plan, period spend, on-demand caps |
54
- | **opencode** | `~/.local/share/opencode/opencode.db` | Cost & token history across whatever providers opencode routes to (uses its own recorded cost) |
55
- | **pi** | `~/.pi/agent/sessions/**/*.jsonl` | Cost & token history (uses pi's own recorded cost) |
56
- | **Grok** | `~/.grok/logs/unified.jsonl` (+ session model join) | Cost & token history from Grok CLI turns, SuperGrok / credits billing when signed in |
57
-
58
- **Billing / quota providers** — plan + live quota or spend (no local token history):
59
-
60
- | Provider | What it reads | What you get |
61
- |----------|---------------|--------------|
62
- | **Copilot** | GitHub token (gh / VS Code) | Plan + premium-request & chat quota |
63
- | **Antigravity** | its `state.vscdb` OAuth → Google Cloud Code | Plan + per-pool (Gemini Pro/Flash/Claude) quota |
64
- | **Gemini** | `~/.gemini/oauth_creds.json` → Google Cloud Code | Plan + quota (re-run `gemini` to refresh an expired token) |
65
-
66
- tokmon auto-detects which tools are installed (on `PATH` or as a desktop app). On first launch you pick which to track, and when a new provider you have installed is added in an update, tokmon offers it once on the next launch. You can also toggle any provider in settings.
67
-
68
- Costs use each model's published pricing (or the tool's own recorded cost where it stores one). **Cached tokens are billed at the discounted cache-read rate**, not full input rate — so tokmon's totals reflect what you're actually charged, and tend to be far lower than tools that count cache reads at full price.
69
-
70
- ## Views
71
-
72
- ### Dashboard
73
-
74
- A responsive grid of provider cards (or one card at a time — see **Dashboard layout** in settings). Each card shows:
75
-
76
- - **Today / This Week / This Month** — cost and token summaries
77
- - **Burn rate** — current $/hr
78
- - **Cache saved** — what caching has saved you
79
- - **Rate limits** — live utilization bars with reset countdowns or exact reset dates
80
- - **Sparkline** — recent daily activity
81
-
82
- The grid reflows to fit your terminal — more columns when it's wide, compacting cards when it's short. With more providers than fit on screen, it splits into **pages**; **scroll** (mouse wheel) to move between them (or `↑`/`↓` / `[` `]`). When you track more than one account, a focus strip lets you view **All** together or zoom into a single account.
83
-
84
- A **Peak / Off-Peak** badge appears in the header (Claude only), fetched from [promoclock.co](https://promoclock.co) — peak hours drain session limits faster.
85
-
86
- ### Table
87
-
88
- Per-provider history with a provider selector (`p` / `P`), search (`/`), and sorting (`o`).
89
-
90
- For **Claude / Codex / Cursor / Grok** — Daily, Weekly, and Monthly breakdowns (6 months of history). Each row shows models used, input/output/cache tokens, and cost. Press `Enter` to expand a per-model breakdown:
91
-
92
- ```
93
- ▸ Apr 7 haiku-4-5, op~ 7.6K 487.0K 10.1M 1.1B $603.89
94
- ├─ opus-4-6 7.5K 485.0K 10.0M 1.1B $601.50
95
- └─ haiku-4-5 100 2.0K 100K 5.0M $2.39
96
- ```
50
+ The first run detects supported tools and lets you choose what to track. Node.js
51
+ 20 or newer is required; Node.js 24 or newer is recommended.
97
52
 
98
- ## Web Dashboard
53
+ For the menu-bar/tray app, download the macOS, Windows, or Linux build from
54
+ [GitHub Releases](https://github.com/DavidIlie/tokmon/releases). macOS builds are
55
+ signed and notarized. Windows builds are currently unsigned.
99
56
 
100
- Prefer a browser? `tokmon serve` starts a local web dashboard with the same data as the TUI — charts, global filtering, and shareable images — in a terminal-styled UI. Press `w` (or `W`) inside the TUI to open its ordinary local URL.
57
+ ## Three ways to use it
101
58
 
102
- ```bash
103
- tokmon serve # opens http://127.0.0.1:4317 in your browser
104
- tokmon serve --port 8080
105
- tokmon serve --no-open # don't auto-open the browser
106
- ```
59
+ | Surface | Best for | Start it |
60
+ | --- | --- | --- |
61
+ | Terminal | A fast overview while coding | `tokmon` |
62
+ | Web dashboard | Charts, filtering, all-time history, and exports | `tokmon serve` |
63
+ | Desktop | Pinned quota rings and quick account details | Install from Releases |
107
64
 
108
- It binds to `127.0.0.1` by default and reads the same local daemon state — nothing leaves your machine. The browser connects directly over a same-origin WebSocket; dashboard URLs have no token or login step. Optional LAN access can be enabled in settings, with an explicit unsafe-access warning, and takes effect after the daemon restarts. When publishing the dashboard through an ingress or reverse proxy, add each exact DNS name to **Allowed hosts** in settings (for example, `tokmon.example.com`); IP hosts remain allowed in LAN mode. The dashboard renders instantly from a cached snapshot, then streams live updates and goes idle when no tab is open. Press `R` or use the visible **Refresh** control to update it. Filter by provider, model, account, and period, flip between dark and light, and export any panel — or a summary card — as a PNG with the **Share** button.
65
+ The desktop app can pin two providers in the macOS menu bar. Clicking it opens
66
+ a compact view of every provider and account, including usage, reset times,
67
+ token totals, spend, cache savings, and recent history.
109
68
 
110
- ### Overview
69
+ ![Tokmon desktop quota popover](assets/desktop/tray-popover.png)
111
70
 
112
- KPIs with inline sparklines, provider cards with live rate-limit bars, and a cost-over-time chart that spans your full history by default. Toggle **merged** (one combined total) vs **split** (a line per provider), **all-time** vs the selected period, and linear vs log.
71
+ The web dashboard is bundled with the npm package and runs locally. It has
72
+ overview, analytics, model, and history views with `7d`, `30d`, `90d`, `MTD`,
73
+ `6M`, and all-time ranges.
113
74
 
114
75
  ![tokmon web dashboard — overview](assets/web/overview.png)
115
76
 
116
- ### Analytics
117
-
118
- A full-width, all-time daily-spend calendar — hover any day for a per-model spend breakdown — with at-a-glance stats (busiest day, daily average, top weekday, current streak), alongside cost-by-model, an interactive provider split, token composition, cache savings, and cumulative spend.
119
-
120
- ![tokmon web dashboard — analytics](assets/web/analytics.png)
121
-
122
- ### Models
123
-
124
- A leaderboard sortable by cost / tokens / calls, each row showing a per-model trend sparkline, cost-per-call, tokens, and calls — over tokens-by-model and cache-savings-by-model charts.
125
-
126
- ![tokmon web dashboard — models](assets/web/models.png)
127
-
128
- ### Explore
129
-
130
- The full daily / weekly / monthly table — searchable, sortable on every column, with expandable per-model breakdowns.
131
-
132
- ![tokmon web dashboard — explore](assets/web/explore.png)
133
-
134
- The dashboard is a prebuilt static bundle shipped in the package — no build step, fully offline.
135
-
136
- ## Keybindings
137
-
138
- ### Global
139
-
140
- | Key | Action |
141
- |-----|--------|
142
- | `Tab` | Switch between Dashboard and Table |
143
- | `←` `→` | (Dashboard) switch between Dashboard and Table |
144
- | scroll / `↑` `↓` / `[` `]` | (Dashboard) move between pages when paginated |
145
- | `a` `A` | Cycle account focus forward / back |
146
- | `0`–`9` | Jump to an account focus slot |
147
- | `r` / `R` | Refresh all usage, billing, peak, and history data |
148
- | `p` | Toggle privacy mode (configurable in settings) |
149
- | `w` `W` | Toggle the web dashboard (opens in your browser) |
150
- | `s` | Open settings |
151
- | `q` | Quit |
152
-
153
- ### Table
154
-
155
- | Key | Action |
156
- |-----|--------|
157
- | `P` | Cycle provider back |
158
- | `/` | Search (Esc clears) |
159
- | `o` | Cycle sort |
160
- | `d` `w` `m` | Daily / Weekly / Monthly *(Claude/Codex)* |
161
- | `←` `→` | Cycle period *(Claude/Codex)* |
162
- | `Enter` | Expand row — per-model breakdown *(Claude/Codex)* |
163
- | `↑` `↓` | Move cursor |
164
- | `g` `G` | Jump to top / bottom |
165
- | `PgUp` `PgDn` | Page scroll |
166
- | `Esc` | Clear search, then collapse row |
167
-
168
- ### Settings
77
+ ## Providers
169
78
 
170
- | Key | Action |
171
- |-----|--------|
172
- | `↑` `↓` | Select row |
173
- | `←` `→` | Adjust value / toggle |
174
- | `Enter` | Edit / confirm |
175
- | `Space` | Toggle provider · set account active |
176
- | `Shift`+`↑` `↓` | Reorder accounts |
177
- | `d` `x` | Delete account |
178
- | `s` / `Esc` | Close |
79
+ Tokmon has two kinds of integrations. Usage providers expose local token and
80
+ cost history; quota providers expose current plan limits or spend.
179
81
 
180
- ## Settings
82
+ ### Usage and cost
181
83
 
182
- Press `s` to open.
84
+ | Provider | Local source | Data shown |
85
+ | --- | --- | --- |
86
+ | Claude | `~/.claude/projects/**/*.jsonl` | Tokens, cost, cache savings, session/weekly/model limits |
87
+ | Codex | `~/.codex/sessions/**/rollout-*.jsonl` | Tokens, cost, plan, session/weekly limits, credits |
88
+ | Cursor | Cursor usage events and local composer data | Tokens, cost, plan, spend, on-demand caps |
89
+ | opencode | `~/.local/share/opencode/opencode.db` | Tokens and the costs recorded by opencode |
90
+ | pi | `~/.pi/agent/sessions/**/*.jsonl` | Tokens and the costs recorded by pi |
91
+ | Grok | `~/.grok/logs/unified.jsonl` and session metadata | Tokens, cost, SuperGrok limits, credits |
183
92
 
184
- **General**
93
+ ### Quota and billing
185
94
 
186
- - **Refresh interval** dashboard poll rate (default: 2s)
187
- - **Billing poll** rate-limit / spend API poll rate (default: 5m, min 1m to avoid rate limiting)
188
- - **Clear screen** clears the terminal on launch (like `watch`)
189
- - **Privacy mode** hides email addresses by default
190
- - **Privacy key** one-key dashboard toggle for privacy mode (default: `p`)
191
- - **Timezone** — IANA timezone, or `System`
192
- - **Dashboard layout** — `grid` (all providers at once) or `single` (one at a time)
193
- - **Default focus** — start on `all`, or remember your `last` focused account
194
- - **ASCII glyphs** — `auto` (detect), `on` (force ASCII), or `off` (force Unicode)
195
- - **Network access** — loopback-only by default; optional LAN access is explicitly marked unsafe
196
- - **Reset times** — show time remaining or the exact reset date/time in the configured timezone
95
+ | Provider | Data shown |
96
+ | --- | --- |
97
+ | Copilot | Plan, premium requests, and chat quota |
98
+ | Antigravity | Plan and per-model-pool quota |
99
+ | Gemini | Plan and Google Cloud Code quota |
197
100
 
198
- **Providers** toggle each provider on or off.
101
+ Cached input is priced at each model's cache-read rate. It is not counted as
102
+ full-price input or treated as free. See [the provider guide](docs/providers.md)
103
+ for detection, multiple-account, and API details.
199
104
 
200
- **Accounts** add, edit, reorder, and delete accounts. Each account has a provider, a name, a home directory (so you can track multiple logins across different `HOME`s), and an accent color. Multiple accounts per provider are supported.
105
+ ## Useful commands
201
106
 
202
- ## Options
107
+ The CLI can query the same daemon without opening the interactive dashboard:
203
108
 
109
+ ```bash
110
+ tokmon usage
111
+ tokmon usage --period week --provider codex
112
+ tokmon usage --model opus --json
113
+ tokmon usage --period all --json --compact
114
+ tokmon providers --json
115
+ tokmon snapshot --refresh
116
+ tokmon config get
204
117
  ```
205
- tokmon [options] Launch the terminal dashboard
206
- tokmon serve [options] Launch the web dashboard (http://127.0.0.1:4317)
207
- tokmon usage [options] Query usage by model (human or JSON)
208
- tokmon providers [options] Show accounts and local provider paths
209
- tokmon snapshot [options] Print the raw daemon snapshot as JSON
210
- tokmon config [path] Print the tokmon config file location
211
-
212
- Options:
213
- -i, --interval <seconds> Refresh interval in seconds (default: from config, or 2)
214
- --ascii Force ASCII glyphs (also: TOKMON_ASCII=1)
215
- --no-ascii Force Unicode glyphs
216
- -h, --help Show help
217
-
218
- serve options:
219
- -p, --port <n> Port to listen on (default: 4317, auto-falls back if taken)
220
- --no-open Don't open the browser automatically
221
- ```
222
-
223
- tokmon auto-detects whether your terminal can render Unicode (block sparklines, box borders) and falls back to ASCII on terminals/fonts that can't (e.g. legacy Windows console). Override with `--ascii` / `--no-ascii`, the `TOKMON_ASCII` env var, or the **ASCII glyphs** setting.
224
118
 
225
- ## Files
119
+ JSON reports include a schema version, provider and account source IDs, model
120
+ token/cost fields, and the local source paths behind each row. Start with
121
+ [`docs/cli.md`](docs/cli.md) for filters and automation examples.
226
122
 
227
- | Path | Purpose |
228
- |------|---------|
229
- | `~/.config/tokmon/config.json` (macOS/Linux) | Settings |
230
- | `%APPDATA%\tokmon\config.json` (Windows) | Settings |
231
- | `~/Library/Caches/tokmon` (macOS) | Parse cache |
232
- | `~/.cache/tokmon` (Linux, or `$XDG_CACHE_HOME`) | Parse cache |
233
- | `%LOCALAPPDATA%\tokmon\cache` (Windows) | Parse cache |
123
+ ## What is included
234
124
 
235
- Config writes are atomic (temp + rename) so a crash mid-save can't corrupt the file.
125
+ - Daily, weekly, monthly, and all-time usage by provider, account, and model
126
+ - Live quota bars with reset countdowns or exact reset dates
127
+ - Burn rate, cache savings, token composition, and recent activity graphs
128
+ - Multiple account homes, automatic discovery, and per-account opt-out
129
+ - Shared privacy mode and themes across terminal, web, and desktop
130
+ - Machine-readable CLI queries for scripts and coding agents
131
+ - A local daemon that prevents every client from polling providers separately
236
132
 
237
133
  ## Privacy
238
134
 
239
- tokmon runs entirely on your machine and reads everything **read-only**:
135
+ Tokmon is local-first and reads provider files without modifying them. SQLite
136
+ databases are opened read-only. Credentials are used only to ask the provider's
137
+ own API for your quota or billing data; tokens are never rendered or logged.
240
138
 
241
- - It never writes to any provider's data SQLite databases (Cursor, opencode) are opened strictly read-only.
242
- - Credentials are read only to call each provider's **own official API** (Anthropic, ChatGPT backend, Cursor, GitHub, Google Cloud Code) for *your own* usage. Tokens are never logged, displayed, or sent anywhere else.
243
- - The only outbound requests are to those provider APIs and the optional peak-pricing clock.
139
+ The daemon listens on loopback by default. LAN access is optional and clearly
140
+ marked unsafe in settings. See [privacy and security](docs/privacy-and-security.md)
141
+ for the exact files, network calls, and trust boundaries.
244
142
 
245
143
  ## How It Works
246
144
 
247
- tokmon runs a small local **daemon** that does all the data collection. The terminal UI and the web dashboard are both thin clients of it, talking over a local WebSocket — loopback-only by default — so a single process does the work and the TUI and web always show the same numbers. The daemon starts automatically with the TUI (and standalone via `tokmon serve`), and idle-pauses when nothing is watching.
248
-
249
- **Usage & cost**
250
- - Parses each tool's local session logs — Claude / Codex / pi `JSONL`, Cursor / opencode `SQLite` — and aggregates cost and token usage per day, week, and month.
251
- - Cost is an API-equivalent estimate from each model's published pricing, counting cached input at the discounted cache-read rate (not the full input rate, not free).
252
- - A persistent parse cache keyed by file **mtime + size** makes repeat launches near-instant; edited or deleted files are re-read automatically.
253
-
254
- **Accounts**
255
- - Each enabled provider is detected automatically, and its real account identity — email and plan — is read from local auth (e.g. Claude `~/.claude.json`, the Codex `id_token`, Cursor's state DB). Extra accounts, like additional Claude homes, are auto-discovered too.
145
+ One daemon owns collection, parsing, settings, and the stable RPC contract. The
146
+ TUI, browser dashboard, desktop renderer, and CLI query commands are clients of
147
+ that contract. Whichever client starts first owns the daemon; compatible clients
148
+ attach to it instead of starting another collector.
149
+
150
+ Local history is cached by file modification time and size, so repeat launches
151
+ do not parse every session again. Usage history and live billing refresh on
152
+ separate schedules. Development commands use a tagged daemon channel and cannot
153
+ collide with an installed release.
154
+
155
+ The architecture and daemon lifecycle are documented in
156
+ [`docs/how-it-works.md`](docs/how-it-works.md).
157
+
158
+ ## Documentation
159
+
160
+ | Guide | Covers |
161
+ | --- | --- |
162
+ | [Getting started](docs/getting-started.md) | Installation, first run, and requirements |
163
+ | [Providers](docs/providers.md) | Sources, detection, accounts, billing, and limits |
164
+ | [Terminal UI](docs/tui.md) | Views and keybindings |
165
+ | [CLI queries](docs/cli.md) | `usage`, `providers`, `snapshot`, and JSON output |
166
+ | [Web dashboard](docs/web-dashboard.md) | Local server, filters, exports, and LAN mode |
167
+ | [Desktop app](docs/desktop.md) | Pins, popover, updates, and daemon attachment |
168
+ | [Configuration](docs/configuration.md) | Settings, themes, discovery, accounts, and files |
169
+ | [Privacy and security](docs/privacy-and-security.md) | Local data and network boundaries |
170
+ | [How it works](docs/how-it-works.md) | Daemon, RPC contracts, caching, and client ownership |
171
+ | [Development](docs/development.md) | Repository layout, checks, and development channels |
172
+ | [Releasing](docs/releasing.md) | Tags, signing, artifacts, and package publication |
173
+
174
+ ## Development
256
175
 
257
- **Limits & billing**
258
- - Rate limits and remaining spend/quota come from each provider's own official API. Tokmon refreshes them on the configured billing interval; terminal focus and extra dashboard viewers reuse fresh data instead of issuing extra provider requests.
259
-
260
- **Responsiveness**
261
- - Dashboard summaries and table history load independently and refresh on separate intervals, so the UI stays responsive even on large histories.
262
- - The TUI shows the usage and limits cadences separately and reconnects automatically if a suspended terminal leaves its live stream stale.
263
-
264
- Cross-platform: macOS, Linux, Windows. Everything is local and read-only — see [Privacy](#privacy).
265
-
266
- ## Requirements
267
-
268
- - Node.js 20+ (**24+ recommended**)
269
- - The CLIs/apps you want to track
270
- - **SQLite** for the Cursor / opencode readers: on Node 24+ this uses the built-in `node:sqlite` — **nothing to install**. On Node 20–23 it falls back to the system `sqlite3` CLI (preinstalled on macOS; `apt install sqlite3` / `winget install sqlite` elsewhere).
176
+ ```bash
177
+ pnpm install
178
+ pnpm --prefix web install
179
+ pnpm --prefix site install
180
+ pnpm run check
181
+ pnpm run check:desktop
182
+ pnpm run check:site
183
+ pnpm run build
184
+ ```
271
185
 
272
- ## CI/CD
186
+ This repository is a pnpm workspace for the published CLI and Electron app.
187
+ The web dashboard and marketing site have isolated lockfiles because they ship
188
+ through different paths and should not enter the npm or Electron dependency
189
+ graphs. The layout is intentional; it is not a conventional `apps/*` monorepo.
273
190
 
274
- Publishes to npm and GitHub Packages via GitHub Actions on version tags:
191
+ Read [the development guide](docs/development.md) before changing daemon
192
+ ownership, shared contracts, packaging paths, or release workflows.
275
193
 
276
- ```bash
277
- git tag v0.14.0 && git push --tags
278
- ```
194
+ ## Acknowledgements
279
195
 
280
- ## Author
196
+ The desktop interaction was researched against
197
+ [OpenUsage](https://github.com/robinebers/openusage),
198
+ [CodexBar](https://github.com/steipete/CodexBar), and
199
+ [ccusage](https://github.com/ryoppippi/ccusage). Provider vector marks and
200
+ compact reset formatting adapted from OpenUsage are used under its MIT license.
201
+ See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.
281
202
 
282
- By [David Ilie](https://davidilie.com)
203
+ Tokmon is built with [Ink](https://github.com/vadimdemedes/ink), React,
204
+ Effect, Astro, and Electron.
283
205
 
284
206
  ## License
285
207
 
286
- [MIT](LICENSE)
208
+ [MIT](LICENSE) © [David Ilie](https://davidilie.com)
@@ -0,0 +1,62 @@
1
+ # Third-party notices
2
+
3
+ Tokmon Desktop adapts provider vector marks and compact reset-duration behavior from
4
+ [OpenUsage](https://github.com/robinebers/openusage), licensed under the MIT License:
5
+
6
+ MIT License
7
+
8
+ Copyright (c) 2026 Robin Ebers
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ ---
29
+
30
+ Tokmon's web and marketing interfaces bundle JetBrains Mono (Copyright 2020
31
+ The JetBrains Mono Project Authors) and Departure Mono (Copyright 2022-2024
32
+ Helena Zhang). Both are distributed under the SIL Open Font License 1.1. The
33
+ complete license text is included at `site/public/fonts/OFL.txt`.
34
+
35
+ ---
36
+
37
+ Tokmon's marketing site adapts the page structure and interaction grammar of
38
+ [T3 Code](https://github.com/pingdotgg/t3code), licensed under the MIT License.
39
+ Tokmon uses its own product copy, screenshots, provider artwork, claims, and
40
+ visual theme.
41
+
42
+ MIT License
43
+
44
+ Copyright (c) 2026 T3 Tools Inc.
45
+
46
+ Permission is hereby granted, free of charge, to any person obtaining a copy
47
+ of this software and associated documentation files (the "Software"), to deal
48
+ in the Software without restriction, including without limitation the rights
49
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
50
+ copies of the Software, and to permit persons to whom the Software is
51
+ furnished to do so, subject to the following conditions:
52
+
53
+ The above copyright notice and this permission notice shall be included in all
54
+ copies or substantial portions of the Software.
55
+
56
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
57
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
58
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
59
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
60
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
61
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
62
+ SOFTWARE.