costhawk 1.5.13 → 1.5.15

package/dist/index.js

@@ -19,7 +19,8 @@ const REQUEST_TIMEOUT_MS = 30000; // 30 seconds
 const PRICING_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const API_BASE_URL = process.env.COSTHAWK_API_URL || "https://costhawk.ai";
 const DEFAULT_BROWSER_LOGIN_HOSTS = ["costhawk.ai", "www.costhawk.ai"];
-const DEFAULT_API_KEY = process.env.COSTHAWK_API_KEY;
+const AUTH_STATE_PATH = join(homedir(), ".costhawk", "auth.json");
+const DEFAULT_API_KEY = process.env.COSTHAWK_API_KEY || readStoredApiKey();
 const CLIENT_VERSION = (() => {
     try {
         const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -48,6 +49,9 @@ const LOGIN_SYNC_MAX_AGE_HOURS = 720; // First-time login sync: 30 days of histo
 let autoSyncIntervalId = null;
 const AUTO_SYNC_ENABLED = process.env.COSTHAWK_AUTO_SYNC === "true";
 const CODEX_AUTO_SYNC_ENABLED = AUTO_SYNC_ENABLED && process.env.COSTHAWK_CODEX_AUTO_SYNC !== "false";
+// Cursor auto-sync piggybacks on the same master COSTHAWK_AUTO_SYNC toggle
+// as Codex, and can be individually opted out via COSTHAWK_CURSOR_AUTO_SYNC=false.
+const CURSOR_AUTO_SYNC_ENABLED = AUTO_SYNC_ENABLED && process.env.COSTHAWK_CURSOR_AUTO_SYNC !== "false";
 // AlertType enum values from backend
 const ALERT_TYPE_VALUES = [
     "BUDGET_EXCEEDED",
@@ -737,6 +741,9 @@ function resolveOpenCodeConfigPath() {
         return jsoncPath;
     return jsonPath;
 }
+function resolveGeminiConfigPath() {
+    return join(homedir(), ".gemini", "settings.json");
+}
 function stripJsonComments(input) {
     let output = "";
     let i = 0;
@@ -880,6 +887,30 @@ function writeSecretJsonFile(filePath, data) {
     writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, { mode: SECRET_FILE_MODE });
     enforceSecretFilePermissions(filePath);
 }
+function readStoredApiKey() {
+    if (!existsSync(AUTH_STATE_PATH))
+        return null;
+    try {
+        const raw = readFileSync(AUTH_STATE_PATH, "utf-8");
+        if (raw.trim().length === 0)
+            return null;
+        const parsed = JSON.parse(raw);
+        return typeof parsed.apiKey === "string" && parsed.apiKey.trim().length > 0 ? parsed.apiKey : null;
+    }
+    catch {
+        return null;
+    }
+}
+function persistApiKey(apiKey) {
+    const authDir = dirname(AUTH_STATE_PATH);
+    if (!existsSync(authDir)) {
+        mkdirSync(authDir, { recursive: true });
+    }
+    writeSecretJsonFile(AUTH_STATE_PATH, {
+        apiKey,
+        savedAt: new Date().toISOString(),
+    });
+}
 async function promptInput(question) {
     const rl = createInterface({
         input: process.stdin,
@@ -1005,6 +1036,10 @@ async function runSetup(args) {
     if (writeClaude === undefined) {
         writeClaude = true;
     }
+    let writeGemini = parseBooleanFlag(args, "gemini");
+    if (writeGemini === undefined) {
+        writeGemini = true;
+    }
     let writeOpenCode = parseBooleanFlag(args, "opencode");
     let apiKey = apiKeyArg || DEFAULT_API_KEY || "";
     if (!apiKey) {
@@ -1030,6 +1065,7 @@ async function runSetup(args) {
         console.error("Error: API key is required to complete setup.");
         process.exit(1);
     }
+    persistApiKey(apiKey);
     let autoSync = parseBooleanFlag(args, "auto-sync");
     if (autoSync === undefined) {
         if (!writeClaude) {
@@ -1056,6 +1092,20 @@ async function runSetup(args) {
     else {
         codexSync = false;
     }
+    let cursorSync = parseBooleanFlag(args, "cursor-sync");
+    if (autoSync) {
+        if (cursorSync === undefined) {
+            if (!process.stdin.isTTY || nonInteractive) {
+                cursorSync = true;
+            }
+            else {
+                cursorSync = await promptYesNo("Enable Cursor IDE auto-sync?", true);
+            }
+        }
+    }
+    else {
+        cursorSync = false;
+    }
     if (writeOpenCode === undefined) {
         if (!process.stdin.isTTY || nonInteractive) {
             writeOpenCode = false;
@@ -1064,8 +1114,8 @@ async function runSetup(args) {
             writeOpenCode = await promptYesNo("Also add OpenCode config?", false);
         }
     }
-    if (!writeClaude && !writeOpenCode) {
-        console.error("Error: No targets selected. Use --claude, --opencode, or both.");
+    if (!writeClaude && !writeGemini && !writeOpenCode) {
+        console.error("Error: No targets selected. Use --claude, --gemini, --opencode, or a combination.");
         process.exit(1);
     }
     const configPaths = writeClaude ? resolveClaudeConfigPaths() : [];
@@ -1096,17 +1146,19 @@ async function runSetup(args) {
             : {};
         const env = {
             ...existingEnv,
-            COSTHAWK_API_KEY: apiKey,
         };
+        delete env.COSTHAWK_API_KEY;
         if (process.env.COSTHAWK_API_URL) {
             env.COSTHAWK_API_URL = process.env.COSTHAWK_API_URL;
         }
         env.COSTHAWK_AUTO_SYNC = autoSync ? "true" : "false";
         if (autoSync) {
             env.COSTHAWK_CODEX_AUTO_SYNC = codexSync ? "true" : "false";
+            env.COSTHAWK_CURSOR_AUTO_SYNC = cursorSync ? "true" : "false";
         }
         else {
             env.COSTHAWK_CODEX_AUTO_SYNC = "false";
+            env.COSTHAWK_CURSOR_AUTO_SYNC = "false";
         }
         mcpServers.costhawk = {
             type: "stdio",
@@ -1148,13 +1200,14 @@ async function runSetup(args) {
             : {};
         const environment = {
             ...existingEnv,
-            COSTHAWK_API_KEY: apiKey,
         };
+        delete environment.COSTHAWK_API_KEY;
         if (process.env.COSTHAWK_API_URL) {
             environment.COSTHAWK_API_URL = process.env.COSTHAWK_API_URL;
         }
         environment.COSTHAWK_AUTO_SYNC = autoSync ? "true" : "false";
         environment.COSTHAWK_CODEX_AUTO_SYNC = autoSync && codexSync ? "true" : "false";
+        environment.COSTHAWK_CURSOR_AUTO_SYNC = autoSync && cursorSync ? "true" : "false";
         mcp.costhawk = {
             type: "local",
             command: ["npx", "--yes", "costhawk@latest"],
@@ -1164,10 +1217,57 @@ async function runSetup(args) {
         config.mcp = mcp;
         writeSecretJsonFile(openCodePath, config);
     }
+    let geminiPath = null;
+    if (writeGemini) {
+        geminiPath = resolveGeminiConfigPath();
+        const geminiDir = dirname(geminiPath);
+        if (!existsSync(geminiDir)) {
+            mkdirSync(geminiDir, { recursive: true });
+        }
+        let config = {};
+        if (existsSync(geminiPath)) {
+            try {
+                config = readJsonFile(geminiPath);
+            }
+            catch (error) {
+                console.error(`Error: Failed to parse ${geminiPath}. Fix the JSON and try again.`);
+                process.exit(1);
+            }
+        }
+        const mcpServers = typeof config.mcpServers === "object" && config.mcpServers !== null
+            ? config.mcpServers
+            : {};
+        const existingCosthawk = typeof mcpServers.costhawk === "object" && mcpServers.costhawk !== null
+            ? mcpServers.costhawk
+            : null;
+        const existingEnv = existingCosthawk && typeof existingCosthawk.env === "object" && existingCosthawk.env !== null
+            ? existingCosthawk.env
+            : {};
+        const env = {
+            ...existingEnv,
+        };
+        delete env.COSTHAWK_API_KEY;
+        if (process.env.COSTHAWK_API_URL) {
+            env.COSTHAWK_API_URL = process.env.COSTHAWK_API_URL;
+        }
+        env.COSTHAWK_AUTO_SYNC = autoSync ? "true" : "false";
+        env.COSTHAWK_CODEX_AUTO_SYNC = autoSync && codexSync ? "true" : "false";
+        env.COSTHAWK_CURSOR_AUTO_SYNC = autoSync && cursorSync ? "true" : "false";
+        mcpServers.costhawk = {
+            command: "npx",
+            args: ["-y", "costhawk@latest"],
+            env,
+        };
+        config.mcpServers = mcpServers;
+        writeSecretJsonFile(geminiPath, config);
+    }
     console.log("");
     if (writeClaude) {
         console.log("✅ CostHawk MCP server added to Claude Code!");
     }
+    if (writeGemini) {
+        console.log("✅ CostHawk MCP server added to Gemini CLI!");
+    }
     if (writeOpenCode) {
         console.log("✅ CostHawk MCP server added to OpenCode!");
     }
@@ -1178,14 +1278,22 @@ async function runSetup(args) {
     if (openCodePath) {
         console.log(`   OpenCode config: ${openCodePath}`);
     }
+    if (geminiPath) {
+        console.log(`   Gemini CLI config: ${geminiPath}`);
+    }
+    console.log(`   Stored auth: ${AUTH_STATE_PATH}`);
     console.log(`   Claude Code auto-sync: ${autoSync ? "enabled" : "disabled"}`);
     console.log(`   OpenAI Codex CLI auto-sync: ${autoSync && codexSync ? "enabled" : "disabled"}`);
-    console.log("   Note: Auto-sync only applies to local Claude Code / Codex CLI logs.");
+    console.log("   Note: Auto-sync only applies to local Claude Code / Codex CLI / Cursor logs. Gemini CLI gets MCP tools, but Gemini local transcripts are not auto-synced yet.");
     console.log("");
     if (writeClaude) {
         console.log("👉 Next step: Restart Claude Code, then ask:");
         console.log('   "What\'s my AI API usage this month?"');
     }
+    if (writeGemini) {
+        console.log("👉 Next step: Restart Gemini CLI, then run:");
+        console.log("   gemini mcp list");
+    }
     if (writeOpenCode) {
         console.log("👉 Next step: Restart OpenCode to load MCP servers.");
     }
@@ -1241,6 +1349,90 @@ async function syncSessionsToApi(sessions, options) {
     }
     return { sessionCount: allSessions.length, totalNew, totalUpdated, totalTokens };
 }
+// Cursor-specific sync helper. Cannot reuse `syncSessionsToApi` because the
+// Cursor parser emits a different shape than Claude Code / Codex:
+//   - no `projectHash`, has `workspaceHash`/`workspaceName` (both nullable)
+//   - nullable `startTime` / `endTime` (must be filtered out pre-send — the
+//     server schema rejects "none" timestampSource as unpersistable)
+//   - extra provenance fields: `timestampSource`, `timestampQuality`,
+//     `dailyUsageSource` at session level, plus per-row `source` on
+//     dailyUsage. These are required by the PR3/PR4 Zod schema on
+//     costcanary's `/api/mcp/usage/cursor` route.
+// The transform logic here MUST stay in lockstep with the transform in
+// the `costhawk_sync_cursor_usage` tool registration (below) so both
+// code paths send an identical wire shape.
+async function syncCursorSessionsToApi(sessions, options) {
+    // Client-side defense-in-depth: drop sessions the server would reject.
+    // timestampSource === "none" means the parser couldn't resolve either
+    // bubble-level or composer-level createdAt. CursorSession.startTime is
+    // NOT NULL on the backend so these would 400. Same filter as the
+    // costhawk_sync_cursor_usage tool.
+    const persistable = sessions.filter((s) => s.timestampSource !== "none" &&
+        s.startTime !== null &&
+        s.endTime !== null);
+    const totalRejected = sessions.length - persistable.length;
+    if (persistable.length === 0) {
+        return { sessionCount: 0, totalNew: 0, totalUpdated: 0, totalTokens: 0, totalRejected };
+    }
+    // Transform parser's Record<date, TokenUsage> into the wire
+    // Array<{date, ..., source}> shape expected by the API route.
+    const wireSessions = persistable.map((session) => {
+        const dailyUsageArray = Object.entries(session.dailyUsage).map(([date, tokens]) => ({
+            date,
+            inputTokens: tokens.inputTokens,
+            outputTokens: tokens.outputTokens,
+            cacheCreationTokens: tokens.cacheCreationTokens,
+            cacheReadTokens: tokens.cacheReadTokens,
+            source: session.dailyUsageSource === "none"
+                ? "bubble"
+                : session.dailyUsageSource,
+        }));
+        return {
+            sessionId: session.sessionId,
+            workspaceHash: session.workspaceHash,
+            workspaceName: session.workspaceName,
+            model: session.model,
+            inputTokens: session.tokens.inputTokens,
+            outputTokens: session.tokens.outputTokens,
+            cacheCreationTokens: session.tokens.cacheCreationTokens,
+            cacheReadTokens: session.tokens.cacheReadTokens,
+            messageCount: session.messageCount,
+            startTime: session.startTime,
+            endTime: session.endTime,
+            timestampSource: session.timestampSource,
+            timestampQuality: session.timestampQuality,
+            dailyUsageSource: session.dailyUsageSource,
+            dailyUsage: dailyUsageArray.length > 0 ? dailyUsageArray : undefined,
+            source: "cursor",
+        };
+    });
+    const BATCH_SIZE = 100;
+    let totalNew = 0;
+    let totalUpdated = 0;
+    let totalTokens = 0;
+    for (let i = 0; i < wireSessions.length; i += BATCH_SIZE) {
+        const batch = wireSessions.slice(i, i + BATCH_SIZE);
+        const result = await apiRequest("/api/mcp/usage/cursor", {
+            method: "POST",
+            apiKey: options.apiKey,
+            body: {
+                sessions: batch,
+                clientVersion: CLIENT_VERSION,
+                syncedAt: new Date().toISOString(),
+            },
+        });
+        totalNew += result.sessionsNew;
+        totalUpdated += result.sessionsUpdated;
+        totalTokens += result.totalTokens;
+    }
+    return {
+        sessionCount: wireSessions.length,
+        totalNew,
+        totalUpdated,
+        totalTokens,
+        totalRejected,
+    };
+}
 // Perform a one-time sync during --login so data appears in the dashboard immediately.
 async function performLoginSync(apiKey) {
     let totalSynced = 0;
@@ -1279,6 +1471,36 @@ async function performLoginSync(apiKey) {
             console.error(`   Warning: Codex sync failed: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    if (cursorDbExists()) {
+        try {
+            // parseCursorUsage() reads the whole Cursor SQLite in one pass. The
+            // LOGIN_SYNC_MAX_AGE_HOURS window is applied client-side below to
+            // avoid syncing sessions older than 30 days on first login. The
+            // parser itself doesn't accept a maxAgeHours param — we filter by
+            // resolved startTime here the same way the sync tool does.
+            const parseResult = parseCursorUsage();
+            const cutoffMs = Date.now() - LOGIN_SYNC_MAX_AGE_HOURS * 60 * 60 * 1000;
+            const recent = parseResult.sessions.filter((s) => {
+                if (s.startTime === null)
+                    return true; // defer to "none" filter inside helper
+                const startMs = Date.parse(s.startTime);
+                return Number.isFinite(startMs) && startMs >= cutoffMs;
+            });
+            const result = await syncCursorSessionsToApi(recent, {
+                apiKey,
+            });
+            totalSynced += result.sessionCount;
+            if (result.sessionCount > 0) {
+                console.log(`   Synced ${result.sessionCount} Cursor session${result.sessionCount === 1 ? "" : "s"}`);
+            }
+            if (result.totalRejected > 0) {
+                console.log(`   Skipped ${result.totalRejected} Cursor session${result.totalRejected === 1 ? "" : "s"} (no resolvable timestamp)`);
+            }
+        }
+        catch (error) {
+            console.error(`   Warning: Cursor sync failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
     if (totalSynced > 0) {
         console.log(`\n✅ ${totalSynced} session${totalSynced === 1 ? "" : "s"} synced to your CostHawk dashboard.`);
     }
@@ -1296,18 +1518,23 @@ async function runLoginCommand(args) {
         console.error(`Error: ${error instanceof Error ? error.message : "Browser login failed."}`);
         process.exit(1);
     }
+    persistApiKey(apiKey);
     if (shouldRunSetup) {
         const setupArgs = ["--api-key", apiKey];
         const passthroughFlags = [
             "--non-interactive",
             "--claude",
             "--no-claude",
+            "--gemini",
+            "--no-gemini",
             "--opencode",
             "--no-opencode",
             "--auto-sync",
             "--no-auto-sync",
             "--codex-sync",
             "--no-codex-sync",
+            "--cursor-sync",
+            "--no-cursor-sync",
         ];
         for (const flag of passthroughFlags) {
             if (args.includes(flag)) {
@@ -1321,9 +1548,10 @@ async function runLoginCommand(args) {
     }
     console.log("");
     console.log("✅ Login successful.");
-    console.log("   API key issued (masked):");
+    console.log("   Credentials saved locally (masked token):");
     console.log(`   COSTHAWK_API_KEY=${maskSecret(apiKey)}`);
     console.log("   Full token is intentionally not printed for security.");
+    console.log(`   Stored auth file: ${AUTH_STATE_PATH}`);
     console.log("");
     console.log("   Or run: npm exec --yes costhawk@latest -- --setup");
     console.log("");
@@ -1983,6 +2211,46 @@ function formatCodexSyncResultMarkdown(data) {
     }
     return truncateResponse(output);
 }
+function formatCursorSyncResultMarkdown(data) {
+    const statusEmoji = data.success ? "✅" : "❌";
+    let output = `# Cursor Sync Result\n\n`;
+    output += `${statusEmoji} ${data.message}\n\n`;
+    output += `| Metric | Value |\n|--------|-------|\n`;
+    if (data.dryRun) {
+        output += `| Dry Run | Yes (no data uploaded) |\n`;
+    }
+    if (data.sessionsParsed !== undefined) {
+        output += `| Sessions Parsed | ${data.sessionsParsed} |\n`;
+    }
+    output += `| New Sessions | ${data.sessionsNew} |\n`;
+    output += `| Updated Sessions | ${data.sessionsUpdated} |\n`;
+    if (data.sessionsRejected > 0) {
+        output += `| Rejected (no timestamp) | ${data.sessionsRejected} |\n`;
+    }
+    if (data.sessionsWithDailyUsage !== undefined) {
+        output += `| Sessions w/ Daily Usage | ${data.sessionsWithDailyUsage} |\n`;
+    }
+    if (data.dailyUsageRowsUpserted !== undefined) {
+        output += `| Daily Usage Rows Upserted | ${data.dailyUsageRowsUpserted} |\n`;
+    }
+    output += `| Total Tokens | ${formatTokens(data.totalTokens)} |\n`;
+    if (data.estimatedCost !== undefined) {
+        output += `| Estimated Cost | ${formatCost(data.estimatedCost)} |\n`;
+    }
+    if (data.filesRead && data.filesRead.length > 0) {
+        output += `\n## Files Read\n`;
+        for (const file of data.filesRead) {
+            output += `- ${file}\n`;
+        }
+    }
+    if (data.payloadPreview && data.payloadPreview.length > 0) {
+        output += `\n## Payload Preview (first ${data.payloadPreview.length})\n`;
+        output += "```json\n";
+        output += JSON.stringify(data.payloadPreview, null, 2);
+        output += "\n```\n";
+    }
+    return truncateResponse(output);
+}
 function formatCodexSessionsMarkdown(sessions) {
     if (sessions.length === 0) {
         return "# Codex Sessions\n\nNo sessions found. Make sure you have used Codex recently.";
@@ -2579,6 +2847,35 @@ const GetLocalCodexUsageSchema = {
         .describe("Only include sessions modified within this many hours (1-720, default 24)"),
     format: z.enum(["markdown", "json"]).optional().default("markdown").describe("Response format"),
 };
+const SyncCursorUsageSchema = {
+    apiKey: z
+        .string()
+        .optional()
+        .describe("Your CostHawk API key. If not provided, uses COSTHAWK_API_KEY environment variable."),
+    maxAgeHours: z
+        .number()
+        .min(1)
+        .max(720)
+        .optional()
+        .default(720)
+        .describe("Only sync sessions whose startTime falls within this many hours (1-720, default 720 = 30 days). Applied after parser output, before the 'none' timestamp filter."),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("If true, do not upload. Returns a local preview of what would be sent."),
+    previewLimit: z
+        .number()
+        .min(0)
+        .max(20)
+        .optional()
+        .default(3)
+        .describe("Number of sessions to include in the payload preview when dryRun is true"),
+    includeFileList: z
+        .boolean()
+        .optional()
+        .describe("Include the Cursor SQLite DB path in the response"),
+    format: z.enum(["markdown", "json"]).optional().default("markdown").describe("Response format"),
+};
 // Cursor usage schema. Three modes:
 //   - "usage" (default): per-session tokens with startTime/endTime/dailyUsage
 //     and timestamp provenance fields. Backward-compatible superset of the
@@ -3763,6 +4060,223 @@ server.registerTool("costhawk_sync_codex_usage", {
         };
     }
 });
+// ─── Cursor sync tool ───
+//
+// Parses the local Cursor SQLite and pushes per-session token counts +
+// timestamps + per-day breakdowns to CostHawk. Mirrors the Codex sync
+// tool pattern with three Cursor-specific deviations:
+//
+//   1. Filters out sessions with timestampSource === "none" client-side
+//      (the API route rejects these too as defense-in-depth; filtering
+//      here keeps the network payload small and surfaces the skip count
+//      in the user-facing result).
+//   2. Transforms the parser's dailyUsage Record<date, TokenUsage> into
+//      Array<{date, ..., source}> and attaches the session-level
+//      dailyUsageSource as the row-level source for every bucket.
+//   3. Applies maxAgeHours client-side (the Cursor parser reads the
+//      whole SQLite in one pass; there's no per-session file mtime to
+//      filter on, so we filter by parsed startTime >= cutoff).
+const CURSOR_DIR_NOT_FOUND_MESSAGE = "Error: Cursor SQLite database not found. Make sure Cursor is installed and you have used it at least once. Set COSTHAWK_CURSOR_DB_PATH to override the default path.";
+server.registerTool("costhawk_sync_cursor_usage", {
+    description: `Sync your local Cursor IDE usage to CostHawk. Parses the local Cursor SQLite (state.vscdb) and uploads token counts, models, timestamps, and per-day breakdowns to your CostHawk dashboard. Requires API key.\n\nIMPORTANT: Always display the COMPLETE output in your response using markdown tables. Never summarize or truncate.`,
+    inputSchema: SyncCursorUsageSchema,
+    annotations: WRITE_ANNOTATIONS,
+}, async (args, _extra) => {
+    const apiKey = getApiKey(args.apiKey);
+    if (!apiKey) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: No API key provided. You must first sign up at https://costhawk.ai to get an API key. Once approved, go to Settings > Developer > Create Token, then set COSTHAWK_API_KEY in your MCP configuration.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (!cursorDbExists()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: CURSOR_DIR_NOT_FOUND_MESSAGE,
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        const maxAgeHours = args.maxAgeHours ?? 720;
+        const dryRun = args.dryRun === true;
+        const previewLimit = args.previewLimit ?? 3;
+        const includeFileList = args.includeFileList === true;
+        const parseResult = parseCursorUsage();
+        const parserSessionCount = parseResult.sessions.length;
+        if (parserSessionCount === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No Cursor sessions with token data found at ${parseResult.filePath}. The database exists but no token-bearing bubbles were detected. Try having a few real conversations in Cursor first.`,
+                    },
+                ],
+            };
+        }
+        // Age filter (after parse, before "none" filter). maxAgeHours is
+        // applied against session.startTime when present. Sessions with
+        // null startTime (timestampSource === "none") cannot be age-
+        // filtered so they fall through to the "none" filter below and
+        // get rejected there regardless.
+        const cutoffMs = Date.now() - maxAgeHours * 60 * 60 * 1000;
+        const ageFiltered = parseResult.sessions.filter((s) => {
+            if (s.startTime === null)
+                return true; // defer to "none" filter
+            const startMs = Date.parse(s.startTime);
+            return Number.isFinite(startMs) && startMs >= cutoffMs;
+        });
+        // "none" filter — drops sessions where the parser could not
+        // resolve either bubble-level or composer-level timestamps. These
+        // cannot be persisted (CursorSession.startTime is NOT NULL on the
+        // backend) so we skip them locally and report the count.
+        const persistable = ageFiltered.filter((s) => s.timestampSource !== "none" &&
+            s.startTime !== null &&
+            s.endTime !== null);
+        const sessionsRejected = ageFiltered.length - persistable.length;
+        if (persistable.length === 0) {
+            const message = sessionsRejected > 0
+                ? `All ${sessionsRejected} age-filtered sessions rejected (no resolvable startTime/endTime).`
+                : `No Cursor sessions found within the last ${maxAgeHours} hours. Try increasing maxAgeHours or use Cursor first.`;
+            return {
+                content: [{ type: "text", text: message }],
+            };
+        }
+        // Transform parser's Record<date, TokenUsage> into the wire
+        // Array<{date, ..., source}> shape expected by the API route.
+        // Session-level dailyUsageSource is applied to every row since
+        // the parser doesn't track per-day provenance separately.
+        const allSessions = persistable.map((session) => {
+            const dailyUsageArray = Object.entries(session.dailyUsage).map(([date, tokens]) => ({
+                date,
+                inputTokens: tokens.inputTokens,
+                outputTokens: tokens.outputTokens,
+                cacheCreationTokens: tokens.cacheCreationTokens,
+                cacheReadTokens: tokens.cacheReadTokens,
+                source: session.dailyUsageSource === "none"
+                    ? "bubble"
+                    : session.dailyUsageSource,
+            }));
+            return {
+                sessionId: session.sessionId,
+                workspaceHash: session.workspaceHash,
+                workspaceName: session.workspaceName,
+                model: session.model,
+                inputTokens: session.tokens.inputTokens,
+                outputTokens: session.tokens.outputTokens,
+                cacheCreationTokens: session.tokens.cacheCreationTokens,
+                cacheReadTokens: session.tokens.cacheReadTokens,
+                messageCount: session.messageCount,
+                startTime: session.startTime,
+                endTime: session.endTime,
+                timestampSource: session.timestampSource,
+                timestampQuality: session.timestampQuality,
+                dailyUsageSource: session.dailyUsageSource,
+                dailyUsage: dailyUsageArray.length > 0 ? dailyUsageArray : undefined,
+                source: "cursor",
+            };
+        });
+        const filesRead = includeFileList
+            ? sanitizePathList([parseResult.filePath])
+            : undefined;
+        if (dryRun) {
+            const sessionsWithDailyUsage = allSessions.filter((session) => session.dailyUsage && session.dailyUsage.length > 0).length;
+            const totalTokens = allSessions.reduce((sum, session) => sum +
+                session.inputTokens +
+                session.outputTokens +
+                session.cacheCreationTokens +
+                session.cacheReadTokens, 0);
+            const result = {
+                success: true,
+                sessionsNew: 0,
+                sessionsUpdated: 0,
+                sessionsRejected,
+                sessionsParsed: allSessions.length,
+                totalTokens,
+                sessionsWithDailyUsage,
+                dryRun: true,
+                message: "Dry run - no data uploaded",
+                filesRead,
+                payloadPreview: previewLimit > 0 ? allSessions.slice(0, previewLimit) : [],
+            };
+            const text = args.format === "json"
+                ? JSON.stringify(result, null, 2)
+                : formatCursorSyncResultMarkdown(result);
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        const BATCH_SIZE = 100;
+        const batches = [];
+        for (let i = 0; i < allSessions.length; i += BATCH_SIZE) {
+            batches.push(allSessions.slice(i, i + BATCH_SIZE));
+        }
+        let totalNew = 0;
+        let totalUpdated = 0;
+        let totalServerRejected = 0;
+        let totalTokens = 0;
+        let sessionsWithDailyUsage = 0;
+        let dailyUsageRowsUpserted = 0;
+        for (const batch of batches) {
+            const payload = {
+                sessions: batch,
+                clientVersion: CLIENT_VERSION,
+                syncedAt: new Date().toISOString(),
+            };
+            const result = await apiRequest("/api/mcp/usage/cursor", {
+                method: "POST",
+                apiKey,
+                body: payload,
+            });
+            totalNew += result.sessionsNew;
+            totalUpdated += result.sessionsUpdated;
+            totalServerRejected += result.sessionsRejected || 0;
+            totalTokens += result.totalTokens;
+            sessionsWithDailyUsage += result.sessionsWithDailyUsage || 0;
+            dailyUsageRowsUpserted += result.dailyUsageRowsUpserted || 0;
+        }
+        // Client-side and server-side rejected counts should agree in
+        // normal flow (we filter first, server filters second as
+        // defense-in-depth). If the server rejected more than we did,
+        // surface the total so the user sees the real number.
+        const combinedRejected = Math.max(sessionsRejected, sessionsRejected + totalServerRejected);
+        const result = {
+            success: true,
+            sessionsNew: totalNew,
+            sessionsUpdated: totalUpdated,
+            sessionsRejected: combinedRejected,
+            sessionsParsed: allSessions.length,
+            totalTokens,
+            estimatedCost: 0,
+            sessionsWithDailyUsage: sessionsWithDailyUsage || undefined,
+            dailyUsageRowsUpserted: dailyUsageRowsUpserted || undefined,
+            message: combinedRejected > 0
+                ? `Synced ${totalNew} new and ${totalUpdated} updated sessions (${combinedRejected} skipped — no resolvable timestamp)`
+                : `Synced ${totalNew} new and ${totalUpdated} updated sessions`,
+            filesRead: includeFileList ? filesRead : undefined,
+        };
+        const text = args.format === "json"
+            ? JSON.stringify(result, null, 2)
+            : formatCursorSyncResultMarkdown(result);
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }],
+            isError: true,
+        };
+    }
+});
 server.registerTool("costhawk_get_local_codex_usage", {
     description: `Get Codex usage from local sessions WITHOUT uploading to CostHawk. Works offline. Shows token counts by type plus estimated retail cost.\n\nIMPORTANT: Always display the COMPLETE output in your response using markdown tables. Never summarize or truncate.`,
     inputSchema: GetLocalCodexUsageSchema,
@@ -4140,6 +4654,47 @@ async function performCodexAutoSync() {
         console.error(`[Codex Auto-sync] Error: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }
+// Auto-sync function for Cursor usage (optional)
+async function performCursorAutoSync() {
+    if (!CURSOR_AUTO_SYNC_ENABLED) {
+        return;
+    }
+    const apiKey = DEFAULT_API_KEY;
+    if (!apiKey) {
+        console.error("[Cursor Auto-sync] Skipped: No COSTHAWK_API_KEY configured");
+        return;
+    }
+    if (!cursorDbExists()) {
+        console.error("[Cursor Auto-sync] Skipped: Cursor state.vscdb not found");
+        return;
+    }
+    try {
+        // parseCursorUsage() has no maxAgeHours param — filter client-side
+        // by resolved startTime, same pattern as performLoginSync.
+        const parseResult = parseCursorUsage();
+        const cutoffMs = Date.now() - AUTO_SYNC_MAX_AGE_HOURS * 60 * 60 * 1000;
+        const recent = parseResult.sessions.filter((s) => {
+            if (s.startTime === null)
+                return true; // deferred to "none" filter in helper
+            const startMs = Date.parse(s.startTime);
+            return Number.isFinite(startMs) && startMs >= cutoffMs;
+        });
+        if (recent.length === 0) {
+            console.error("[Cursor Auto-sync] No sessions to sync");
+            return;
+        }
+        const result = await syncCursorSessionsToApi(recent, {
+            apiKey,
+        });
+        console.error(`[Cursor Auto-sync] Success: ${result.totalNew} new, ${result.totalUpdated} updated, ${formatTokens(result.totalTokens)} tokens`);
+        if (result.totalRejected > 0) {
+            console.error(`[Cursor Auto-sync] Skipped ${result.totalRejected} session${result.totalRejected === 1 ? "" : "s"} (no resolvable timestamp)`);
+        }
+    }
+    catch (error) {
+        console.error(`[Cursor Auto-sync] Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}
 // Start auto-sync interval
 function startAutoSync() {
     if (!AUTO_SYNC_ENABLED) {
@@ -4154,11 +4709,13 @@ function startAutoSync() {
     setTimeout(() => {
         performAutoSync();
         performCodexAutoSync();
+        performCursorAutoSync();
     }, 30 * 1000);
     // Then sync every 15 minutes
     autoSyncIntervalId = setInterval(() => {
         performAutoSync();
         performCodexAutoSync();
+        performCursorAutoSync();
     }, AUTO_SYNC_INTERVAL_MS);
     console.error(`[Auto-sync] Enabled: syncing every ${AUTO_SYNC_INTERVAL_MS / 60000} minutes`);
 }
@@ -4194,11 +4751,13 @@ OPTIONS:
   --no-open        With --login, skip auto-opening the browser
   --client-name    Optional device/client label for login approval screen
   --scopes         Optional comma-separated scopes for login token (default: mcp:read,mcp:write,otel:ingest)
-  --setup          Configure MCP settings (Claude Code / OpenCode)
+  --setup          Configure MCP settings (Claude Code / Gemini CLI / OpenCode)
   --opencode       Also write OpenCode config during setup
   --no-claude      Skip writing Claude Code config during setup
+  --no-gemini      Skip writing Gemini CLI config during setup
   --auto-sync      Enable Claude Code auto-sync (setup only)
   --codex-sync     Enable OpenAI Codex CLI auto-sync (setup only)
+  --cursor-sync    Enable Cursor IDE auto-sync (setup only)
   --api-key        Provide API key non-interactively (setup only)
   --non-interactive  Skip prompts and use defaults (setup only)
 
@@ -4207,14 +4766,18 @@ ENVIRONMENT VARIABLES:
   COSTHAWK_DEBUG                Set to "true" to log API requests
   COSTHAWK_AUTO_SYNC            Set to "true" to enable automatic local sync
   COSTHAWK_CODEX_AUTO_SYNC      Set to "false" to disable Codex auto-sync (requires COSTHAWK_AUTO_SYNC=true)
+  COSTHAWK_CURSOR_AUTO_SYNC     Set to "false" to disable Cursor auto-sync (requires COSTHAWK_AUTO_SYNC=true)
   COSTHAWK_CODEX_SESSIONS_DIR   Override Codex sessions directory (optional)
+  COSTHAWK_CURSOR_DB_PATH       Override Cursor state.vscdb path (optional)
 
 SETUP:
   1. Recommended (browser login + auto-setup):
      npm exec --yes costhawk@latest -- --login
-  2. Manual API key mode:
+  2. Manual API key mode (Claude Code):
      claude mcp add -s user -e COSTHAWK_API_KEY=your_key -e COSTHAWK_AUTO_SYNC=true costhawk -- npx --yes costhawk@latest
-  3. Interactive setup (writes Claude Code config, optional OpenCode):
+     Manual API key mode (Gemini CLI):
+     gemini mcp add -s user -e COSTHAWK_API_KEY=your_key costhawk npx --yes costhawk@latest
+  3. Interactive setup (writes Claude Code + Gemini CLI config, optional OpenCode):
      npm exec --yes costhawk@latest -- --setup --opencode
 
 DOCUMENTATION:
@@ -4248,7 +4811,11 @@ DOCUMENTATION:
                 exists: codexDirectoryExists(),
                 sampleFiles: codexSamples,
             },
-            note: "Only file metadata is listed here; transcripts are parsed locally.",
+            cursor: {
+                databasePath: sanitizePathForOutput(getCursorDbPath()),
+                exists: cursorDbExists(),
+            },
+            note: "Only file metadata is listed here; transcripts and Cursor state.vscdb are parsed locally.",
         };
         console.log(JSON.stringify(payload, null, 2));
         process.exit(0);
@@ -4265,11 +4832,13 @@ DOCUMENTATION:
                     hasApiKey: Boolean(DEFAULT_API_KEY),
                     autoSyncEnabled: AUTO_SYNC_ENABLED,
                     codexAutoSyncEnabled: CODEX_AUTO_SYNC_ENABLED,
+                    cursorAutoSyncEnabled: CURSOR_AUTO_SYNC_ENABLED,
                     debugEnabled: DEBUG_ENABLED,
                 },
                 local: {
                     claudeCodeDir: claudeCodeDirectoryExists(),
                     codexDir: codexDirectoryExists(),
+                    cursorDb: cursorDbExists(),
                 },
             };
             console.log(JSON.stringify(payload, null, 2));