costhawk 1.5.14 → 1.5.16

package/README.md

@@ -168,9 +168,13 @@ COSTHAWK_GIT_SHA=$(git rev-parse --short HEAD) npm run build
 | Tool | Description |
 |------|-------------|
 | `costhawk_get_usage_summary` | Get usage and costs over a time period (by provider/model) |
-| `costhawk_get_usage_by_tag` | Get usage grouped by custom tags (user_id, feature, etc.) |
+| `costhawk_get_usage_by_tag` | Get usage grouped by attribution fields and custom metadata (`project`, `feature`, `team`, `environment`, `user_id`, etc.) |
 | `costhawk_detect_anomalies` | Check for cost anomalies and unusual usage patterns |
 
+`costhawk_get_usage_by_tag` has two data sources:
+- Standard attribution fields like `feature`, `project`, `team`, and `environment` can come from wrapped-key or scoped API key attribution.
+- Arbitrary custom tag keys only appear when you send request metadata through the proxy, such as `costhawk_metadata.feature` or `costhawk_metadata.user_id`.
+
 ### Claude Code Local Tracking (Optional Auto-Sync)
 
 These tools parse your local Claude Code transcripts from `~/.claude/projects/` to track token usage - including the 4 token types Claude Code uses.

package/dist/build-info.d.ts

@@ -1,2 +1,2 @@
-export declare const BUILD_COMMIT_SHA = "5009d40";
+export declare const BUILD_COMMIT_SHA = "7a15693";
 //# sourceMappingURL=build-info.d.ts.map

package/dist/build-info.js

@@ -1,3 +1,3 @@
 // Auto-generated during release builds. Values may be empty in dev.
-export const BUILD_COMMIT_SHA = "5009d40";
+export const BUILD_COMMIT_SHA = "7a15693";
 //# sourceMappingURL=build-info.js.map

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",
@@ -74,6 +78,40 @@ const WEBHOOK_TYPES = ["SLACK", "DISCORD", "TEAMS", "PAGERDUTY", "CUSTOM"];
 function getApiKey(providedKey) {
     return providedKey || DEFAULT_API_KEY || null;
 }
+function extractApiErrorMessage(errorText) {
+    const trimmed = errorText.trim();
+    if (!trimmed)
+        return "Unknown API error";
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
+            return parsed.error;
+        }
+        if (typeof parsed.error_description === "string" && parsed.error_description.trim().length > 0) {
+            return parsed.error_description;
+        }
+    }
+    catch {
+        // Fall through to the raw response body.
+    }
+    return trimmed;
+}
+function formatApiErrorMessage(status, errorText) {
+    const message = extractApiErrorMessage(errorText);
+    const reconnect = "Reconnect CostHawk by running `npm exec --yes costhawk@latest -- --login`, then restart your MCP client.";
+    if (status === 401) {
+        if (/revoked/i.test(message)) {
+            return `Your CostHawk connection token was revoked. ${reconnect}`;
+        }
+        if (/expired/i.test(message)) {
+            return `Your CostHawk connection token expired. ${reconnect}`;
+        }
+        if (/invalid api key|invalid authorization|missing or invalid authorization/i.test(message)) {
+            return `Your CostHawk connection is not authorized. ${reconnect}`;
+        }
+    }
+    return `CostHawk API error (${status}): ${message}`;
+}
 // Helper to resolve period to date range
 function resolvePeriod(period, startDate, endDate) {
     // Explicit dates override period
@@ -359,7 +397,7 @@ async function apiRequest(endpoint, options) {
         });
         if (!response.ok) {
             const error = await response.text();
-            throw new Error(`CostHawk API error (${response.status}): ${error}`);
+            throw new Error(formatApiErrorMessage(response.status, error));
         }
         return response.json();
     }
@@ -737,6 +775,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 +921,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 +1070,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 +1099,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 +1126,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 +1148,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 +1180,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 +1234,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 +1251,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 +1312,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 +1383,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 +1505,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 +1552,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 +1582,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("");
@@ -1332,7 +1594,8 @@ async function runLoginCommand(args) {
 }
 // Markdown formatters
 function formatUsageSummaryMarkdown(data) {
-    let output = `# Usage Summary\n\n`;
+    let output = `# API Usage Summary\n\n`;
+    output += `This report covers CostHawk-tracked API requests from wrapped/proxied keys and provider-ingested API usage. It does not include local Claude Code, Codex, or Cursor sessions; use the local usage, sync, ROI, or savings tools for those.\n\n`;
     output += `**Period:** ${data.period.start} to ${data.period.end}\n\n`;
     output += `## Overview\n`;
     output += `| Metric | Value |\n|--------|-------|\n`;
@@ -1340,6 +1603,9 @@ function formatUsageSummaryMarkdown(data) {
     output += `| Total API Calls | ${formatNumber(data.totalCalls)} |\n`;
     output += `| Input Tokens | ${formatNumber(data.totalInputTokens)} |\n`;
     output += `| Output Tokens | ${formatNumber(data.totalOutputTokens)} |\n\n`;
+    if (data.totalCalls === 0 && data.totalInputTokens === 0 && data.totalOutputTokens === 0) {
+        output += `No API-request usage was recorded for this period. This does not mean local AI-tool usage is zero; Claude Code, Codex, and Cursor are tracked in separate local-tool reports.\n\n`;
+    }
     output += `## By Provider\n`;
     output += `| Provider | Cost | Calls |\n|----------|------|-------|\n`;
     for (const [provider, stats] of Object.entries(data.byProvider)) {
@@ -2697,7 +2963,7 @@ const ListIntegrationsSchema = {
 };
 // Register tools
 server.registerTool("costhawk_get_usage_summary", {
-    description: `Get a summary of your AI API usage and costs over a time period. Returns total costs, API calls, and token usage broken down by provider and model. Supports preset periods (last_24h, today, yesterday, last_7d, last_30d) or custom date ranges.\n\nIMPORTANT: Always display the COMPLETE output in your response using markdown tables. Render every section (Overview, By Provider, By Model). Never summarize or truncate.`,
+    description: `Get a summary of CostHawk-tracked API request usage over a time period. This covers wrapped/proxied keys and provider-ingested API usage stored as API requests. It does NOT include local Claude Code, Codex, or Cursor sessions; for local AI-tool token usage, use costhawk_get_local_claude_code_usage, costhawk_get_local_codex_usage, costhawk_get_local_cursor_usage, costhawk_get_local_roi_report, or costhawk_get_savings after syncing. Returns total API costs, API calls, and API token usage broken down by provider and model. Supports preset periods (last_24h, today, yesterday, last_7d, last_30d) or custom date ranges.\n\nIMPORTANT: Always display the COMPLETE output in your response using markdown tables. Render every section (Overview, By Provider, By Model). Never summarize or truncate. If this report is zero, do not say the user's local AI-tool usage is zero; explain that local Claude Code, Codex, and Cursor usage is reported separately.`,
     inputSchema: UsageSummarySchema,
     annotations: READ_ONLY_ANNOTATIONS,
 }, async (args, _extra) => {
@@ -4370,7 +4636,7 @@ server.registerTool("costhawk_list_integrations", {
 async function performAutoSync() {
     const apiKey = DEFAULT_API_KEY;
     if (!apiKey) {
-        console.error("[Auto-sync] Skipped: No COSTHAWK_API_KEY configured");
+        console.error("[Auto-sync] Skipped: No CostHawk auth token found. Run `npm exec --yes costhawk@latest -- --login`.");
         return;
     }
     if (!claudeCodeDirectoryExists()) {
@@ -4401,7 +4667,7 @@ async function performCodexAutoSync() {
     }
     const apiKey = DEFAULT_API_KEY;
     if (!apiKey) {
-        console.error("[Codex Auto-sync] Skipped: No COSTHAWK_API_KEY configured");
+        console.error("[Codex Auto-sync] Skipped: No CostHawk auth token found. Run `npm exec --yes costhawk@latest -- --login`.");
         return;
     }
     if (!codexDirectoryExists()) {
@@ -4426,6 +4692,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 auth token found. Run `npm exec --yes costhawk@latest -- --login`.");
+        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) {
@@ -4433,18 +4740,20 @@ function startAutoSync() {
         return;
     }
     if (!DEFAULT_API_KEY) {
-        console.error("[Auto-sync] Disabled: No COSTHAWK_API_KEY configured");
+        console.error("[Auto-sync] Disabled: No CostHawk auth token found. Run `npm exec --yes costhawk@latest -- --login`.");
         return;
     }
     // Perform initial sync after 30 seconds (give server time to fully start)
     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`);
 }
@@ -4480,11 +4789,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)
 
@@ -4493,14 +4804,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:
@@ -4534,7 +4849,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);
@@ -4551,11 +4870,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));