tokmon 0.12.5 → 0.13.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.
- package/README.md +102 -51
- package/dist/cli.js +2588 -1254
- 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**, and **Cursor** — usage, costs, and rate limits, all in one place.
|
|
4
4
|
|
|
5
|
-
Built with [Ink](https://github.com/vadimdemedes/ink)
|
|
5
|
+
Built with [Ink](https://github.com/vadimdemedes/ink) and TypeScript.
|
|
6
6
|
|
|
7
7
|
|
|
8
8
|
|
|
@@ -24,106 +24,157 @@ pnpm dlx tokmon
|
|
|
24
24
|
npm install -g tokmon
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
Then
|
|
27
|
+
Then run `tokmon`. On first launch you'll pick which providers to track; press `q` to quit any time.
|
|
28
28
|
|
|
29
|
-
##
|
|
29
|
+
## Providers
|
|
30
|
+
|
|
31
|
+
| Provider | What it reads | What you get |
|
|
32
|
+
|----------|---------------|--------------|
|
|
33
|
+
| **Claude** | `~/.claude/projects/**/*.jsonl` session logs | Cost & token history, live 5h / weekly / Sonnet rate limits |
|
|
34
|
+
| **Codex** | `~/.codex/sessions/**/rollout-*.jsonl` | Cost & token history, live 5h / weekly limits, credit balance |
|
|
35
|
+
| **Cursor** | `state.vscdb` + local tracking DBs (via `sqlite3`) | Plan, current-period spend, on-demand caps, per-model spend, AI-code activity |
|
|
36
|
+
|
|
37
|
+
tokmon auto-detects which tools are installed (on `PATH` or as a desktop app) and offers them during onboarding. You can always enable a provider manually in settings, even if it isn't detected.
|
|
38
|
+
|
|
39
|
+
Costs use each model's published pricing. **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.
|
|
40
|
+
|
|
41
|
+
## Views
|
|
42
|
+
|
|
43
|
+
### Dashboard
|
|
44
|
+
|
|
45
|
+
A responsive grid of provider cards (or one card at a time — see **Dashboard layout** in settings). Each card shows:
|
|
46
|
+
|
|
47
|
+
- **Today / This Week / This Month** — cost and token summaries
|
|
48
|
+
- **Burn rate** — current $/hr
|
|
49
|
+
- **Cache saved** — what caching has saved you
|
|
50
|
+
- **Rate limits** — live utilization bars with reset countdowns
|
|
51
|
+
- **Sparkline** — recent daily activity
|
|
52
|
+
|
|
53
|
+
When you track more than one account, a focus strip lets you view **All** together or zoom into a single account.
|
|
54
|
+
|
|
55
|
+
A **Peak / Off-Peak** badge appears in the header (Claude only), fetched from [promoclock.co](https://promoclock.co) — peak hours drain session limits faster.
|
|
56
|
+
|
|
57
|
+
### Table
|
|
58
|
+
|
|
59
|
+
Per-provider history with a provider selector (`p` / `P`), search (`/`), and sorting (`o`).
|
|
60
|
+
|
|
61
|
+
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
62
|
|
|
31
63
|
```
|
|
32
|
-
-
|
|
33
|
-
-
|
|
64
|
+
▸ Apr 7 haiku-4-5, op~ 7.6K 487.0K 10.1M 1.1B $603.89
|
|
65
|
+
├─ opus-4-6 7.5K 485.0K 10.0M 1.1B $601.50
|
|
66
|
+
└─ haiku-4-5 100 2.0K 100K 5.0M $2.39
|
|
34
67
|
```
|
|
35
68
|
|
|
69
|
+
For **Cursor** — a per-model spend table (cost, request count, share of total, all-time), sourced from Cursor's local conversation data.
|
|
70
|
+
|
|
36
71
|
## Keybindings
|
|
37
72
|
|
|
38
73
|
### Global
|
|
39
74
|
|
|
40
75
|
| Key | Action |
|
|
41
76
|
|-----|--------|
|
|
42
|
-
| `Tab` |
|
|
43
|
-
|
|
|
77
|
+
| `Tab` | Switch between Dashboard and Table |
|
|
78
|
+
| `←` `→` | (Dashboard) switch between Dashboard and Table |
|
|
79
|
+
| `a` `A` | Cycle account focus forward / back |
|
|
80
|
+
| `0`–`9` | Jump to an account focus slot |
|
|
44
81
|
| `s` | Open settings |
|
|
45
82
|
| `q` | Quit |
|
|
46
83
|
|
|
47
|
-
### Table
|
|
84
|
+
### Table
|
|
48
85
|
|
|
49
86
|
| Key | Action |
|
|
50
87
|
|-----|--------|
|
|
51
|
-
| `
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
| `
|
|
55
|
-
|
|
|
56
|
-
| `
|
|
57
|
-
|
|
|
58
|
-
| `G` | Jump to bottom |
|
|
88
|
+
| `p` `P` | Cycle provider forward / back |
|
|
89
|
+
| `/` | Search (Esc clears) |
|
|
90
|
+
| `o` | Cycle sort |
|
|
91
|
+
| `d` `w` `m` | Daily / Weekly / Monthly *(Claude/Codex)* |
|
|
92
|
+
| `←` `→` | Cycle period *(Claude/Codex)* |
|
|
93
|
+
| `Enter` | Expand row — per-model breakdown *(Claude/Codex)* |
|
|
94
|
+
| `↑` `↓` | Move cursor |
|
|
95
|
+
| `g` `G` | Jump to top / bottom |
|
|
59
96
|
| `PgUp` `PgDn` | Page scroll |
|
|
97
|
+
| `Esc` | Clear search, then collapse row |
|
|
60
98
|
|
|
61
99
|
### Settings
|
|
62
100
|
|
|
63
101
|
| Key | Action |
|
|
64
102
|
|-----|--------|
|
|
65
|
-
| `↑` `↓` | Select
|
|
66
|
-
| `←` `→` | Adjust value |
|
|
103
|
+
| `↑` `↓` | Select row |
|
|
104
|
+
| `←` `→` | Adjust value / toggle |
|
|
105
|
+
| `Enter` | Edit / confirm |
|
|
106
|
+
| `Space` | Toggle provider · set account active |
|
|
107
|
+
| `Shift`+`↑` `↓` | Reorder accounts |
|
|
108
|
+
| `d` `x` | Delete account |
|
|
67
109
|
| `s` / `Esc` | Close |
|
|
68
110
|
|
|
69
|
-
##
|
|
111
|
+
## Settings
|
|
70
112
|
|
|
71
|
-
|
|
113
|
+
Press `s` to open.
|
|
72
114
|
|
|
73
|
-
|
|
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)
|
|
115
|
+
**General**
|
|
77
116
|
|
|
78
|
-
|
|
117
|
+
- **Refresh interval** — dashboard poll rate (default: 2s)
|
|
118
|
+
- **Billing poll** — rate-limit / spend API poll rate (default: 5m, min 1m to avoid rate limiting)
|
|
119
|
+
- **Clear screen** — clears the terminal on launch (like `watch`)
|
|
120
|
+
- **Timezone** — IANA timezone, or `System`
|
|
121
|
+
- **Dashboard layout** — `grid` (all providers at once) or `single` (one at a time)
|
|
122
|
+
- **Default focus** — start on `all`, or remember your `last` focused account
|
|
79
123
|
|
|
80
|
-
|
|
124
|
+
**Providers** — toggle each provider on or off.
|
|
81
125
|
|
|
82
|
-
|
|
83
|
-
- **Weekly** — grouped by ISO week
|
|
84
|
-
- **Monthly** — grouped by month
|
|
126
|
+
**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
127
|
|
|
86
|
-
|
|
128
|
+
## Options
|
|
87
129
|
|
|
88
130
|
```
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
└─ haiku-4-5 100 2.0K 100K 5.0M $2.39
|
|
131
|
+
-i, --interval <seconds> Refresh interval in seconds (default: from config, or 2)
|
|
132
|
+
-h, --help Show help
|
|
92
133
|
```
|
|
93
134
|
|
|
94
|
-
|
|
135
|
+
## Files
|
|
95
136
|
|
|
96
|
-
|
|
137
|
+
| Path | Purpose |
|
|
138
|
+
|------|---------|
|
|
139
|
+
| `~/.config/tokmon/config.json` (macOS/Linux) | Settings |
|
|
140
|
+
| `%APPDATA%\tokmon\config.json` (Windows) | Settings |
|
|
141
|
+
| `~/Library/Caches/tokmon` (macOS) | Parse cache |
|
|
142
|
+
| `~/.cache/tokmon` (Linux, or `$XDG_CACHE_HOME`) | Parse cache |
|
|
143
|
+
| `%LOCALAPPDATA%\tokmon\cache` (Windows) | Parse cache |
|
|
97
144
|
|
|
98
|
-
|
|
145
|
+
Config writes are atomic (temp + rename) so a crash mid-save can't corrupt the file.
|
|
99
146
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
147
|
+
## Privacy
|
|
148
|
+
|
|
149
|
+
tokmon runs entirely on your machine and reads everything **read-only**:
|
|
150
|
+
|
|
151
|
+
- It never writes to any provider's data (Cursor's `state.vscdb` and tracking DBs are opened with `sqlite3 -readonly`).
|
|
152
|
+
- Credentials are read only to call each provider's **own official API** (Anthropic, ChatGPT backend, Cursor) for *your own* usage. Tokens are never logged, displayed, or sent anywhere else.
|
|
153
|
+
- The only outbound requests are to those provider APIs and the optional peak-pricing clock.
|
|
103
154
|
|
|
104
155
|
## How It Works
|
|
105
156
|
|
|
106
|
-
-
|
|
107
|
-
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
- Rate limits fetched from Anthropic OAuth API every 2 minutes (token from macOS Keychain)
|
|
157
|
+
- Parses local CLI session logs and aggregates cost/token usage per day, week, and month.
|
|
158
|
+
- A persistent parse cache keyed by file **mtime + size** makes repeat launches near-instant; edited or deleted files are re-read automatically.
|
|
159
|
+
- Dashboard summaries and table history load independently, so the UI stays responsive on large histories.
|
|
160
|
+
- Rate limits and spend are fetched from each provider's API on the billing poll interval.
|
|
111
161
|
|
|
112
162
|
Cross-platform: macOS, Linux, Windows.
|
|
113
163
|
|
|
164
|
+
## Requirements
|
|
165
|
+
|
|
166
|
+
- Node.js 20+
|
|
167
|
+
- The CLIs/apps you want to track ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Cursor](https://cursor.com))
|
|
168
|
+
- `sqlite3` on your `PATH` — required for Cursor (preinstalled on macOS; `apt install sqlite3` / `winget install sqlite` elsewhere)
|
|
169
|
+
|
|
114
170
|
## CI/CD
|
|
115
171
|
|
|
116
172
|
Publishes to npm and GitHub Packages via GitHub Actions on version tags:
|
|
117
173
|
|
|
118
174
|
```bash
|
|
119
|
-
git tag v0.
|
|
175
|
+
git tag v0.13.0 && git push --tags
|
|
120
176
|
```
|
|
121
177
|
|
|
122
|
-
## Requirements
|
|
123
|
-
|
|
124
|
-
- Node.js 20+
|
|
125
|
-
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
|
|
126
|
-
|
|
127
178
|
## Author
|
|
128
179
|
|
|
129
180
|
By [David Ilie](https://davidilie.com)
|