tokmon 0.28.2 → 0.28.4
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.
- package/README.md +156 -234
- package/THIRD_PARTY_NOTICES.md +62 -0
- package/dist/{bootstrap-ink-IMT3S5HU.js → bootstrap-ink-WG4WG3R2.js} +1579 -1136
- package/dist/chunk-5B3XCEMC.js +294 -0
- package/dist/chunk-7CH6S7BR.js +447 -0
- package/dist/{chunk-LCAHTRGP.js → chunk-CFKUZCMB.js} +56 -29
- package/dist/{chunk-LKYOWBD4.js → chunk-FLANGRI6.js} +21 -42
- package/dist/chunk-HNWEJ6MS.js +1094 -0
- package/dist/{chunk-WUK3MQUB.js → chunk-JZSZEHVD.js} +167 -10
- package/dist/{chunk-6ZEW2M6P.js → chunk-P57DVFNH.js} +125 -25
- package/dist/chunk-TN6V7XSL.js +512 -0
- package/dist/chunk-UYPDMVW5.js +21 -0
- package/dist/{cli-command-DCENRCO3.js → cli-command-I4GRR3MF.js} +249 -15
- package/dist/cli.js +6 -6
- package/dist/{config-HXFJTNLM.js → config-3DGZ47F7.js} +23 -3
- package/dist/daemon-ZXV3V5CS.js +384 -0
- package/dist/daemon-handle-G4OGPFR3.js +11 -0
- package/dist/server-EPSH52DR.js +12 -0
- package/dist/web/assets/{Area-CMXvOw33.js → Area-stRnp8Km.js} +1 -1
- package/dist/web/assets/analytics-moZZt9L_.js +2 -0
- package/dist/web/assets/breakdown-km9w7myU.js +4 -0
- package/dist/web/assets/button-DrX04Cc2.js +1 -0
- package/dist/web/assets/{chart-cZoLgpmG.js → chart-D0CtuL2k.js} +1 -1
- package/dist/web/assets/explore-B11uNJV1.js +22 -0
- package/dist/web/assets/index-RDhXsCNG.js +83 -0
- package/dist/web/assets/index-ZmOS8p9O.css +1 -0
- package/dist/web/assets/models-DYbZnY34.js +2 -0
- package/dist/web/assets/overview-CruICbfJ.js +2 -0
- package/dist/web/assets/panel-xckM3_GC.js +1 -0
- package/dist/web/assets/settings-sheet-G-BTSIF6.js +1 -0
- package/dist/web/assets/share-sheet-weIdd4DW.js +2 -0
- package/dist/web/assets/timeline-BHgniliZ.js +1 -0
- package/dist/web/index.html +30 -4
- package/package.json +13 -4
- package/site/THIRD_PARTY_NOTICES.md +83 -0
- package/site/public/fonts/OFL.txt +93 -0
- package/dist/chunk-44ZSQEOS.js +0 -299
- package/dist/chunk-HP5UZCXP.js +0 -436
- package/dist/chunk-J3JW3RFP.js +0 -196
- package/dist/chunk-M7XMV36F.js +0 -275
- package/dist/daemon-6Y4O7NXS.js +0 -241
- package/dist/daemon-handle-GVCYVDPO.js +0 -10
- package/dist/server-GXXOWUVZ.js +0 -11
- package/dist/web/assets/analytics-DqdZXOJL.js +0 -2
- package/dist/web/assets/breakdown-kOSSJ3mI.js +0 -4
- package/dist/web/assets/explore-vcsM8K9I.js +0 -22
- package/dist/web/assets/index-BErCXT7f.css +0 -1
- package/dist/web/assets/index-DH3dOnbg.js +0 -83
- package/dist/web/assets/models-B5ikm83_.js +0 -2
- package/dist/web/assets/overview-DD1kP8CP.js +0 -2
- package/dist/web/assets/panel-DTQBwExW.js +0 -1
- package/dist/web/assets/primitives-C36qJlA2.js +0 -1
- package/dist/web/assets/settings-sheet-_i2zTQjf.js +0 -1
- package/dist/web/assets/share-sheet-BLHmrFbm.js +0 -2
- package/dist/web/assets/timeline-B4uG-Emo.js +0 -1
- package/dist/web/assets/use-dialog-trap-bfaXEMz9.js +0 -1
package/README.md
CHANGED
|
@@ -1,286 +1,208 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|

|
|
8
26
|
|
|
9
|
-
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
```
|
|
32
|
+
It currently understands Claude Code, Codex, Cursor, Copilot, opencode, pi,
|
|
33
|
+
Antigravity, Gemini, and Grok.
|
|
14
34
|
|
|
15
|
-
|
|
35
|
+
## Install
|
|
16
36
|
|
|
17
|
-
|
|
18
|
-
pnpm dlx tokmon
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
### Global Install
|
|
37
|
+
Run the terminal dashboard without installing anything:
|
|
22
38
|
|
|
23
39
|
```bash
|
|
24
|
-
|
|
40
|
+
npx tokmon
|
|
25
41
|
```
|
|
26
42
|
|
|
27
|
-
|
|
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
|
-
|
|
35
|
-
tokmon
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
+
## Three ways to use it
|
|
101
58
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
+

|
|
111
70
|
|
|
112
|
-
|
|
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
|

|
|
115
76
|
|
|
116
|
-
|
|
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
|
-

|
|
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
|
-

|
|
127
|
-
|
|
128
|
-
### Explore
|
|
129
|
-
|
|
130
|
-
The full daily / weekly / monthly table — searchable, sortable on every column, with expandable per-model breakdowns.
|
|
131
|
-
|
|
132
|
-

|
|
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
|
-
|
|
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
|
-
|
|
82
|
+
### Usage and cost
|
|
181
83
|
|
|
182
|
-
|
|
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
|
-
|
|
93
|
+
### Quota and billing
|
|
185
94
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
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
|
-
|
|
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
|
-
|
|
105
|
+
## Useful commands
|
|
201
106
|
|
|
202
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
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
|
-
|
|
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
|
-
|
|
191
|
+
Read [the development guide](docs/development.md) before changing daemon
|
|
192
|
+
ownership, shared contracts, packaging paths, or release workflows.
|
|
275
193
|
|
|
276
|
-
|
|
277
|
-
git tag v0.14.0 && git push --tags
|
|
278
|
-
```
|
|
194
|
+
## Acknowledgements
|
|
279
195
|
|
|
280
|
-
|
|
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
|
-
|
|
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.
|