cursor-usage 0.1.0

package/README.md

@@ -0,0 +1,209 @@
+# Cursor Usage Analyzer
+
+A CLI tool for analyzing Cursor API usage and membership information, inspired by [ccusage](https://github.com/ryoppippi/ccusage).
+
+## Features
+
+- ✨ Extract Cursor credentials from local database
+- 🔗 Fetch usage data from Cursor API
+- 💳 Display membership and plan usage information
+- 📊 Show usage breakdown (included vs bonus)
+- 🎯 Track percentage of included usage consumed
+- 🎨 Colorful terminal output
+
+## Installation
+
+```bash
+npm install
+```
+
+## Usage
+
+### Commands
+
+```bash
+# Show current billing summary (default)
+npm run dev
+
+# Show daily usage for last 7 days (default)
+npm run dev -- daily
+
+# Show daily usage for last N days
+npm run dev -- daily 30
+npm run dev -- d 7          # Alias
+
+# Show monthly usage for last 3 months (default)
+npm run dev -- monthly
+
+# Show monthly usage for last N months
+npm run dev -- monthly 6
+npm run dev -- m 12         # Alias
+
+# Show detailed usage for today
+npm run dev -- today
+
+# Show help
+npm run dev -- help
+```
+
+### Development
+
+```bash
+npm run dev              # Run with tsx (default summary)
+npm start               # Run with tsx (default summary)
+npm run build           # Compile TypeScript
+```
+
+## Example Output
+
+### Summary View
+
+```
+📊 ACCOUNT INFORMATION:
+  Membership: pro
+  Billing Cycle: <your-billing-cycle>
+
+📊 PLAN USAGE:
+  Used: 150 / 2000 (7.50%)
+  Remaining: 1850
+```
+
+### Daily Report View
+
+```
+✓ Found 3 usage events
+
+====================================================================================================
+DAILY USAGE REPORT (Last 7 days)
+====================================================================================================
+
++------------+--------+--------------+-------+--------+-------+----------------------------------+
+| Date       | Events | Total Tokens | Input | Output | Cost  | Models                           |
++------------+--------+--------------+-------+--------+-------+----------------------------------+
+| 2026-01-11 | 3      | 539,301      | 381   | 7,081  | $0.82 | claude-4.5-opus-high-thinking(3) |
++------------+--------+--------------+-------+--------+-------+----------------------------------+
+
+====================================================================================================
+SUMMARY
+====================================================================================================
+Total Events: 3
+Total Tokens: 539,301
+Total Cost: $0.82
+====================================================================================================
+```
+
+### Monthly Report View
+
+```
+====================================================================================================
+MONTHLY USAGE REPORT (Last 3 months)
+====================================================================================================
+
++----------+--------+---------------+-------+-------+-------+------------------------------+
+| Month    | Events | Total Tokens  | Input | Output| Cost  | Models                       |
++----------+--------+---------------+-------+-------+-------+------------------------------+
+| Month 1  | 50     | 5,000,000     | 50000 | 30000 | $4.50 | claude-sonnet(50)            |
+| Month 2  | 75     | 8,500,000     | 75000 | 45000 | $6.80 | claude-opus(75)              |
+| Month 3  | 25     | 2,500,000     | 20000 | 10000 | $2.00 | claude-haiku(25)             |
++----------+--------+---------------+-------+-------+-------+------------------------------+
+
+====================================================================================================
+SUMMARY
+====================================================================================================
+Total Events: 150
+Total Tokens: 16,000,000
+Total Cost: $13.30
+Average per month: 5,333,333 tokens, $4.43
+====================================================================================================
+```
+
+### Detailed Event View
+
+```
+========================================================================================================================
+USAGE EVENTS FOR Today
+========================================================================================================================
+
++----------+---------------+-------+--------------+---------------+--------------+---------+
+| Time     | Model         | Type  | Input Tokens | Output Tokens | Total Tokens | Cost    |
++----------+---------------+-------+--------------+---------------+--------------+---------+
+| 2:15 pm  | claude-opus   | usage | 500          | 1,200         | 1,700        | $0.0850 |
+| 1:45 pm  | claude-sonnet | usage | 300          | 800           | 1,100        | $0.0440 |
+| 1:20 pm  | claude-haiku  | usage | 100          | 250           | 350          | $0.0070 |
++----------+---------------+-------+--------------+---------------+--------------+---------+
+
+========================================================================================================================
+Total Events: 3
+Total Tokens: 3,150
+Total Cost: $0.14
+========================================================================================================================
+```
+
+## How It Works
+
+1. **Extracts credentials** from `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`
+   - User ID from `workbench.experiments.statsigBootstrap`
+   - Access Token from `cursorAuth/accessToken`
+   - Email and membership (optional)
+
+2. **Authenticates** with Cursor API using `WorkosCursorSessionToken` cookie
+
+3. **Fetches usage data** from `https://cursor.com/api/usage-summary`
+
+4. **Parses and displays** membership, plan usage, and billing information
+
+## Environment Variables
+
+- `CURSOR_DATA_DIR` - Custom path to Cursor data directory (optional)
+- `DEBUG` - Enable debug logging
+
+## Project Structure
+
+```
+src/
+├── index.ts          # CLI entry point & display logic
+├── data-loader.ts    # Database extraction & API fetching
+├── logger.ts         # Colored logging utilities
+├── _types.ts         # TypeScript type definitions
+└── _consts.ts        # Constants & configuration
+```
+
+## API Response Structure
+
+The tool fetches data from Cursor's `/api/usage-summary` endpoint which returns:
+- Billing cycle information
+- Membership type (pro, hobby, etc.)
+- Plan usage (used/limit/remaining)
+- On-demand usage status
+- Display messages about usage percentage
+
+## Features Implemented
+
+- ✅ Daily usage reports with table formatting
+- ✅ Detailed event breakdown by time
+- ✅ Token count tracking (input, output, cache)
+- ✅ Cost calculation and display
+- ✅ Model usage breakdown
+- ✅ Flexible date range querying
+- ✅ Colorized CLI output
+
+## Future Enhancements
+
+- [ ] JSON output format (`--json`)
+- [ ] Date range queries (`--from 2026-01-01 --to 2026-01-31`)
+- [ ] Weekly/monthly aggregations
+- [ ] Historical data caching
+- [ ] Cost projections
+- [ ] Team usage analysis
+- [ ] Export to CSV/JSON
+- [ ] Web dashboard
+- [ ] Webhook notifications
+
+## License
+
+MIT
+
+## Related Projects
+
+- [ccusage](https://github.com/ryoppippi/ccusage) - Claude Code usage analyzer
+- [@ccusage/amp](https://www.npmjs.com/package/@ccusage/amp) - Amp usage analyzer

package/dist/_consts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Constants for Cursor usage analyzer
+ */
+export declare const CURSOR_DB_PATH: string;
+export declare const CURSOR_API_URL = "https://cursor.com/api/usage-summary";
+export declare const CURSOR_API_URL_EVENTS = "https://cursor.com/api/dashboard/get-filtered-usage-events";
+export declare const CURSOR_DATA_DIR_ENV = "CURSOR_DATA_DIR";
+export declare const DB_KEY_STATSIG_BOOTSTRAP = "workbench.experiments.statsigBootstrap";
+export declare const DB_KEY_ACCESS_TOKEN = "cursorAuth/accessToken";
+export declare const DB_KEY_EMAIL = "cursorAuth/cachedEmail";
+export declare const DB_KEY_MEMBERSHIP = "cursorAuth/stripeMembershipType";
+export declare const DEFAULT_TIMEOUT = 10000;
+export declare const USER_AGENT = "Mozilla/5.0 (compatible; cursor-usage/1.0)";

package/dist/_consts.js

@@ -0,0 +1,16 @@
+/**
+ * Constants for Cursor usage analyzer
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const CURSOR_DB_PATH = join(homedir(), 'Library/Application Support/Cursor/User/globalStorage/state.vscdb');
+export const CURSOR_API_URL = 'https://cursor.com/api/usage-summary';
+export const CURSOR_API_URL_EVENTS = 'https://cursor.com/api/dashboard/get-filtered-usage-events';
+export const CURSOR_DATA_DIR_ENV = 'CURSOR_DATA_DIR';
+// Database keys
+export const DB_KEY_STATSIG_BOOTSTRAP = 'workbench.experiments.statsigBootstrap';
+export const DB_KEY_ACCESS_TOKEN = 'cursorAuth/accessToken';
+export const DB_KEY_EMAIL = 'cursorAuth/cachedEmail';
+export const DB_KEY_MEMBERSHIP = 'cursorAuth/stripeMembershipType';
+export const DEFAULT_TIMEOUT = 10000; // 10 seconds
+export const USER_AGENT = 'Mozilla/5.0 (compatible; cursor-usage/1.0)';

package/dist/_types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Type definitions for Cursor usage data
+ */
+export interface UsageBreakdown {
+    included: number;
+    bonus: number;
+    total: number;
+}
+export interface PlanUsage {
+    enabled: boolean;
+    used: number;
+    limit: number;
+    remaining: number;
+    breakdown: UsageBreakdown;
+    autoPercentUsed: number;
+    apiPercentUsed: number;
+    totalPercentUsed: number;
+}
+export interface OnDemandUsage {
+    enabled: boolean;
+    used: number;
+    limit: number | null;
+    remaining: number | null;
+}
+export interface IndividualUsage {
+    plan: PlanUsage;
+    onDemand: OnDemandUsage;
+}
+export interface UsageSummary {
+    billingCycleStart: string;
+    billingCycleEnd: string;
+    membershipType: string;
+    limitType: string;
+    isUnlimited: boolean;
+    autoModelSelectedDisplayMessage: string;
+    namedModelSelectedDisplayMessage: string;
+    individualUsage: IndividualUsage;
+    teamUsage: Record<string, any>;
+}
+export interface CursorCredentials {
+    userId: string;
+    accessToken: string;
+    email?: string;
+    membership?: string;
+}
+export interface FetchOptions {
+    userAgent?: string;
+    timeout?: number;
+}
+export interface MonthlyStats {
+    year: number;
+    month: number;
+    monthName: string;
+    eventCount: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalCost: number;
+    models: Map<string, number>;
+}

package/dist/_types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Cursor usage data
+ */
+export {};

package/dist/args-parser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Command-line argument parser
+ */
+export interface ParsedArgs {
+    command: string;
+    params: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Parse command-line arguments
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Validate and parse date string (YYYY-MM-DD)
+ */
+export declare function parseDate(dateStr: string): Date | null;
+/**
+ * Get date from flag or parameter
+ */
+export declare function getDateFlag(flags: Record<string, string | boolean>, key: string): Date | null;
+/**
+ * Get number from flag or parameter
+ */
+export declare function getNumberFlag(flags: Record<string, string | boolean>, key: string, defaultValue?: number): number;
+/**
+ * Get boolean flag
+ */
+export declare function getBoolFlag(flags: Record<string, string | boolean>, key: string): boolean;
+/**
+ * Get string flag
+ */
+export declare function getStringFlag(flags: Record<string, string | boolean>, key: string, defaultValue?: string): string;

package/dist/args-parser.js

@@ -0,0 +1,104 @@
+/**
+ * Command-line argument parser
+ */
+/**
+ * Parse command-line arguments
+ */
+export function parseArgs(argv) {
+    const command = argv[0] || 'summary';
+    const params = [];
+    const flags = {};
+    let i = 1;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            // Long flag: --flag or --flag=value
+            const eqIndex = arg.indexOf('=');
+            if (eqIndex > -1) {
+                const key = arg.substring(2, eqIndex);
+                const value = arg.substring(eqIndex + 1);
+                flags[key] = value;
+            }
+            else {
+                const key = arg.substring(2);
+                // Check if next arg is value (not a flag)
+                if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+                    flags[key] = argv[i + 1];
+                    i++;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+        }
+        else if (arg.startsWith('-') && arg.length === 2) {
+            // Short flag: -h
+            const key = arg.substring(1);
+            if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+                flags[key] = argv[i + 1];
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            // Positional parameter
+            params.push(arg);
+        }
+        i++;
+    }
+    return { command, params, flags };
+}
+/**
+ * Validate and parse date string (YYYY-MM-DD)
+ */
+export function parseDate(dateStr) {
+    const match = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!match) {
+        return null;
+    }
+    const [, year, month, day] = match;
+    const date = new Date(`${year}-${month}-${day}T00:00:00Z`);
+    if (isNaN(date.getTime())) {
+        return null;
+    }
+    return date;
+}
+/**
+ * Get date from flag or parameter
+ */
+export function getDateFlag(flags, key) {
+    const value = flags[key];
+    if (!value || typeof value !== 'string') {
+        return null;
+    }
+    return parseDate(value);
+}
+/**
+ * Get number from flag or parameter
+ */
+export function getNumberFlag(flags, key, defaultValue = 0) {
+    const value = flags[key];
+    if (value === undefined || value === true) {
+        return defaultValue;
+    }
+    const num = Number(value);
+    return isNaN(num) ? defaultValue : num;
+}
+/**
+ * Get boolean flag
+ */
+export function getBoolFlag(flags, key) {
+    return flags[key] === true;
+}
+/**
+ * Get string flag
+ */
+export function getStringFlag(flags, key, defaultValue = '') {
+    const value = flags[key];
+    if (typeof value === 'string') {
+        return value;
+    }
+    return defaultValue;
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+/**
+ * CLI command routing and argument handling
+ */
+export declare function runCLI(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,162 @@
+/**
+ * CLI command routing and argument handling
+ */
+import { getCursorCredentials, fetchUsageData } from './data-loader';
+import { showDailyReport, showMonthlyReport, showWeeklyReport, showDateReport, } from './commands';
+import { logger } from './logger';
+import { parseArgs, getNumberFlag, getDateFlag, getBoolFlag, } from './args-parser';
+export async function runCLI(argv) {
+    const parsed = parseArgs(argv);
+    const { command, params, flags } = parsed;
+    // Load credentials
+    const credentials = await getCursorCredentials();
+    if (!credentials) {
+        logger.error('Failed to load credentials from local database');
+        process.exit(1);
+    }
+    // Get common flags
+    const breakdown = getBoolFlag(flags, 'breakdown');
+    const json = getBoolFlag(flags, 'json');
+    const sinceDate = getDateFlag(flags, 'since');
+    const untilDate = getDateFlag(flags, 'until');
+    // Route commands
+    if (command === 'daily' || command === 'd') {
+        const days = getNumberFlag(flags, 'days') || getNumberFlag({ [params[0] || '']: params[0] }, '', 7);
+        const numDays = params.length > 0 && !isNaN(Number(params[0])) ? Number(params[0]) : days;
+        const options = {
+            breakdown,
+            startDate: sinceDate || undefined,
+            endDate: untilDate || undefined,
+            compact: getBoolFlag(flags, 'compact')
+        };
+        await showDailyReport(credentials, numDays, options, json);
+    }
+    else if (command === 'monthly' || command === 'm') {
+        const months = params.length > 0 && !isNaN(Number(params[0])) ? Number(params[0]) : 3;
+        const options = {
+            breakdown,
+            startDate: sinceDate || undefined,
+            endDate: untilDate || undefined,
+            compact: getBoolFlag(flags, 'compact')
+        };
+        await showMonthlyReport(credentials, months, options, json);
+    }
+    else if (command === 'weekly' || command === 'w') {
+        const weeks = params.length > 0 && !isNaN(Number(params[0])) ? Number(params[0]) : 4;
+        const options = {
+            breakdown,
+            startDate: sinceDate || undefined,
+            endDate: untilDate || undefined,
+            compact: getBoolFlag(flags, 'compact')
+        };
+        await showWeeklyReport(credentials, weeks, options, json);
+    }
+    else if (command === 'today') {
+        const options = { breakdown, compact: getBoolFlag(flags, 'compact') };
+        await showDateReport(credentials, new Date(), options, json);
+    }
+    else if (command === 'help' || command === '-h' || command === '--help') {
+        showHelp();
+    }
+    else {
+        // Default: show summary
+        const usageData = await fetchUsageData(credentials);
+        if (!usageData) {
+            logger.error('Failed to fetch usage data');
+            process.exit(1);
+        }
+        logger.log('');
+        displayResults(usageData);
+    }
+}
+function displayResults(data) {
+    logger.log('='.repeat(70));
+    logger.log('CURSOR USAGE SUMMARY');
+    logger.log('='.repeat(70));
+    // Membership and plan info
+    logger.log('\n📋 ACCOUNT INFORMATION:');
+    logger.log(`  Membership: ${data.membershipType || 'N/A'}`);
+    logger.log(`  Billing Cycle: ${formatDate(data.billingCycleStart)} to ${formatDate(data.billingCycleEnd)}`);
+    // Plan usage
+    const plan = data.individualUsage?.plan;
+    if (plan) {
+        logger.log('\n📊 PLAN USAGE:');
+        logger.log(`  Used: ${plan.used} / ${plan.limit} (${(plan.totalPercentUsed * 100).toFixed(2)}%)`);
+        logger.log(`  Remaining: ${plan.remaining}`);
+        logger.log(`  Breakdown:`);
+        logger.log(`    - Included: ${plan.breakdown?.included || 0}`);
+        logger.log(`    - Bonus: ${plan.breakdown?.bonus || 0}`);
+    }
+    // On-demand usage
+    const onDemand = data.individualUsage?.onDemand;
+    if (onDemand && onDemand.enabled) {
+        logger.log('\n💰 ON-DEMAND USAGE:');
+        logger.log(`  Used: ${onDemand.used}`);
+        logger.log(`  Status: Enabled`);
+    }
+    // Display messages
+    if (data.autoModelSelectedDisplayMessage) {
+        logger.log('\n📢 AUTO MODEL MESSAGE:');
+        logger.log(`  ${data.autoModelSelectedDisplayMessage}`);
+    }
+    if (data.namedModelSelectedDisplayMessage) {
+        logger.log('\n💬 NAMED MODEL MESSAGE:');
+        logger.log(`  ${data.namedModelSelectedDisplayMessage}`);
+    }
+    logger.log('\n' + '='.repeat(70) + '\n');
+}
+function formatDate(dateString) {
+    try {
+        const date = new Date(dateString);
+        return date.toLocaleDateString('en-US', {
+            year: 'numeric',
+            month: 'short',
+            day: 'numeric',
+        });
+    }
+    catch {
+        return dateString;
+    }
+}
+function showHelp() {
+    logger.log(`
+CURSOR USAGE ANALYZER - CLI COMMANDS
+
+Usage: cursor-usage [COMMAND] [OPTIONS]
+
+Commands:
+  (none)        Show current billing summary (default)
+  daily [N]     Show daily usage for last N days (default: 7)
+  d [N]         Alias for 'daily'
+  weekly [N]    Show weekly usage for last N weeks (default: 4)
+  w [N]         Alias for 'weekly'
+  monthly [N]   Show monthly usage for last N months (default: 3)
+  m [N]         Alias for 'monthly'
+  today         Show detailed usage for today
+  help          Show this help message
+  -h, --help    Show this help message
+
+Flags:
+  --since DATE     Start date (YYYY-MM-DD)
+  --until DATE     End date (YYYY-MM-DD)
+  --breakdown      Show per-model breakdown
+  --json           Output as JSON (in development)
+  --compact        Compact table format
+
+Examples:
+  cursor-usage                                           # Show summary
+  cursor-usage daily                                     # Show last 7 days
+  cursor-usage daily 30                                  # Show last 30 days
+  cursor-usage daily --since 2026-01-01 --until 2026-01-15
+  cursor-usage weekly                                    # Show last 4 weeks
+  cursor-usage weekly 8                                  # Show last 8 weeks
+  cursor-usage monthly                                   # Show last 3 months
+  cursor-usage monthly 6                                 # Show last 6 months
+  cursor-usage daily --breakdown                         # With model breakdown
+  cursor-usage weekly --breakdown --json                 # JSON output
+  cursor-usage today                                     # Today's details
+
+Environment Variables:
+  DEBUG         Enable debug logging
+  `);
+}

package/dist/commands.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CLI command handlers
+ */
+import type { CursorCredentials } from './_types';
+/**
+ * Convert stats to JSON
+ */
+export declare function statsToJSON(command: string, stats: any[], events: any[], options?: any): string;
+/**
+ * Show daily usage report for a date range
+ */
+export declare function showDailyReport(credentials: CursorCredentials, days?: number, options?: {
+    breakdown?: boolean;
+    startDate?: Date;
+    endDate?: Date;
+    compact?: boolean;
+}, outputJson?: boolean): Promise<void>;
+/**
+ * Show monthly usage report
+ */
+export declare function showMonthlyReport(credentials: CursorCredentials, months?: number, options?: {
+    breakdown?: boolean;
+    startDate?: Date;
+    endDate?: Date;
+    compact?: boolean;
+}, outputJson?: boolean): Promise<void>;
+/**
+ * Show weekly usage report
+ */
+export declare function showWeeklyReport(credentials: CursorCredentials, weeks?: number, options?: {
+    breakdown?: boolean;
+    startDate?: Date;
+    endDate?: Date;
+    compact?: boolean;
+}, outputJson?: boolean): Promise<void>;
+/**
+ * Show usage for a specific date
+ */
+export declare function showDateReport(credentials: CursorCredentials, date: Date, options?: {
+    breakdown?: boolean;
+    compact?: boolean;
+}, outputJson?: boolean): Promise<void>;