cursor-usage-tracker 1.17.0 → 1.18.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 +51 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -73,6 +73,7 @@ Developer uses Cursor → API collects data hourly → Engine detects anomaly
|
|
|
73
73
|
| Someone's daily spend spikes | `Alice: daily spend spiked to $214 (4.2x her 7-day avg of $51)` → Slack alert |
|
|
74
74
|
| A user's cycle spend is far above the team | `Bob: cycle spend $957 is 5.1x the team median ($188)` → Slack alert |
|
|
75
75
|
| A user is statistically far from the team | `Bob: daily spend $214 is 3.2σ above team mean ($42)` → Slack alert |
|
|
76
|
+
| Someone switches to an expensive model | `Bob: cost/request spiked to $1.45 (4.2x his avg of $0.34) — using opus-max` → Slack alert |
|
|
76
77
|
| A developer uses an expensive model when others don't | `Bob averaged $4.20/req on claude-opus-max (team median: $0.52 on sonnet)` → Model cost comparison table |
|
|
77
78
|
|
|
78
79
|
Every alert includes who, what model, how much, and a link to their dashboard page so you can investigate immediately.
|
|
@@ -83,11 +84,12 @@ Every alert includes who, what model, how much, and a link to their dashboard pa
|
|
|
83
84
|
|
|
84
85
|
### Three-Layer Anomaly Detection
|
|
85
86
|
|
|
86
|
-
| Layer
|
|
87
|
-
|
|
|
88
|
-
| **Thresholds**
|
|
89
|
-
| **Z-Score**
|
|
90
|
-
| **Trends**
|
|
87
|
+
| Layer | Method | What it catches |
|
|
88
|
+
| ------------------- | ------------- | -------------------------------------------------------------------------------------- |
|
|
89
|
+
| **Thresholds** | Static limits | Optional hard caps on spend, requests, or tokens (disabled by default) |
|
|
90
|
+
| **Z-Score** | Statistical | User daily spend 2.5+ standard deviations above team mean (active users only) |
|
|
91
|
+
| **Trends** | Spend-based | Daily spend spikes vs personal average, cycle spend outliers vs team median |
|
|
92
|
+
| **Expensive Model** | Cost/request | User's $/request jumps vs their own history (catches model switches like max-thinking) |
|
|
91
93
|
|
|
92
94
|
### Incident Lifecycle (MTTD / MTTI / MTTR)
|
|
93
95
|
|
|
@@ -127,7 +129,7 @@ Also supports **email alerts** via [Resend](https://resend.com) (one API key, no
|
|
|
127
129
|
| **Insights** | DAU chart, model adoption trends, model efficiency rankings (cost/precision), MCP tool usage, file extensions, client versions |
|
|
128
130
|
| **User Drilldown** | Per-user token timeline, model breakdown, feature usage, activity profile, anomaly history |
|
|
129
131
|
| **Anomalies** | Open incidents, MTTD/MTTI/MTTR metrics, full anomaly timeline |
|
|
130
|
-
| **Settings** | Detection thresholds,
|
|
132
|
+
| **Settings** | Detection thresholds, expensive model alerts, billing group management, HiBob CSV import, group export/import |
|
|
131
133
|
|
|
132
134
|
> For a detailed breakdown of every section, metric, badge, and chart, see [FEATURES.md](FEATURES.md).
|
|
133
135
|
|
|
@@ -295,7 +297,7 @@ Any platform that supports Docker + persistent volumes works:
|
|
|
295
297
|
- **[Render](https://render.com)** — use the deploy button above, or `render.yaml` in this repo
|
|
296
298
|
- **[Railway](https://railway.app)** — create a project from this repo, attach a volume at `/app/data`
|
|
297
299
|
|
|
298
|
-
> **
|
|
300
|
+
> **Serverless platforms** (Vercel, AWS Lambda, etc.) require replacing SQLite with an external database. The data layer is abstracted behind `src/lib/data/` — swap the implementation to use Postgres, Supabase, PlanetScale, or any other database. See [Architecture](#architecture) for details.
|
|
299
301
|
|
|
300
302
|
---
|
|
301
303
|
|
|
@@ -305,7 +307,7 @@ Any platform that supports Docker + persistent volumes works:
|
|
|
305
307
|
flowchart TB
|
|
306
308
|
APIs["Cursor Enterprise APIs\n/teams/members · /teams/spend · /teams/daily-usage-data\n/teams/filtered-usage-events · /teams/groups · /analytics/team/*"]
|
|
307
309
|
C["Collector (hourly)"]
|
|
308
|
-
DB[("SQLite
|
|
310
|
+
DB[("Database\n(SQLite default, swappable)")]
|
|
309
311
|
D["Detection Engine, 3 layers"]
|
|
310
312
|
AL["Alerts: Slack / Email"]
|
|
311
313
|
DA["Dashboard: Next.js"]
|
|
@@ -315,7 +317,7 @@ flowchart TB
|
|
|
315
317
|
D --> AL
|
|
316
318
|
```
|
|
317
319
|
|
|
318
|
-
|
|
320
|
+
The data layer is abstracted behind `src/lib/data/` — SQLite is the default (zero-config), but you can swap the implementation for Postgres, Supabase, or any database that fits your infrastructure.
|
|
319
321
|
|
|
320
322
|
---
|
|
321
323
|
|
|
@@ -323,56 +325,56 @@ flowchart TB
|
|
|
323
325
|
|
|
324
326
|
All detection thresholds are configurable via the Settings page or the API:
|
|
325
327
|
|
|
326
|
-
| Setting
|
|
327
|
-
|
|
|
328
|
-
| Max spend per cycle
|
|
329
|
-
| Max requests per day
|
|
330
|
-
| Max tokens per day
|
|
331
|
-
| Z-score multiplier
|
|
332
|
-
| Z-score window
|
|
333
|
-
| Spend spike multiplier
|
|
334
|
-
| Spend spike lookback
|
|
335
|
-
| Cycle outlier multiplier
|
|
328
|
+
| Setting | Default | What it does |
|
|
329
|
+
| ------------------------- | ------- | -------------------------------------------------------------- |
|
|
330
|
+
| Max spend per cycle | 0 (off) | Alert when a user exceeds this in a billing cycle |
|
|
331
|
+
| Max requests per day | 0 (off) | Alert on excessive daily request count |
|
|
332
|
+
| Max tokens per day | 0 (off) | Alert on excessive daily token consumption |
|
|
333
|
+
| Z-score multiplier | 2.5 | How many standard deviations above mean to flag (spend + reqs) |
|
|
334
|
+
| Z-score window | 7 days | Historical window for statistical comparison |
|
|
335
|
+
| Spend spike multiplier | 5.0x | Alert when today's spend > N× user's personal daily average |
|
|
336
|
+
| Spend spike lookback | 7 days | How many days of history to compare against |
|
|
337
|
+
| Cycle outlier multiplier | 10.0x | Alert when cycle spend > N× team median (active users only) |
|
|
338
|
+
| Cost/req spike multiplier | 3.0x | Alert when today's $/request > N× user's historical average |
|
|
339
|
+
| Cost/req min daily spend | $20 | Skip cost/req alerts for users below this daily spend |
|
|
336
340
|
|
|
337
341
|
---
|
|
338
342
|
|
|
339
|
-
|
|
340
|
-
|
|
343
|
+
## Settings
|
|
344
|
+
|
|
345
|
+
The Settings page (`/settings`) is where you configure detection behavior and manage your team structure. Everything is persisted locally and takes effect on the next detection run.
|
|
341
346
|
|
|
342
|
-
|
|
347
|
+
### Detection Thresholds
|
|
343
348
|
|
|
344
|
-
|
|
349
|
+
All anomaly detection parameters listed in [Configuration](#configuration) above are editable from the Settings page — static thresholds, z-score sensitivity, spend spike multipliers, and the expensive model detector. Set any value to 0 to disable that specific check.
|
|
345
350
|
|
|
346
|
-
|
|
351
|
+
### Billing Groups
|
|
347
352
|
|
|
348
|
-
|
|
353
|
+
Billing groups let you organize team members by department, team, or any structure that fits your org. The Team Overview page includes a group filter dropdown — select a group to instantly scope all stats, charts, and the members table to that subset.
|
|
349
354
|
|
|
350
355
|
From the Settings page you can:
|
|
351
356
|
|
|
352
357
|
- **View** all groups with member counts and per-group spend
|
|
353
|
-
- **Rename** groups to match your org structure
|
|
354
|
-
- **Reassign** members between groups
|
|
358
|
+
- **Rename** groups to match your org structure (displayed as `Parent > Team`)
|
|
359
|
+
- **Reassign** individual members between groups
|
|
355
360
|
- **Create** new groups manually
|
|
356
|
-
- **Search** across all members to find
|
|
361
|
+
- **Search** across all members to find and reassign anyone
|
|
362
|
+
- **Export** your current group mapping as a CSV backup
|
|
363
|
+
- **Import** a previously exported CSV to restore or transfer mappings between environments
|
|
357
364
|
|
|
358
|
-
|
|
365
|
+
### HiBob Import
|
|
359
366
|
|
|
360
|
-
|
|
361
|
-
<summary><strong>HiBob Import: sync your org structure from HiBob's People Directory</strong></summary>
|
|
367
|
+
For teams using [HiBob](https://www.hibob.com/) as their HR platform, the Settings page includes a dedicated **Import from HiBob** flow:
|
|
362
368
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
2. Upload it to the import modal in Settings
|
|
367
|
-
3. Review the preview: see which members will be moved, which groups will be created, and which members weren't matched
|
|
369
|
+
1. Export a CSV from HiBob's People Directory (include Email, Department, Group, and Team columns)
|
|
370
|
+
2. Upload it to the import modal
|
|
371
|
+
3. Review the preview — see which members will be moved, which groups will be created, and who wasn't matched
|
|
368
372
|
4. Selectively approve or reject individual changes before applying
|
|
369
373
|
|
|
370
|
-
The import
|
|
374
|
+
The import builds a `Group > Team` hierarchy automatically. Small teams (fewer than 3 members) are merged into their parent group. Members not found in the CSV keep their current assignment.
|
|
371
375
|
|
|
372
376
|
> The HiBob import updates your local billing groups only. It does not push changes back to HiBob or to Cursor's billing API.
|
|
373
377
|
|
|
374
|
-
</details>
|
|
375
|
-
|
|
376
378
|
---
|
|
377
379
|
|
|
378
380
|
## Authentication
|
|
@@ -434,15 +436,15 @@ When both are set, either match grants access. When neither is set, any Google a
|
|
|
434
436
|
|
|
435
437
|
## Tech Stack
|
|
436
438
|
|
|
437
|
-
| Component | Technology
|
|
438
|
-
| ---------- |
|
|
439
|
-
| Framework | Next.js
|
|
440
|
-
| Language | TypeScript
|
|
441
|
-
| Database | SQLite
|
|
442
|
-
| Charts | Recharts
|
|
443
|
-
| Styling | Tailwind CSS
|
|
444
|
-
| Testing | Vitest
|
|
445
|
-
| Deployment | Docker
|
|
439
|
+
| Component | Technology |
|
|
440
|
+
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
441
|
+
| Framework | [](https://github.com/vercel/next.js) App Router |
|
|
442
|
+
| Language | [](https://github.com/microsoft/TypeScript) strict mode |
|
|
443
|
+
| Database | [](https://github.com/WiseLibs/better-sqlite3) via better-sqlite3 (swappable) |
|
|
444
|
+
| Charts | [](https://github.com/recharts/recharts) |
|
|
445
|
+
| Styling | [](https://github.com/tailwindlabs/tailwindcss) |
|
|
446
|
+
| Testing | [](https://github.com/vitest-dev/vitest) |
|
|
447
|
+
| Deployment | [](https://github.com/docker) multi-stage build |
|
|
446
448
|
|
|
447
449
|
---
|
|
448
450
|
|
|
@@ -484,7 +486,7 @@ This project handles sensitive usage and spending data, so security matters here
|
|
|
484
486
|
- **Automated scanning**: Every push and PR goes through [CodeQL](https://codeql.github.com/) (SQL injection, XSS, CSRF, etc.) and [Dependabot](https://docs.github.com/en/code-security/dependabot) for dependency vulnerabilities.
|
|
485
487
|
- **OpenSSF Scorecard**: Continuously evaluated against [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/ofershap/cursor-usage-tracker) security benchmarks.
|
|
486
488
|
- **OpenSSF Best Practices**: [Passing badge](https://www.bestpractices.dev/projects/11968) earned.
|
|
487
|
-
- **Data stays
|
|
489
|
+
- **Data stays yours**: Everything is stored in your own infrastructure. No external services, no telemetry, no data leaving your network.
|
|
488
490
|
- **Small dependency tree**: Fewer dependencies = smaller attack surface.
|
|
489
491
|
- **Signed releases**: Automated via semantic-release with GitHub-verified provenance.
|
|
490
492
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cursor-usage-tracker",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.18.0",
|
|
4
4
|
"description": "Open-source Cursor IDE usage monitoring, anomaly detection, and alerting for enterprise teams",
|
|
5
5
|
"homepage": "https://github.com/ofershap/cursor-usage-tracker#readme",
|
|
6
6
|
"type": "module",
|