tokmon 0.12.6 → 0.14.0

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 (3) hide show
  1. package/README.md +120 -51
  2. package/dist/cli.js +4199 -1264
  3. package/package.json +6 -2
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # tokmon
2
2
 
3
- Terminal dashboard for Claude Code usage, costs, and rate limits.
3
+ Terminal dashboard for **Claude Code**, **Codex**, **Cursor**, **Copilot**, **opencode**, **pi**, **Antigravity**, and **Gemini** — usage, costs, and rate limits, all in one place.
4
4
 
5
- Built with [Ink](https://github.com/vadimdemedes/ink), TypeScript.
5
+ Built with [Ink](https://github.com/vadimdemedes/ink) and TypeScript.
6
6
 
7
7
  ![tokmon dashboard](screenshot.png)
8
8
 
@@ -24,106 +24,175 @@ pnpm dlx tokmon
24
24
  npm install -g tokmon
25
25
  ```
26
26
 
27
- Then just run `tokmon`. Press `q` to quit.
27
+ Then run `tokmon`. On first launch you'll pick which providers to track; press `q` to quit any time.
28
28
 
29
- ## Options
29
+ ## Providers
30
+
31
+ **Usage providers** — full cost & token history (Today / Week / Month, sparkline, per-model table):
32
+
33
+ | Provider | What it reads | What you get |
34
+ |----------|---------------|--------------|
35
+ | **Claude** | `~/.claude/projects/**/*.jsonl` | Cost & token history, plan (e.g. Max 20x), live 5h / weekly / Sonnet limits |
36
+ | **Codex** | `~/.codex/sessions/**/rollout-*.jsonl` | Cost & token history, plan, live 5h / weekly limits, credit balance |
37
+ | **opencode** | `~/.local/share/opencode/opencode.db` | Cost & token history across whatever providers opencode routes to (uses its own recorded cost) |
38
+ | **pi** | `~/.pi/agent/sessions/**/*.jsonl` | Cost & token history (uses pi's own recorded cost) |
39
+
40
+ **Billing / quota providers** — plan + live quota or spend (no local token history):
41
+
42
+ | Provider | What it reads | What you get |
43
+ |----------|---------------|--------------|
44
+ | **Cursor** | `state.vscdb` + local tracking DBs | Plan, current-period spend, on-demand caps, per-model spend, AI-code activity |
45
+ | **Copilot** | GitHub token (gh / VS Code) | Plan + premium-request & chat quota |
46
+ | **Antigravity** | its `state.vscdb` OAuth → Google Cloud Code | Plan + per-pool (Gemini Pro/Flash/Claude) quota |
47
+ | **Gemini** | `~/.gemini/oauth_creds.json` → Google Cloud Code | Plan + quota (re-run `gemini` to refresh an expired token) |
48
+
49
+ 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.
50
+
51
+ 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.
52
+
53
+ ## Views
54
+
55
+ ### Dashboard
56
+
57
+ A responsive grid of provider cards (or one card at a time — see **Dashboard layout** in settings). Each card shows:
58
+
59
+ - **Today / This Week / This Month** — cost and token summaries
60
+ - **Burn rate** — current $/hr
61
+ - **Cache saved** — what caching has saved you
62
+ - **Rate limits** — live utilization bars with reset countdowns
63
+ - **Sparkline** — recent daily activity
64
+
65
+ 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.
66
+
67
+ A **Peak / Off-Peak** badge appears in the header (Claude only), fetched from [promoclock.co](https://promoclock.co) — peak hours drain session limits faster.
68
+
69
+ ### Table
70
+
71
+ Per-provider history with a provider selector (`p` / `P`), search (`/`), and sorting (`o`).
72
+
73
+ For **Claude / Codex** — 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:
30
74
 
31
75
  ```
32
- -i, --interval <seconds> Refresh interval in seconds (default: 2)
33
- -h, --help Show help
76
+ ▸ Apr 7 haiku-4-5, op~ 7.6K 487.0K 10.1M 1.1B $603.89
77
+ ├─ opus-4-6 7.5K 485.0K 10.0M 1.1B $601.50
78
+ └─ haiku-4-5 100 2.0K 100K 5.0M $2.39
34
79
  ```
35
80
 
81
+ For **Cursor** — a per-model spend table (cost, request count, share of total, all-time), sourced from Cursor's local conversation data.
82
+
36
83
  ## Keybindings
37
84
 
38
85
  ### Global
39
86
 
40
87
  | Key | Action |
41
88
  |-----|--------|
42
- | `Tab` | Cycle between Dashboard and Table |
43
- | `1` `2` | Jump to Dashboard / Table |
89
+ | `Tab` | Switch between Dashboard and Table |
90
+ | `←` `→` | (Dashboard) switch between Dashboard and Table |
91
+ | scroll / `↑` `↓` / `[` `]` | (Dashboard) move between pages when paginated |
92
+ | `a` `A` | Cycle account focus forward / back |
93
+ | `0`–`9` | Jump to an account focus slot |
44
94
  | `s` | Open settings |
45
95
  | `q` | Quit |
46
96
 
47
- ### Table View
97
+ ### Table
48
98
 
49
99
  | Key | Action |
50
100
  |-----|--------|
51
- | `d` `w` `m` | Switch to Daily / Weekly / Monthly |
52
- | `←` `→` | Cycle sub-view |
53
- | `↑` `↓` | Move cursor / navigate rows |
54
- | `Enter` | Expand row — per-model cost breakdown |
55
- | `Esc` | Collapse expanded row |
56
- | `o` | Cycle sort: date ↑, date ↓, cost ↑, cost ↓ |
57
- | `g` | Jump to top |
58
- | `G` | Jump to bottom |
101
+ | `p` `P` | Cycle provider forward / back |
102
+ | `/` | Search (Esc clears) |
103
+ | `o` | Cycle sort |
104
+ | `d` `w` `m` | Daily / Weekly / Monthly *(Claude/Codex)* |
105
+ | `←` `→` | Cycle period *(Claude/Codex)* |
106
+ | `Enter` | Expand row — per-model breakdown *(Claude/Codex)* |
107
+ | `↑` `↓` | Move cursor |
108
+ | `g` `G` | Jump to top / bottom |
59
109
  | `PgUp` `PgDn` | Page scroll |
110
+ | `Esc` | Clear search, then collapse row |
60
111
 
61
112
  ### Settings
62
113
 
63
114
  | Key | Action |
64
115
  |-----|--------|
65
- | `↑` `↓` | Select option |
66
- | `←` `→` | Adjust value |
116
+ | `↑` `↓` | Select row |
117
+ | `←` `→` | Adjust value / toggle |
118
+ | `Enter` | Edit / confirm |
119
+ | `Space` | Toggle provider · set account active |
120
+ | `Shift`+`↑` `↓` | Reorder accounts |
121
+ | `d` `x` | Delete account |
67
122
  | `s` / `Esc` | Close |
68
123
 
69
- ## Views
124
+ ## Settings
70
125
 
71
- ### Dashboard
126
+ Press `s` to open.
72
127
 
73
- - **Today / This Week / This Month** — cost and token summaries
74
- - **Burn rate** — current $/hr
75
- - **Rate Limits** — real-time session (5h), weekly (7d), and Sonnet utilization with reset countdowns, fetched from Anthropic's OAuth API
76
- - **Peak / Off-Peak badge** — shown in the header, fetched from [promoclock.co](https://promoclock.co) (peak hours drain session limits faster)
128
+ **General**
77
129
 
78
- ### Table
130
+ - **Refresh interval** — dashboard poll rate (default: 2s)
131
+ - **Billing poll** — rate-limit / spend API poll rate (default: 5m, min 1m to avoid rate limiting)
132
+ - **Clear screen** — clears the terminal on launch (like `watch`)
133
+ - **Timezone** — IANA timezone, or `System`
134
+ - **Dashboard layout** — `grid` (all providers at once) or `single` (one at a time)
135
+ - **Default focus** — start on `all`, or remember your `last` focused account
136
+ - **ASCII glyphs** — `auto` (detect), `on` (force ASCII), or `off` (force Unicode)
79
137
 
80
- Interactive table with 3 sub-views:
138
+ **Providers** — toggle each provider on or off.
81
139
 
82
- - **Daily** — per-day breakdown (6 months of history)
83
- - **Weekly** — grouped by ISO week
84
- - **Monthly** — grouped by month
140
+ **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.
85
141
 
86
- Each row shows models used, input/output/cache tokens, and cost. Press `Enter` on any row to expand a per-model breakdown:
142
+ ## Options
87
143
 
88
144
  ```
89
- ▸ Apr 7 haiku-4-5, op~ 7.6K 487.0K 10.1M 1.1B $603.89
90
- ├─ opus-4-6 7.5K 485.0K 10.0M 1.1B $601.50
91
- └─ haiku-4-5 100 2.0K 100K 5.0M $2.39
145
+ -i, --interval <seconds> Refresh interval in seconds (default: from config, or 2)
146
+ --ascii Force ASCII glyphs (also: TOKMON_ASCII=1)
147
+ --no-ascii Force Unicode glyphs
148
+ -h, --help Show help
92
149
  ```
93
150
 
94
- Sort by date or cost with `o`.
151
+ 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.
95
152
 
96
- ## Settings
153
+ ## Files
97
154
 
98
- Press `s` to open. Persisted to `~/.config/tokmon/config.json` (macOS/Linux) or `%APPDATA%\tokmon\config.json` (Windows).
155
+ | Path | Purpose |
156
+ |------|---------|
157
+ | `~/.config/tokmon/config.json` (macOS/Linux) | Settings |
158
+ | `%APPDATA%\tokmon\config.json` (Windows) | Settings |
159
+ | `~/Library/Caches/tokmon` (macOS) | Parse cache |
160
+ | `~/.cache/tokmon` (Linux, or `$XDG_CACHE_HOME`) | Parse cache |
161
+ | `%LOCALAPPDATA%\tokmon\cache` (Windows) | Parse cache |
99
162
 
100
- - **Refresh interval** — dashboard poll rate (default: 2s)
101
- - **Billing poll** — rate limits API poll rate (default: 5m, min 1m to avoid 429s)
102
- - **Clear screen** — clears terminal on launch (like `watch`)
163
+ Config writes are atomic (temp + rename) so a crash mid-save can't corrupt the file.
164
+
165
+ ## Privacy
166
+
167
+ tokmon runs entirely on your machine and reads everything **read-only**:
168
+
169
+ - It never writes to any provider's data — SQLite databases (Cursor, opencode) are opened strictly read-only.
170
+ - 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.
171
+ - The only outbound requests are to those provider APIs and the optional peak-pricing clock.
103
172
 
104
173
  ## How It Works
105
174
 
106
- - Reads Claude Code's JSONL session logs from `~/.claude/projects/`
107
- - Calculates costs using Claude model pricing (Opus, Sonnet, Haiku)
108
- - Caches file reads by mtime — subsequent refreshes are near-instant
109
- - Dashboard loads current month only (fast). Table loads 6 months lazily.
110
- - Rate limits fetched from Anthropic OAuth API every 2 minutes (token from macOS Keychain)
175
+ - Parses local CLI session logs and aggregates cost/token usage per day, week, and month.
176
+ - A persistent parse cache keyed by file **mtime + size** makes repeat launches near-instant; edited or deleted files are re-read automatically.
177
+ - Dashboard summaries and table history load independently, so the UI stays responsive on large histories.
178
+ - Rate limits and spend are fetched from each provider's API on the billing poll interval.
111
179
 
112
180
  Cross-platform: macOS, Linux, Windows.
113
181
 
182
+ ## Requirements
183
+
184
+ - Node.js 20+ (**24+ recommended**)
185
+ - The CLIs/apps you want to track
186
+ - **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).
187
+
114
188
  ## CI/CD
115
189
 
116
190
  Publishes to npm and GitHub Packages via GitHub Actions on version tags:
117
191
 
118
192
  ```bash
119
- git tag v0.7.0 && git push --tags
193
+ git tag v0.14.0 && git push --tags
120
194
  ```
121
195
 
122
- ## Requirements
123
-
124
- - Node.js 20+
125
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
126
-
127
196
  ## Author
128
197
 
129
198
  By [David Ilie](https://davidilie.com)