cursor-usage-tracker 1.17.0 → 1.18.1
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 +57 -55
- 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
|
|
|
@@ -115,7 +117,7 @@ You don't need to remember to check the dashboard. The system comes to you.
|
|
|
115
117
|
| **Plan exhaustion** | Daily, when users exceed plan | "65/151 active users have exceeded their included plan this cycle" |
|
|
116
118
|
| **Cycle summary** | 3 days before billing cycle ends | Total spend, unused seats, top spenders, adoption breakdown, cycle-over-cycle trend |
|
|
117
119
|
|
|
118
|
-
Anomaly alerts include severity, user, model, value vs threshold, and a direct link to the user's dashboard page. Cycle summaries tell you how many seats are going unused and who's driving cost
|
|
120
|
+
Anomaly alerts include severity, user, model, value vs threshold, and a direct link to the user's dashboard page. Cycle summaries tell you how many seats are going unused and who's driving cost, so you can act before the invoice lands.
|
|
119
121
|
|
|
120
122
|
Also supports **email alerts** via [Resend](https://resend.com) (one API key, no SMTP config).
|
|
121
123
|
|
|
@@ -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
|
|
|
@@ -141,7 +143,7 @@ Deploy your own instance in minutes. You'll need a [Cursor Enterprise](https://c
|
|
|
141
143
|
|
|
142
144
|
[](https://render.com/deploy?repo=https://github.com/ofershap/cursor-usage-tracker)
|
|
143
145
|
|
|
144
|
-
> **Railway and Docker** options below. Want help setting this up for your team
|
|
146
|
+
> **Railway and Docker** options below. Want help setting this up for your team? Deployment, threshold tuning, first spend analysis, ongoing support. [Let's talk](https://linkedin.com/in/ofershap).
|
|
145
147
|
|
|
146
148
|
---
|
|
147
149
|
|
|
@@ -286,16 +288,16 @@ fly deploy
|
|
|
286
288
|
# Dashboard at https://your-app.fly.dev
|
|
287
289
|
```
|
|
288
290
|
|
|
289
|
-
Set up hourly collection by adding `DASHBOARD_URL` and `CRON_SECRET` as [GitHub Actions secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)
|
|
291
|
+
Set up hourly collection by adding `DASHBOARD_URL` and `CRON_SECRET` as [GitHub Actions secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). The included `.github/workflows/cron.yml` workflow triggers `/api/cron` every hour.
|
|
290
292
|
|
|
291
293
|
### Other cloud platforms
|
|
292
294
|
|
|
293
295
|
Any platform that supports Docker + persistent volumes works:
|
|
294
296
|
|
|
295
|
-
- **[Render](https://render.com)**
|
|
296
|
-
- **[Railway](https://railway.app)**
|
|
297
|
+
- **[Render](https://render.com)** - use the deploy button above, or `render.yaml` in this repo
|
|
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, the expensive model detector. Set any value to 0 to disable that 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 has a group filter dropdown. Select a group to 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: which members move, which groups get created, 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
|
|
@@ -406,7 +408,7 @@ When both are set, either match grants access. When neither is set, any Google a
|
|
|
406
408
|
|
|
407
409
|
### How It Works
|
|
408
410
|
|
|
409
|
-
- Sessions use encrypted JWT cookies
|
|
411
|
+
- Sessions use encrypted JWT cookies, no database tables needed
|
|
410
412
|
- The `/api/cron` endpoint is excluded from auth (it uses its own `CRON_SECRET`)
|
|
411
413
|
- Sign-in page appears automatically when auth is enabled
|
|
412
414
|
- User avatar and sign-out menu appear in the nav bar
|
|
@@ -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.1",
|
|
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",
|