feat: initial release — Cursor IDE usage monitoring with anomaly detection

3-layer anomaly detection (thresholds, Z-score, trends), MTTD/MTTI/MTTR
incident lifecycle, Slack & email alerts, and a Next.js dashboard.

- Cursor Enterprise Admin + Analytics API client (Basic Auth)
- SQLite storage with zero-config setup
- Detection: static thresholds, statistical outliers, spike/drift/model-shift
- Dashboard: team overview, per-user drilldown, anomaly timeline, settings
- Docker support with standalone Next.js output
- CI/CD with GitHub Actions, semantic-release

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ofershap

.cursor/rules/coding-conventions.mdc

@@ -0,0 +1,54 @@
+---
+description: Coding conventions and patterns for cursor-usage-tracker
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Coding Conventions
+
+## Imports
+
+- NO `.js` extensions on internal imports — Next.js Turbopack bundler resolution doesn't support them
+- Use `@/` path alias for imports from `src/` (configured in tsconfig.json)
+- Use `import type` for type-only imports
+
+```typescript
+// CORRECT
+import { getDb } from "@/lib/db";
+import type { Anomaly } from "@/lib/types";
+
+// WRONG — will break Next.js build
+import { getDb } from "./db.js";
+```
+
+## Database
+
+- All DB access goes through `src/lib/db.ts` — never import better-sqlite3 directly in pages/routes
+- Use `getDb()` singleton — it initializes schema on first call
+- Use transactions for batch inserts: `db.transaction(() => { ... })()`
+- SQLite column names use snake_case; TypeScript types use camelCase
+
+## API Routes
+
+- All API routes use `export const dynamic = "force-dynamic"` (data is always fresh from SQLite)
+- Cron endpoint requires `x-cron-secret` header or `?secret=` query param
+- Use Next.js App Router async params pattern: `{ params }: { params: Promise<{ id: string }> }`
+
+## Components
+
+- Dashboard pages: server component (page.tsx) fetches data, passes to client component (*-client.tsx)
+- Charts are always client components ("use client")
+- Use Tailwind CSS with zinc color palette (dark theme)
+- No shadcn/ui installed — components are hand-rolled
+
+## Anomaly Detection
+
+- Three layers: thresholds → zscore → trends (all in `src/lib/anomaly/`)
+- `detector.ts` orchestrates all three, deduplicates by `userEmail:type:metric` key
+- New anomalies get inserted; existing ones that no longer fire get auto-resolved
+
+## Testing
+
+- Tests in `tests/` directory, use Vitest
+- Anomaly tests create their own test SQLite DB (not the main db.ts singleton)
+- API client tests mock `globalThis.fetch`

.cursor/rules/cursor-api.mdc

@@ -0,0 +1,77 @@
+---
+description: Cursor Enterprise API reference — endpoints, auth, response shapes, rate limits
+globs: "**/cursor-client.ts"
+alwaysApply: false
+---
+
+# Cursor Enterprise API Reference
+
+Base URL: `https://api.cursor.com`
+Auth: **Basic Auth** — `Authorization: Basic {base64(API_KEY + ':')}`
+Two separate API keys: Admin API key and Analytics API key (generated from team settings).
+
+## Rate Limits (per team, per minute)
+
+| API | Endpoint Type | Limit |
+|-----|---------------|-------|
+| Admin API | Most endpoints | 20 req/min |
+| Admin API | `/teams/user-spend-limit` | 250 req/min |
+| Analytics API | Team-level (`/analytics/team/*`) | 100 req/min |
+| Analytics API | By-user (`/analytics/by-user/*`) | 50 req/min |
+
+304 responses from ETag caching do NOT count against rate limits.
+
+## Admin API Endpoints
+
+### GET /teams/members
+Returns `{ teamMembers: [{ name, email, role }] }`
+
+### POST /teams/daily-usage-data
+Body: `{ startDate: number (ms), endDate: number (ms) }`
+Poll at most once per hour (data aggregated hourly).
+
+### POST /teams/spend
+Body: `{ page, pageSize }`
+Returns `{ teamMemberSpend: [{ email, spendCents, fastPremiumRequests }], subscriptionCycleStart: number, totalPages }`
+
+### POST /teams/filtered-usage-events
+Body: `{ email?, startDate?, endDate?, page, pageSize }`
+Returns `{ usageEvents: [{ timestamp, model, kindLabel, tokenUsage: { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens }, userEmail }], pagination: { hasNextPage } }`
+Poll at most once per hour (data aggregated hourly). Max 30 days per request.
+
+### POST /teams/user-spend-limit
+Body: `{ email, hardLimitDollars }`
+
+## Analytics API Endpoints (separate key: CURSOR_ANALYTICS_API_KEY)
+
+All use `startDate`/`endDate` params (formats: `YYYY-MM-DD`, `7d`, `30d`, `today`, `yesterday`). Max 30 days. Default: last 7 days.
+Optional `users` param: comma-separated emails or user IDs.
+
+### Team-Level
+- `GET /analytics/team/dau` — daily active users (includes cli_dau, cloud_agent_dau, bugbot_dau)
+- `GET /analytics/team/models` — model usage with `model_breakdown` per day
+- `GET /analytics/team/agent-edits` — agent edits (suggested/accepted diffs and lines)
+- `GET /analytics/team/tabs` — tab autocomplete usage
+- `GET /analytics/team/leaderboard` — ranked by AI usage (supports `page`, `pageSize`)
+- `GET /analytics/team/mcp` — MCP tool adoption
+- `GET /analytics/team/commands` — command adoption
+- `GET /analytics/team/plans` — plan mode adoption
+- `GET /analytics/team/ask-mode` — ask mode adoption
+- `GET /analytics/team/client-versions` — Cursor version distribution
+- `GET /analytics/team/top-file-extensions` — most edited file types
+
+### By-User (paginated: `page`, `pageSize`, max 500)
+All follow pattern: `GET /analytics/by-user/{metric}`
+Available: `agent-edits`, `tabs`, `models`, `mcp`, `commands`, `plans`, `ask-mode`, `client-versions`, `top-file-extensions`
+
+## Known Model Strings (from API responses)
+
+`claude-sonnet-4.5`, `claude-opus-4.5`, `claude-opus-4.6`, `gpt-4o`, `gpt-5.2`, `gpt-5.3-codex`, `gemini-3-flash`, `gemini-3-pro`, `grok-code`
+
+## Caching
+
+Analytics and AI Code Tracking APIs support ETags. Use `If-None-Match` header for 304 responses (15-minute cache, `Cache-Control: public, max-age=900`).
+
+## Important
+
+Admin API endpoint response shapes are based on community implementations and may not exactly match the live API. Analytics API shapes are from official Cursor documentation (Feb 2026). If you encounter mismatches, update `src/lib/types.ts` and `src/lib/cursor-client.ts`.

.cursor/rules/project-context.mdc

@@ -0,0 +1,63 @@
+---
+description: Core project context for cursor-usage-tracker — architecture, data flow, key files
+alwaysApply: true
+---
+
+# cursor-usage-tracker — Project Context
+
+Open-source Cursor IDE usage monitoring, anomaly detection, and alerting for enterprise teams.
+
+## Tech Stack
+
+- Next.js (App Router, Turbopack) + TypeScript strict
+- SQLite via better-sqlite3 (zero-config, file at `data/tracker.db`)
+- Recharts for charts, Tailwind CSS for styling
+- Vitest for tests, ESLint 9 flat config, Prettier
+- Docker (multi-stage Dockerfile + docker-compose.yml)
+
+## Architecture
+
+```
+Cursor Enterprise APIs → Collector (src/lib/collector.ts) → SQLite (src/lib/db.ts)
+                                                                ↓
+                                                    Detection Engine (src/lib/anomaly/)
+                                                                ↓
+                                                    Alerts: Slack + Email (src/lib/alerts/)
+                                                                ↓
+                                                    Dashboard (src/app/ pages)
+```
+
+Single cron endpoint `POST /api/cron` does: collect → detect → alert in one call.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/lib/types.ts` | All shared types + DetectionConfig + DEFAULT_CONFIG |
+| `src/lib/cursor-client.ts` | Cursor API client (Admin + Analytics), pagination, rate-limit retry |
+| `src/lib/db.ts` | SQLite schema, all queries, dashboard stats, user stats |
+| `src/lib/collector.ts` | Data collection pipeline (members, daily usage, spending, events) |
+| `src/lib/anomaly/detector.ts` | Orchestrator — runs all 3 detection layers, deduplicates |
+| `src/lib/anomaly/thresholds.ts` | Layer 1: static limits (spend, requests, tokens) |
+| `src/lib/anomaly/zscore.ts` | Layer 2: statistical z-score vs team mean |
+| `src/lib/anomaly/trends.ts` | Layer 3: personal spikes, drift above P75, model shift |
+| `src/lib/incidents.ts` | Incident lifecycle: create, alert, acknowledge, resolve + MTTD/MTTI/MTTR |
+| `src/lib/alerts/slack.ts` | Slack webhook with block-kit messages |
+| `src/lib/alerts/email.ts` | SMTP email with HTML templates |
+| `src/app/api/cron/route.ts` | Main cron endpoint (collect + detect + alert) |
+
+## Dashboard Pages
+
+- `/` — Team overview: stat cards, spend bar chart, usage line chart, members table
+- `/users/[email]` — Per-user: token timeline, model pie chart, feature breakdown, anomaly history
+- `/anomalies` — MTTD/MTTI/MTTR metrics, open incidents (acknowledge/resolve), anomaly table
+- `/settings` — Configurable detection thresholds
+
+## Database Tables
+
+members, daily_usage, spending, usage_events, anomalies, incidents, config, collection_log
+
+## Important Caveats
+
+- API response shapes may not exactly match the live Cursor API. If real responses differ, update `src/lib/types.ts` and `src/lib/cursor-client.ts`.
+- Trend detection can produce duplicate dedup keys (spike + drift both emit `trend:tokens` for same user) — first one wins, second is silently dropped.

.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+.next
+.git
+data/*.db
+data/*.db-journal
+coverage
+.env
+.env.local

.env.example

@@ -0,0 +1,15 @@
+CURSOR_ADMIN_API_KEY=key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+CURSOR_ANALYTICS_API_KEY=
+
+SLACK_WEBHOOK_URL=
+
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASS=
+SMTP_FROM=cursor-tracker@yourcompany.com
+ALERT_EMAIL_TO=team-lead@yourcompany.com
+
+CRON_SECRET=your-secret-for-cron-endpoint
+
+DASHBOARD_PASSWORD=

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: ofershap

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+.next/
+dist/
+data/*.db
+data/*.db-journal
+data/*.db-shm
+data/*.db-wal
+coverage/
+*.tsbuildinfo
+.env
+.env.local
+.env.*.local
+.DS_Store

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged