cursor-usage-tracker

Cursor Usage Tracker

Open-source cost monitoring and optimization for Cursor Enterprise teams. Track AI spend per developer, spot unnecessary expensive model usage, detect anomalies automatically, and get Slack alerts before the invoice surprises you. Self-host with Docker or let us run it for you.

   

AI Spend Is a Blind Spot

Engineering costs used to be two things: headcount and cloud infrastructure. You had tools for both. Then AI coding assistants showed up, and suddenly there's a third cost center that nobody has good tooling for.

A single developer on Cursor can burn through hundreds of dollars a day just by switching to an expensive model or letting an agent loop run wild. Developers often don't know which models cost more - one of our team members used opus-max for weeks thinking it was a cheaper option. Now multiply that confusion by 50, 100, 500 developers. The bill gets big fast, and there's nothing like Datadog or CloudHealth for this category yet.

Cursor's admin dashboard shows you the raw numbers, but it won't tell you when something is off. No anomaly detection. No alerts. No incident tracking. You find out about cost spikes when the invoice lands, weeks after the damage is done.

I built cursor-usage-tracker to fix that. It sits on top of Cursor's Enterprise APIs and gives engineering managers, finance, and platform teams actual visibility into AI spend before it becomes a surprise.

What This Dashboard Answers

• Cost monitoring - Are we spending too much? Who's driving it? Why?
• Cost optimization - Who's using expensive models when cheaper ones would do? How much would switching save?
• Adoption tracking - Is everyone using the tool we're paying for?
• Usage understanding - How is each person working with AI?

What It Does

Your company has 50+ developers on Cursor. Do you know who's spending $200/day on Claude Opus while everyone else uses Sonnet?

You're about to find out.

_{Watch the full demo (90 seconds):}

It connects to Cursor's Enterprise APIs, collects usage data, and automatically detects anomalies across three layers. When something looks off, you get a Slack message or email within the hour, not next month.

Developer uses Cursor → API collects data hourly → Engine detects anomaly → You get a Slack alert

How It Works

What happens	Example
A developer exceeds the spend limit	Bob spent $82 this cycle (limit: $50) → Slack alert
Someone's daily spend spikes	Alice: daily spend spiked to $214 (4.2x her 7-day avg of $51) → Slack alert
A user's cycle spend is far above the team	Bob: cycle spend $957 is 5.1x the team median ($188) → Slack alert
A user is statistically far from the team	Bob: daily spend $214 is 3.2σ above team mean ($42) → Slack alert
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
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

Every alert includes who, what model, how much, and a link to their dashboard page so you can investigate immediately.

Quiz Time: Can you guess which Cursor model costs the most? 🤔

Your developers see this list every day. Can you spot the expensive one?

claude-4.6-opus-high

composer-1.5

claude-4.6-opus-max-thinking-fast

claude-4.5-opus-high

claude-4.6-opus-max

  Reveal the answer  

Model	Output $/1M tokens	Relative cost
composer-1.5	$17.50	1x (cheapest)
claude-4.5-opus-high	$25	1.4x
claude-4.6-opus-high	$25	1.4x
claude-4.6-opus-max	$25 + 20% surcharge	~1.7x
claude-4.6-opus-max-thinking-fast	$150 + 20% surcharge	~10x 🔥

"Fast" sounds cheap. It's the most expensive model Cursor offers.
Now imagine 200 developers picking from this dropdown without knowing.

Features

Three-Layer Anomaly Detection

Layer	Method	What it catches
Thresholds	Static limits	Optional hard caps on spend, requests, or tokens (disabled by default)
Z-Score	Statistical	User daily spend 2.5+ standard deviations above team mean (active users only)
Trends	Spend-based	Daily spend spikes vs personal average, cycle spend outliers vs team median
Expensive Model	Cost/request	User's $/request jumps vs their own history (catches model switches like max-thinking)

Incident Lifecycle (MTTD / MTTI / MTTR)

Every anomaly becomes a tracked incident with full lifecycle metrics:

Anomaly Detected ──→ Alert Sent ──→ Acknowledged ──→ Resolved
       │                  │               │              │
       └──── MTTD ────────┘               │              │
                                          └── MTTI ──────┘
       └────────────────── MTTR ─────────────────────────┘

• MTTD (Mean Time to Detect): how fast the system catches it
• MTTI (Mean Time to Identify): how fast a human acknowledges it
• MTTR (Mean Time to Resolve): how fast it gets fixed

Proactive Slack Notifications

You don't need to remember to check the dashboard. The system comes to you.

Notification	When it fires	What you learn
Anomaly alerts	Within the hour	"Alice's daily spend spiked to $214 (4.2x her 7-day avg)"
Plan exhaustion	Daily, when users exceed plan	"65/151 active users have exceeded their included plan this cycle"
Cycle summary	3 days before billing cycle ends	Total spend, unused seats, top spenders, adoption breakdown, cycle-over-cycle trend

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.

Also supports email alerts via Resend (one API key, no SMTP config).

Web Dashboard

Page	What you see
Team Overview	Stat cards, spend by user, daily spend trend, spend breakdown, members table with search/sort, group filter dropdown, billing cycle progress, time range picker
Insights	DAU chart, model adoption trends, model efficiency rankings (cost/precision), repository code volume (lines, % of total, AI %), MCP tool usage, file extensions, client versions
User Drilldown	Per-user token timeline, model breakdown, feature usage, repository breakdown, activity profile, anomaly history
Anomalies	Open incidents, MTTD/MTTI/MTTR metrics, full anomaly timeline
Settings	Detection thresholds, expensive model alerts, billing group management, HiBob CSV import, group export/import

For a detailed breakdown of every section, metric, badge, and chart, see FEATURES.md.

Deploy

One-click deploy

Deploy your own instance in minutes. You'll need a Cursor Enterprise plan and an Admin API key.

Railway and Docker options below. Want help setting this up for your team? Deployment, threshold tuning, first spend analysis, ongoing support. Let's talk.

Quick Start

Prerequisites

What	Where to get it
Cursor Enterprise plan	Required for API access
Admin API key	Cursor dashboard → Settings → Advanced → Admin API Keys
Node.js 18+	nodejs.org

1. Set up

Option A: One command

npx cursor-usage-tracker my-tracker
cd my-tracker

Option B: Manual clone

git clone https://github.com/ofershap/cursor-usage-tracker.git
cd cursor-usage-tracker
npm install

2. Configure

cp .env.example .env

Edit .env:

# Required
CURSOR_ADMIN_API_KEY=your_admin_api_key

# Alerting — Slack (at least one alerting channel recommended)
SLACK_BOT_TOKEN=xoxb-your-bot-token          # bot token with chat:write scope
SLACK_CHANNEL_ID=C0123456789                  # channel to post alerts to

# Dashboard URL (used in alert links)
DASHBOARD_URL=http://localhost:3000

# Optional
CRON_SECRET=your_secret_here                  # protects the cron endpoint

# Email alerts via Resend (optional)
RESEND_API_KEY=re_xxxxxxxxxxxx
ALERT_EMAIL_TO=[e-mail]

3. Start the dashboard

npm run dev
# Open http://localhost:3000

4. Collect your first data

npm run collect

You should see:

[collect] Done in 4.2s
  Members: 87
  Daily usage: 30
  Spending: 87
  Usage events: 12,847

5. Run anomaly detection

After collecting data, run detection separately:

npm run detect

This runs the stored data through all three detection layers and sends alerts for anything it finds.

npm run collect only fetches data. npm run detect only runs detection. The cron endpoint (POST /api/cron) does both in one call.

6. Set up recurring collection

Trigger the cron endpoint hourly (via crontab, GitHub Actions, or any scheduler):

curl -X POST http://localhost:3000/api/cron -H "x-cron-secret: YOUR_SECRET"

This collects data, runs anomaly detection, and sends alerts in one call.

Production Deployment

Docker (self-hosted)

cp .env.example .env   # configure your keys
docker compose up -d
# Dashboard at http://localhost:3000

The Docker image uses multi-stage builds for a minimal production image. Data persists in a Docker volume.

Docker Compose details

services:
  tracker:
    build: .
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - tracker-data:/app/data
volumes:
  tracker-data:

Fly.io (recommended free option)

fly launch --copy-config          # creates the app from fly.toml
fly volumes create tracker_data --region ams --size 1
fly secrets set CURSOR_ADMIN_API_KEY=your_key CRON_SECRET=your_secret
fly deploy
# Dashboard at https://your-app.fly.dev

Set up hourly collection by adding DASHBOARD_URL and CRON_SECRET as GitHub Actions secrets. The included .github/workflows/cron.yml workflow triggers /api/cron every hour.

Other cloud platforms

Any platform that supports Docker + persistent volumes works:

• Render - use the deploy button above, or render.yaml in this repo
• Railway - create a project from this repo, attach a volume at /app/data

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 for details.

Architecture

flowchart TB
    APIs["Cursor Enterprise APIs\n/teams/members · /teams/spend · /teams/daily-usage-data\n/teams/filtered-usage-events · /teams/groups · /analytics/team/*"]
    C["Collector (hourly)"]
    DB[("Database\n(SQLite default, swappable)")]
    D["Detection Engine, 3 layers"]
    AL["Alerts: Slack / Email"]
    DA["Dashboard: Next.js"]

    APIs --> C --> DB --> D
    DB --> DA
    D --> AL

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.

Configuration

All detection thresholds are configurable via the Settings page or the API:

Setting	Default	What it does
Max spend per cycle	0 (off)	Alert when a user exceeds this in a billing cycle
Max requests per day	0 (off)	Alert on excessive daily request count
Max tokens per day	0 (off)	Alert on excessive daily token consumption
Z-score multiplier	2.5	How many standard deviations above mean to flag (spend + reqs)
Z-score window	7 days	Historical window for statistical comparison
Spend spike multiplier	5.0x	Alert when today's spend > N× user's personal daily average
Spend spike lookback	7 days	How many days of history to compare against
Cycle outlier multiplier	10.0x	Alert when cycle spend > N× team median (active users only)
Cost/req spike multiplier	3.0x	Alert when today's $/request > N× user's historical average
Cost/req min daily spend	$20	Skip cost/req alerts for users below this daily spend

Settings

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.

Detection Thresholds

All anomaly detection parameters listed in 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.

Billing Groups

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.

From the Settings page you can:

• View all groups with member counts and per-group spend
• Rename groups to match your org structure (displayed as Parent > Team)
• Reassign individual members between groups
• Create new groups manually
• Search across all members to find and reassign anyone
• Export your current group mapping as a CSV backup
• Import a previously exported CSV to restore or transfer mappings between environments

HiBob Import

For teams using HiBob as their HR platform, the Settings page includes a dedicated Import from HiBob flow:

• Export a CSV from HiBob's People Directory (include Email, Department, Group, and Team columns)
• Upload it to the import modal
• Review the preview: which members move, which groups get created, who wasn't matched
• Selectively approve or reject individual changes before applying

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.

The HiBob import updates your local billing groups only. It does not push changes back to HiBob or to Cursor's billing API.

Authentication

Authentication is fully optional. When no auth environment variables are set, the dashboard is open (the default behavior). Setting AUTH_SECRET enables Google OAuth sign-in.

Setup

• Create a Google OAuth app with redirect URI:

  • Local: http://localhost:3000/api/auth/callback/google
  • Production: https://your-domain.com/api/auth/callback/google

• Add to your .env:

AUTH_SECRET=$(openssl rand -base64 32)       # encryption key for sessions
AUTH_GOOGLE_ID=your-client-id.apps.google... # Google OAuth client ID
AUTH_GOOGLE_SECRET=GOCSPX-...               # Google OAuth client secret
AUTH_TRUST_HOST=true                         # required behind a reverse proxy
AUTH_URL=https://your-domain.com             # public URL (auto-detected locally)

• Optionally restrict access by domain or specific emails:

AUTH_ALLOWED_DOMAIN=yourcompany.com          # only @yourcompany.com emails
AUTH_ALLOWED_EMAILS=[e-mail],[e-mail]  # or specific emails

When both are set, either match grants access. When neither is set, any Google account can sign in.

How It Works

• Sessions use encrypted JWT cookies, no database tables needed
• The /api/cron endpoint is excluded from auth (it uses its own CRON_SECRET)
• Sign-in page appears automatically when auth is enabled
• User avatar and sign-out menu appear in the nav bar

API Endpoints

Endpoint	Method	Description
/api/cron	POST	Collect + detect + alert (use with scheduler)
/api/stats	GET	Dashboard statistics (?days=7)
/api/analytics	GET	Analytics data: DAU, models, MCP, etc. (?days=30)
/api/team-spend	GET	Daily team spend breakdown
/api/model-costs	GET	Model cost breakdown by users and spend
/api/groups	GET	Billing groups with members and spend
/api/groups	PATCH	Rename group, assign member, or create group
/api/groups/import	POST	HiBob CSV import (preview + apply)
/api/anomalies	GET	Anomaly timeline (?days=30)
/api/users/[email]	GET	Per-user statistics (?days=30)
/api/incidents/[id]	PATCH	Acknowledge or resolve incident
/api/settings	GET/PUT	Detection configuration

Tech Stack

Component	Technology
Framework	App Router
Language	strict mode
Database	via better-sqlite3 (swappable)
Charts
Styling
Testing
Deployment	multi-stage build

Development

npm run dev          # Start dev server
npm run collect      # Manual data collection
npm run detect       # Manual anomaly detection + alerting
npm run typecheck    # Type checking
npm test             # Run tests
npm run lint         # Lint + format check

Cursor API Requirements

Requires a Cursor Enterprise plan. The tool uses these endpoints:

Endpoint	Auth	What it provides
GET /teams/members	Admin API key	Team member list
POST /teams/spend	Admin API key	Per-user spending data
POST /teams/daily-usage-data	Admin API key	Daily usage metrics
POST /teams/filtered-usage-events	Admin API key	Detailed usage events with model/token info
POST /teams/groups	Admin API key	Billing groups + cycle dates
GET /analytics/team/*	Analytics API key	DAU, model usage, MCP, tabs, etc. (optional)

Rate limit: 20 requests/minute (Admin API), 100 requests/minute (Analytics API). The collector handles rate limiting with automatic retry.

Security

This project handles sensitive usage and spending data, so security matters here more than most.

• Vulnerability reporting: See SECURITY.md for the disclosure policy. Report vulnerabilities privately via GitHub Security Advisories, not public issues.
• Automated scanning: Every push and PR goes through CodeQL (SQL injection, XSS, CSRF, etc.) and Dependabot for dependency vulnerabilities.
• OpenSSF Scorecard: Continuously evaluated against OpenSSF Scorecard security benchmarks.
• OpenSSF Best Practices: Passing badge earned.
• Data stays yours: Everything is stored in your own infrastructure. No external services, no telemetry, no data leaving your network.
• Small dependency tree: Fewer dependencies = smaller attack surface.
• Signed releases: Automated via semantic-release with GitHub-verified provenance.

Contributing

See CONTRIBUTING.md for setup and guidelines. Bug reports, feature requests, docs improvements, and code are all welcome. Use conventional commits and make sure CI is green before opening a PR.

Code of Conduct

This project uses the Contributor Covenant Code of Conduct.

Author

License

MIT © Ofer Shapira