exe-watcher 0.2.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 (5) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +276 -0
  3. package/dist/cli.js +7233 -0
  4. package/dist/cli.js.map +1 -0
  5. package/package.json +58 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AgentSeal (original codeburn)
4
+ Copyright (c) 2026 Exe AI (exe-watcher fork)
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,276 @@
1
+ <p align="center">
2
+ <img src="https://cdn.jsdelivr.net/gh/AskExe/exe-watcher@main/assets/owl-header.png" alt="WATCHER" width="520" />
3
+ </p>
4
+
5
+ <p align="center"><strong>The fuel gauge for your AI coding day — by <a href="https://github.com/AskExe">Exe AI</a>.</strong></p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/exe-watcher"><img src="https://img.shields.io/npm/v/exe-watcher.svg" alt="npm version" /></a>
9
+ <a href="https://www.npmjs.com/package/exe-watcher"><img src="https://img.shields.io/npm/dt/exe-watcher.svg" alt="total downloads" /></a>
10
+ <a href="https://github.com/AskExe/exe-watcher/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/exe-watcher.svg" alt="license" /></a>
11
+ <a href="https://github.com/AskExe/exe-watcher"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="node version" /></a>
12
+ <a href="https://discord.gg/pJ2DMWvtAx"><img src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <img src="https://raw.githubusercontent.com/AskExe/exe-watcher/main/assets/dashboard.jpg" alt="Watcher TUI dashboard" width="620" />
17
+ </p>
18
+
19
+ You're spending real money on AI coding tools every day. Watcher shows you exactly where it goes — cost, tokens, models, projects, and whether the AI is getting it right the first time or burning through retry loops. One command, zero cloud, everything local.
20
+
21
+ ```bash
22
+ npm install -g exe-watcher
23
+ ```
24
+
25
+ ---
26
+
27
+ ## What you get
28
+
29
+ **Dashboard** — Interactive TUI with gradient charts, responsive panels, keyboard navigation. Breaks down spend by day, project, model, activity type, tools, MCP servers, and shell commands. Auto-refreshes every 30 seconds.
30
+
31
+ **One-shot rate** — For every category that involves edits, Watcher detects edit/test/fix retry cycles and shows you the percentage of turns where the AI got it right on the first try. Coding at 90% means 9 out of 10 edits landed without retries.
32
+
33
+ **Optimize** — Scans your sessions and `~/.claude/` config for waste: re-read files, low read:edit ratios, uncapped bash output, unused MCP servers, ghost agents, bloated CLAUDE.md files. Hands back exact, copy-paste fixes. Grades your setup A through F.
34
+
35
+ **Compare** — Side-by-side model comparison on your own data. One-shot rate, retry rate, cost per edit, cache hit rate, delegation style, fast mode usage — broken down by task category.
36
+
37
+ **Menubar** — Native macOS app showing today's cost in your menu bar. Period switcher, trend/forecast/pulse insights, activity breakdowns, per-project spend, and AI employee tracking. Launches at login, one command to install.
38
+
39
+ **Export** — CSV and JSON export for any time period. Pipe `--format json` output to `jq` for scripting.
40
+
41
+ ---
42
+
43
+ ## Supported tools
44
+
45
+ | Tool | Data source | Notes |
46
+ |------|-------------|-------|
47
+ | **Claude Code** | `~/.claude/projects/` | Full support |
48
+ | **Claude Desktop** | `~/Library/Application Support/Claude/local-agent-mode-sessions/` | Full support |
49
+ | **Codex** (OpenAI) | `~/.codex/sessions/` | Full support |
50
+ | **Cursor** | SQLite (`state.vscdb`) | Auto mode estimated at Sonnet pricing |
51
+ | **cursor-agent** | CLI sessions | Full support |
52
+ | **OpenCode** | SQLite (`~/.local/share/opencode/`) | Subtask sessions excluded |
53
+ | **Pi** | `~/.pi/agent/sessions/` | Full support |
54
+ | **OMP** (Oh My Pi) | `~/.omp/agent/sessions/` | Full support |
55
+ | **GitHub Copilot** | `~/.copilot/session-state/` | Output tokens only |
56
+
57
+ Auto-detected. If multiple tools have data, press `p` in the dashboard to toggle. Provider plugin system makes adding new tools straightforward — see `src/providers/codex.ts` for the pattern.
58
+
59
+ ---
60
+
61
+ ## CLI reference
62
+
63
+ ```bash
64
+ # Dashboard
65
+ exe-watcher # interactive (default: 7 days)
66
+ exe-watcher today # today only
67
+ exe-watcher month # this month
68
+
69
+ # Reports
70
+ exe-watcher report -p 30days # rolling 30-day window
71
+ exe-watcher report -p all # everything on disk
72
+ exe-watcher report --from 2026-04-01 --to 2026-04-10
73
+ exe-watcher report --format json # structured JSON to stdout
74
+ exe-watcher status # compact one-liner (today + month)
75
+
76
+ # Filter
77
+ exe-watcher report --provider claude # single provider
78
+ exe-watcher report --project myapp # project substring match
79
+ exe-watcher report --exclude tests # exclude projects
80
+
81
+ # Tools
82
+ exe-watcher optimize # find waste, get fixes
83
+ exe-watcher optimize -p week # scope to last 7 days
84
+ exe-watcher compare # interactive model picker
85
+ exe-watcher export # CSV (today, 7d, 30d)
86
+ exe-watcher export -f json # JSON export
87
+ ```
88
+
89
+ **Dashboard keys:** `1`-`5` switch periods (Today / 7d / 30d / Month / All). `p` toggle providers. `c` compare mode. `o` optimize view. `q` quit.
90
+
91
+ **Flags work everywhere:** `--provider`, `--project`, `--exclude`, `--from`, `--to`, and `--format json` combine freely across all commands.
92
+
93
+ ---
94
+
95
+ ## Menubar app
96
+
97
+ <!-- Screenshot: native macOS menubar popover with gold/purple Exe Foundry Bold theme -->
98
+ <!-- To update: screencapture -w assets/menubar-v0.2.0.png (click the Watcher menubar icon) -->
99
+
100
+ ```bash
101
+ exe-watcher menubar
102
+ ```
103
+
104
+ Downloads, installs to `~/Applications`, and launches. Re-run with `--force` to reinstall. Native Swift + SwiftUI — silent background refresh every 60 seconds, no loading overlay. Pre-fetches all periods on launch so tab switching is instant. Launches at login automatically via macOS Login Items (toggleable in System Settings).
105
+
106
+ **v0.2.0 additions:**
107
+ - **Project Spend** — per-project cost breakdown across 24h / 7d / 30d
108
+ - **AI Employees** — collapsible section with Memory counts (+ growth) and Employee Spend (model-aware pricing per agent)
109
+ - **Dynamic provider tabs** — only shows providers that have actual spend data
110
+ - **Quit button** — clean shutdown from the footer bar
111
+ - **App icon** — gold EXE on dark purple (Exe Foundry Bold palette)
112
+
113
+ **Compact mode** drops decimals in the menubar (e.g. `$110` instead of `$110.20`):
114
+
115
+ ```bash
116
+ defaults write ExeWatcherMenubar ExeWatcherMenubarCompact -bool true
117
+ ```
118
+
119
+ ---
120
+
121
+ ## Configuration
122
+
123
+ ### Currency
124
+
125
+ ```bash
126
+ exe-watcher currency GBP # any ISO 4217 code (162 currencies)
127
+ exe-watcher currency --reset # back to USD
128
+ ```
129
+
130
+ Exchange rates from the European Central Bank via [Frankfurter](https://www.frankfurter.app/). Cached 24 hours. Applies everywhere: dashboard, menubar, exports.
131
+
132
+ ### Plans
133
+
134
+ Track spend against your subscription:
135
+
136
+ ```bash
137
+ exe-watcher plan set claude-max # $200/month
138
+ exe-watcher plan set claude-pro # $20/month
139
+ exe-watcher plan set cursor-pro # $20/month
140
+ exe-watcher plan set custom --monthly-usd 150 --provider claude
141
+ exe-watcher plan set none # disable
142
+ ```
143
+
144
+ ### Model aliases
145
+
146
+ If a model shows `$0.00`, your provider's model name doesn't match LiteLLM pricing data. Map it:
147
+
148
+ ```bash
149
+ exe-watcher model-alias "my-proxy-model" "claude-opus-4-6"
150
+ exe-watcher model-alias --list
151
+ exe-watcher model-alias --remove "my-proxy-model"
152
+ ```
153
+
154
+ Stored in `~/.config/exe-watcher/config.json`. User aliases override built-ins.
155
+
156
+ ---
157
+
158
+ ## Activity tracking
159
+
160
+ 6 categories classified from tool usage patterns and keywords. No LLM calls, fully deterministic.
161
+
162
+ | Category | What triggers it |
163
+ |----------|-----------------|
164
+ | Building | Edit, Write tools; "add", "create", "implement"; refactoring keywords |
165
+ | Debugging | Error/fix/bug keywords + tools |
166
+ | Testing | pytest, vitest, jest in Bash |
167
+ | Research | Read, Grep, WebSearch without edits; brainstorming; conversation |
168
+ | DevOps | git push/commit/merge; npm build, docker, deploy |
169
+ | Planning | EnterPlanMode, TaskCreate, Agent tool spawns |
170
+
171
+ ---
172
+
173
+ ## Reading the signals
174
+
175
+ | What you see | What it might mean |
176
+ |---|---|
177
+ | Cache hit < 80% | Unstable system prompt or caching not enabled |
178
+ | Lots of `Read` calls per session | Agent re-reading files, missing context |
179
+ | Low 1-shot rate (Coding 30%) | Agent struggling, retry loops |
180
+ | Opus on small turns | Overpowered model for simple tasks |
181
+ | Bash dominated by `git status`, `ls` | Agent exploring instead of executing |
182
+ | Conversation category dominant | Agent talking instead of doing |
183
+
184
+ Starting points, not verdicts. A single experimental session with 60% cache hit is fine. That same number across weeks of work is a config issue.
185
+
186
+ ---
187
+
188
+ ## How it works
189
+
190
+ Reads session data directly from disk. No wrapper, no proxy, no API keys needed. Pricing from [LiteLLM](https://github.com/BerriAI/litellm) (auto-cached 24h). Handles input, output, cache write, cache read, and web search costs. Deduplicates messages by API message ID (Claude), cumulative token cross-check (Codex), conversation/timestamp (Cursor), session+message ID (OpenCode), or responseId (Pi/OMP).
191
+
192
+ **Environment variables:**
193
+
194
+ | Variable | Description |
195
+ |----------|-------------|
196
+ | `CLAUDE_CONFIG_DIR` | Override Claude data directory (default: `~/.claude`) |
197
+ | `CODEX_HOME` | Override Codex data directory (default: `~/.codex`) |
198
+
199
+ ---
200
+
201
+ ## Contributing
202
+
203
+ Contributions welcome. The provider plugin system is the easiest entry point — each provider is a single file in `src/providers/`. See `src/providers/codex.ts` for the pattern.
204
+
205
+ ```
206
+ src/
207
+ cli.ts Entry point (Commander.js)
208
+ dashboard.tsx TUI (Ink — React for terminals)
209
+ parser.ts Session reader, dedup, date filter
210
+ models.ts LiteLLM pricing engine
211
+ classifier.ts Activity classifier (6 categories)
212
+ compare-stats.ts Model comparison engine
213
+ menubar-json.ts Menubar payload builder (agent spend, project spend)
214
+ export.ts CSV/JSON export
215
+ config.ts Config management
216
+ currency.ts Currency conversion
217
+ providers/ One file per supported tool
218
+ mac/ Native macOS menubar app (Swift + SwiftUI)
219
+ ```
220
+
221
+ ---
222
+
223
+ ## Exe OS integration
224
+
225
+ If [Exe OS](https://github.com/AskExe/exe-os) is installed, Watcher auto-detects it and shows a live **AI Employees** section in the menubar with two sub-panels:
226
+
227
+ - **Memory** — per-agent memory count with 24h / 7d / 30d growth columns
228
+ - **Employee Spend** — per-agent cost across 24h / 7d / 30d, using model-aware pricing (Opus, Sonnet, Haiku rates applied per-model from the daemon's token data)
229
+
230
+ No configuration needed. The section appears when exe-os is present and hides when it's not. The data pipeline: exe-os SessionStart hook maps Claude Code sessions to agents, the daemon computes `getAgentSpend()` with per-model pricing, writes `~/.exe-os/agent-stats.json` every 60 seconds, and Watcher reads this file — zero coupling, no auth, no direct database access.
231
+
232
+ ---
233
+
234
+ ## Origin & attribution
235
+
236
+ Watcher is forked from [codeburn](https://github.com/getagentseal/codeburn) by [AgentSeal](https://github.com/getagentseal) (MIT license). We forked rather than contributed upstream because our roadmap diverges significantly:
237
+
238
+ **What we changed:**
239
+ - Rebranded to Watcher with the Exe Foundry Bold design system (gold + purple palette, owl icon)
240
+ - Consolidated activity categories from 13 → 6 (less overlap, clearer signal)
241
+ - Fixed double-counting bugs in the menubar JSON pipeline (cache + fresh parse overlap)
242
+ - Performance: 7-day and 30-day queries from 2-5 seconds down to ~1 second (parse today only, use daily cache for history)
243
+ - Menubar: removed loading overlay entirely — silent background refresh, pre-fetched periods for instant tab switching
244
+ - Added exe-os agent memory and spend integration (auto-detected, model-aware pricing)
245
+ - Per-project spend breakdown in the menubar (24h / 7d / 30d)
246
+ - Launch at login via SMAppService, quit button, macOS app icon
247
+ - Dark mode forced on popover, dynamic provider tabs (no empty states)
248
+
249
+ **Why we forked:**
250
+ - We need full control over the data pipeline to integrate with exe-os (our AI employee operating system)
251
+ - Our classification model, provider support, and UI direction serve a different user base (AI-first teams running multi-agent workflows)
252
+ - MIT license allows this — we give full credit to AgentSeal for the foundation
253
+
254
+ Thank you to AgentSeal for building the original. If you just want a clean cost tracker without exe-os integration, [codeburn](https://github.com/getagentseal/codeburn) is excellent.
255
+
256
+ ---
257
+
258
+ ## Star History
259
+
260
+ <a href="https://www.star-history.com/?repos=AskExe%2Fexe-watcher&type=date&legend=top-left">
261
+ <picture>
262
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=AskExe/exe-watcher&type=date&theme=dark&legend=top-left" />
263
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=AskExe/exe-watcher&type=date&legend=top-left" />
264
+ <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=AskExe/exe-watcher&type=date&legend=top-left" />
265
+ </picture>
266
+ </a>
267
+
268
+ ---
269
+
270
+ ## License
271
+
272
+ MIT
273
+
274
+ ---
275
+
276
+ Built by [Exe AI](https://askexe.com). Forked from [codeburn](https://github.com/getagentseal/codeburn) by AgentSeal (MIT). Pricing data from [LiteLLM](https://github.com/BerriAI/litellm). Exchange rates from [Frankfurter](https://www.frankfurter.app/).