@statforge/claudestat 1.7.0 → 1.8.0

package/README.md

@@ -282,7 +282,7 @@ Claude Code event
 ## Troubleshooting
 
 **`claudestat start` hangs for ~5 seconds**
-Normal — `require('express')` takes a few seconds on first load.
+Normal — `require('express')` takes a few seconds on first load. The daemon is running; wait for the "Daemon started" confirmation.
 
 **Hooks are not firing / dashboard shows no events**
 Run `claudestat doctor` — it checks every component and prints the exact fix command.
@@ -302,7 +302,38 @@ The daemon polls quota every 60s and logs warnings at 70%, 85%, and 95%. Check a
 **Working with multiple projects**
 claudestat tracks every project automatically. The Projects tab groups sessions by working directory.
 
----
+**Dashboard shows 0 cost / $0.00 for all sessions**
+Token data comes from Claude Code's JSONL files, not from hook events. Make sure Claude Code is writing JSONL logs — check `~/.claude/projects/` for `.jsonl` files. If the directory is empty, Claude Code may not have logging enabled.
+
+**Daemon stops after terminal closes**
+The daemon must be started with `nohup` to persist beyond the shell session:
+```bash
+nohup claudestat start &
+```
+Or use `claudestat setup` which installs a system service (launchd on macOS, systemd on Linux).
+
+**`claudestat export` produces empty output**
+If no sessions appear, the daemon may not have been running during your Claude Code sessions. Check `claudestat status` and restart with `claudestat start`. For historical data only (without a running daemon), export still reads from the local SQLite database — so past sessions captured while the daemon was running are always available.
+
+**Loop detector fires too often / not enough**
+Adjust the threshold and window:
+```bash
+claudestat config --loop-threshold 5   # default: 8 calls
+claudestat config --loop-window 90     # default: 120 seconds
+```
+
+**MCP server not responding**
+Restart the daemon (`claudestat restart`) and verify it's registered:
+```bash
+claude mcp list
+```
+If not listed, re-run: `claude mcp add claudestat -s user -- claudestat-mcp`
+
+**OpenCode sessions not appearing**
+claudestat reads OpenCode data from `~/.local/share/opencode/opencode.db`. If the file does not exist, OpenCode has not run yet or uses a different data path on your system. Run `opencode` at least once to initialize it.
+
+**Node.js experimental SQLite warning on startup**
+Expected — `node:sqlite` is experimental in Node 22. The warning is suppressed automatically. If you see it repeatedly, ensure you are running Node.js 22 or later (`node --version`).
 
 ## FAQ
 

package/dist/config.d.ts

@@ -32,6 +32,13 @@ export interface ClaudestatConfig {
     reportDay: number;
     reportTime: string;
     alertsEnabled: boolean;
+    killSwitchForce: boolean;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    port: number;
+    loopThreshold: number;
+    loopWindowSecs: number;
+    projectAliases: Record<string, string>;
+    webhookUrl: string | null;
 }
 /** Lee la config del disco. Valores ausentes se rellenan con defaults. */
 export declare function readConfig(): ClaudestatConfig;

package/dist/config.js

@@ -43,6 +43,13 @@ const DEFAULTS = {
     reportDay: 1,
     reportTime: '09:00',
     alertsEnabled: true,
+    killSwitchForce: false,
+    logLevel: 'info',
+    port: 7337,
+    loopThreshold: 8,
+    loopWindowSecs: 120,
+    projectAliases: {},
+    webhookUrl: null,
 };
 /** Lee la config del disco. Valores ausentes se rellenan con defaults. */
 function readConfig() {
@@ -100,6 +107,30 @@ function validateConfig(raw) {
     }
     if ('alertsEnabled' in cfg && typeof cfg.alertsEnabled !== 'boolean')
         return 'alertsEnabled debe ser boolean';
+    if ('killSwitchForce' in cfg && typeof cfg.killSwitchForce !== 'boolean')
+        return 'killSwitchForce must be boolean';
+    if ('logLevel' in cfg && !['debug', 'info', 'warn', 'error'].includes(cfg.logLevel))
+        return 'logLevel must be: debug, info, warn, error';
+    if ('loopThreshold' in cfg) {
+        const v = cfg.loopThreshold;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 2 || v > 50)
+            return 'loopThreshold must be an integer between 2 and 50';
+    }
+    if ('loopWindowSecs' in cfg) {
+        const v = cfg.loopWindowSecs;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 10 || v > 600)
+            return 'loopWindowSecs must be an integer between 10 and 600';
+    }
+    if ('projectAliases' in cfg) {
+        const v = cfg.projectAliases;
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return 'projectAliases must be an object { "/path": "Alias" }';
+    }
+    if ('webhookUrl' in cfg) {
+        const v = cfg.webhookUrl;
+        if (v !== null && (typeof v !== 'string' || (!v.startsWith('http://') && !v.startsWith('https://'))))
+            return 'webhookUrl must be null or a valid http/https URL';
+    }
     if ('reportsEnabled' in cfg && typeof cfg.reportsEnabled !== 'boolean')
         return 'reportsEnabled debe ser boolean';
     if ('reportFrequency' in cfg && !['weekly', 'biweekly', 'monthly'].includes(cfg.reportFrequency))
@@ -113,6 +144,11 @@ function validateConfig(raw) {
         if (typeof cfg.reportTime !== 'string' || !/^\d{2}:\d{2}$/.test(cfg.reportTime))
             return 'reportTime debe tener formato HH:MM';
     }
+    if ('port' in cfg) {
+        const v = cfg.port;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 1024 || v > 65535)
+            return 'port must be an integer between 1024 and 65535';
+    }
     return null;
 }
 /** Devuelve el nivel de warning para un % dado, o null si no alcanza ningún threshold. */

package/dist/daemon.js

@@ -75,7 +75,8 @@ const projects_cache_1 = require("./cache/projects-cache");
 const rate_limiter_1 = require("./middleware/rate-limiter");
 const summarizer_1 = require("./summarizer");
 const paths_1 = require("./paths");
-const PORT = 7337;
+const logger_1 = require("./logger");
+const PORT = (0, config_1.readConfig)().port;
 const app = (0, express_1.default)();
 app.use(express_1.default.json());
 // ─── Shutdown graceful (cross-platform, no depende de SIGTERM) ────────────────
@@ -131,7 +132,7 @@ function migrateSessionProjects() {
         }
     }
     if (tagged > 0)
-        console.log(`[daemon] ${tagged} sessions tagged with project`);
+        logger_1.logger.info(`${tagged} sessions tagged with project`);
 }
 /**
  * Genera summaries IA para las últimas N sesiones que no tienen uno.
@@ -148,11 +149,11 @@ async function migrateSessionSummaries(limit = 5) {
             const summary = await (0, summarizer_1.summarizeSession)(events, s.total_cost_usd ?? 0, projectName);
             if (summary) {
                 db_1.dbOps.updateSessionSummary(s.id, summary);
-                console.log(`[daemon] Summary generated for session ${s.id.slice(0, 8)}: "${summary}"`);
+                logger_1.logger.info(`Summary generated for session ${s.id.slice(0, 8)}: "${summary}"`);
             }
         }
         catch (err) {
-            console.error('[daemon] Error generating summary:', err);
+            logger_1.logger.error(`Error generating summary: ${err}`);
         }
     }
 }
@@ -206,6 +207,7 @@ function checkAlertLevel(level, lastLevel, logMsg, notifTitle, notifBody) {
     const prevRank = lastLevel ? LEVEL_RANK[lastLevel] ?? 0 : 0;
     const currRank = LEVEL_RANK[level];
     if (currRank > prevRank) {
+        logger_1.logger.warn(logMsg);
         process.stderr.write(`${LEVEL_COLOR[level]}${logMsg}\x1b[0m\n`);
         (0, notifier_1.sendDesktopNotification)(notifTitle, notifBody);
     }
@@ -220,9 +222,37 @@ function startAlertPolling() {
             const data = (0, quota_tracker_1.computeQuota)(cfg.plan ?? undefined);
             const resetMins = Math.ceil(data.cycleResetMs / 60000);
             // ── Cycle 5h alerts ──────────────────────────────────────────────────────
-            _lastCycleAlertLevel = checkAlertLevel((0, config_1.getWarnLevel)(data.cyclePct, cfg.warnThresholds), _lastCycleAlertLevel, `[claudestat] ⚠️  5h cycle at ${data.cyclePct}% (${data.cyclePrompts}/${data.cycleLimit} prompts)`, 'claudestat — 5h cycle alert', `${data.cyclePct}% of cycle used · resets in ${resetMins}m`);
+            const cycleLevel = (0, config_1.getWarnLevel)(data.cyclePct, cfg.warnThresholds);
+            if (cycleLevel && cycleLevel !== _lastCycleAlertLevel) {
+                const webhookUrl = (0, config_1.readConfig)().webhookUrl;
+                if (webhookUrl) {
+                    (0, notifier_1.sendWebhookAlert)(webhookUrl, {
+                        title: 'claudestat — 5h cycle alert',
+                        body: `${data.cyclePct}% of cycle used · resets in ${resetMins}m`,
+                        level: cycleLevel,
+                        cyclePct: data.cyclePct,
+                        resetInMins: resetMins,
+                        burnRate: data.burnRateTokensPerMin,
+                    });
+                }
+            }
+            _lastCycleAlertLevel = checkAlertLevel(cycleLevel, _lastCycleAlertLevel, `[claudestat] ⚠️  5h cycle at ${data.cyclePct}% (${data.cyclePrompts}/${data.cycleLimit} prompts)`, 'claudestat — 5h cycle alert', `${data.cyclePct}% of cycle used · resets in ${resetMins}m`);
             // ── Weekly alerts ────────────────────────────────────────────────────────
-            _lastWeeklyAlertLevel = checkAlertLevel((0, config_1.getWarnLevel)(data.weeklyPctAll, cfg.weeklyWarnThresholds), _lastWeeklyAlertLevel, `[claudestat] ⚠️  Weekly usage at ${data.weeklyPctAll}%`, 'claudestat — Weekly usage alert', `${data.weeklyPctAll}% of weekly quota used`);
+            const weeklyLevel = (0, config_1.getWarnLevel)(data.weeklyPctAll, cfg.weeklyWarnThresholds);
+            if (weeklyLevel && weeklyLevel !== _lastWeeklyAlertLevel) {
+                const webhookUrl = (0, config_1.readConfig)().webhookUrl;
+                if (webhookUrl) {
+                    (0, notifier_1.sendWebhookAlert)(webhookUrl, {
+                        title: 'claudestat — Weekly usage alert',
+                        body: `${data.weeklyPctAll}% of weekly quota used`,
+                        level: weeklyLevel,
+                        cyclePct: data.cyclePct,
+                        weeklyPct: data.weeklyPctAll,
+                        resetInMins: resetMins,
+                    });
+                }
+            }
+            _lastWeeklyAlertLevel = checkAlertLevel(weeklyLevel, _lastWeeklyAlertLevel, `[claudestat] ⚠️  Weekly usage at ${data.weeklyPctAll}%`, 'claudestat — Weekly usage alert', `${data.weeklyPctAll}% of weekly quota used`);
             // ── Reset reminder ───────────────────────────────────────────────────────
             const reminderMs = (cfg.resetReminderMins ?? 10) * 60000;
             if (reminderMs > 0) {
@@ -231,11 +261,28 @@ function startAlertPolling() {
                 }
                 else if (data.cycleResetMs <= reminderMs && data.cycleResetMs > 0 && !_resetReminderFired) {
                     const mins = Math.ceil(data.cycleResetMs / 60000);
+                    logger_1.logger.info(`Quota resets in ${mins}m — good time to wrap up`);
                     process.stderr.write(`\x1b[36m[claudestat] ⏰  Quota resets in ${mins}m — good time to wrap up\x1b[0m\n`);
                     (0, notifier_1.sendDesktopNotification)('claudestat — Quota reset soon', `Your 5h cycle resets in ${mins} min — good time to start a new task`);
                     _resetReminderFired = true;
                 }
             }
+            // Write or remove pause signal file based on kill switch state
+            const signalFile = (0, paths_1.getPauseSignalFile)();
+            if (cfg.killSwitchEnabled && data.cyclePct >= cfg.killSwitchThreshold) {
+                const msg = `Quota at ${data.cyclePct}% — threshold is ${cfg.killSwitchThreshold}%. Resets in ${Math.ceil(data.cycleResetMs / 60000)}m.`;
+                try {
+                    fs_1.default.writeFileSync(signalFile, msg);
+                }
+                catch { }
+                (0, stream_1.broadcast)({ type: 'kill_switch', payload: { blocked: true, reason: msg } });
+            }
+            else {
+                try {
+                    fs_1.default.unlinkSync(signalFile);
+                }
+                catch { }
+            }
         }
         catch {
             // quota read failed — ignore
@@ -262,6 +309,7 @@ function cleanPid() {
 function startDaemon() {
     _server = app.listen(PORT, '127.0.0.1', () => {
         writePid();
+        (0, paths_1.writePortFile)(PORT);
         process.on('exit', cleanPid);
         process.on('SIGTERM', () => { if (_server)
             shutdown(_server); process.exit(0); });
@@ -289,7 +337,7 @@ function startDaemon() {
         // Se ejecuta en background para no retrasar el inicio del servidor
         setImmediate(() => {
             const projects = (0, projects_cache_1.getProjectsCached)();
-            console.log(`[daemon] ${projects?.length ?? 0} projects scanned`);
+            logger_1.logger.info(`${projects?.length ?? 0} projects scanned`);
         });
         // Refresh automático del cache de proyectos cada 2 minutos
         // Recoge cambios en HANDOFF.md aunque el daemon lleve horas corriendo
@@ -311,7 +359,7 @@ function startDaemon() {
                 return; // ya existe
             const markdown = (0, reports_1.generateReport)(dateLabel, cfg);
             db_1.dbOps.insertWeeklyReport(dateLabel, markdown);
-            console.log(`[daemon] Report auto-generated: ${dateLabel}`);
+            logger_1.logger.info(`Report auto-generated: ${dateLabel}`);
         }, 60000);
         // Al arrancar: liberar intents activos de sesiones anteriores (ya no hay nadie que los use)
         db_1.dbOps.releaseOrphanedIntents();

package/dist/db.d.ts

@@ -176,6 +176,17 @@ export declare const dbOps: {
         week_start: number;
         week_end: number;
     };
+    getPrevWeekInsight(): {
+        total_sessions: any;
+        total_cost: any;
+        input_tokens: any;
+        output_tokens: any;
+        cache_read: any;
+        total_loops: any;
+        avg_efficiency: any;
+        week_start: any;
+        week_end: any;
+    };
     setMeta(key: string, value: string): void;
     getMeta(key: string): string | undefined;
     getCostProjection(days?: number): {

package/dist/db.js

@@ -719,6 +719,36 @@ exports.dbOps = {
         const since = Date.now() - days * 86400000;
         return stmts.getWeeklyInsight.get(since);
     },
+    getPrevWeekInsight() {
+        const now = Date.now();
+        const weekEnd = now - 7 * 86400000;
+        const weekStart = now - 14 * 86400000;
+        const row = db.prepare(`
+      SELECT
+        COUNT(*)                               AS total_sessions,
+        COALESCE(SUM(total_cost_usd), 0)       AS total_cost,
+        COALESCE(SUM(total_input_tokens), 0)   AS input_tokens,
+        COALESCE(SUM(total_output_tokens), 0)  AS output_tokens,
+        COALESCE(SUM(total_cache_read), 0)     AS cache_read,
+        COALESCE(SUM(loops_detected), 0)       AS total_loops,
+        COALESCE(AVG(efficiency_score), 100)   AS avg_efficiency,
+        MIN(started_at)                        AS week_start,
+        MAX(started_at)                        AS week_end
+      FROM sessions
+      WHERE started_at >= ? AND started_at < ?
+    `).get(weekStart, weekEnd);
+        return {
+            total_sessions: row.total_sessions ?? 0,
+            total_cost: row.total_cost ?? 0,
+            input_tokens: row.input_tokens ?? 0,
+            output_tokens: row.output_tokens ?? 0,
+            cache_read: row.cache_read ?? 0,
+            total_loops: row.total_loops ?? 0,
+            avg_efficiency: row.avg_efficiency ?? 100,
+            week_start: row.week_start ?? weekStart,
+            week_end: row.week_end ?? null,
+        };
+    },
     setMeta(key, value) {
         stmts.upsertMeta.run(key, value);
     },

package/dist/doctor.js

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDoctor = runDoctor;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const paths_1 = require("./paths");
+const config_1 = require("./config");
 async function runDoctor() {
     const checks = [];
     const G = '\x1b[32m✓\x1b[0m';
@@ -66,15 +68,16 @@ async function runDoctor() {
         fix: hookOk ? undefined : 'claudestat install',
     });
     // 6. Daemon reachable
+    const cfgPort = (0, config_1.readConfig)().port;
     const daemonOk = await (async () => { try {
-        const res = await fetch('http://localhost:7337/health');
+        const res = await fetch(`http://localhost:${cfgPort}/health`);
         return res.ok;
     }
     catch {
         return false;
     } })();
     checks.push({
-        label: 'Daemon running (localhost:7337)',
+        label: 'Daemon running (localhost:' + cfgPort + ')',
         ok: daemonOk,
         fix: daemonOk ? undefined : 'claudestat start',
     });
@@ -166,6 +169,21 @@ async function runDoctor() {
                 `nvm use default && npm install -g @statforge/claudestat\n       Then restart terminal`,
         });
     }
+    // 12. Daemon service node matches current node (only if service file exists)
+    if (process.platform === 'darwin') {
+        const plistPath = path_1.default.join(process.env.HOME ?? os_1.default.homedir(), 'Library', 'LaunchAgents', 'com.statforge.claudestat.plist');
+        if (fs_1.default.existsSync(plistPath)) {
+            const plistContent = fs_1.default.readFileSync(plistPath, 'utf8');
+            const currentNode = process.execPath;
+            const nodeOk = plistContent.includes(currentNode);
+            checks.push({
+                label: 'Daemon service uses current Node binary',
+                ok: nodeOk,
+                note: nodeOk ? undefined : `Service file uses a different node than ${currentNode}`,
+                fix: nodeOk ? undefined : 'claudestat setup --uninstall && claudestat setup',
+            });
+        }
+    }
     // 11. MCP server registered in Claude Code
     let mcpOk = false;
     let mcpNote;

package/dist/export.d.ts

@@ -1,7 +1,8 @@
 export interface ExportOpts {
-    format: 'json' | 'csv';
+    format: 'json' | 'csv' | 'markdown';
     from?: string;
     to?: string;
+    since?: string;
     project?: string;
     output?: string;
 }

package/dist/export.js

@@ -5,9 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runExport = runExport;
 const fs_1 = __importDefault(require("fs"));
-const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const db_1 = require("./db");
+const MD_HEADERS = ['Date', 'Project', 'Cost (USD)', 'Input tokens', 'Output tokens', 'Efficiency', 'Loops'];
 function parseDate(str, endOfDay = false) {
     const ms = Date.parse(str);
     if (isNaN(ms))
@@ -23,6 +23,23 @@ const CSV_HEADERS = [
     'total_cost_usd', 'total_input_tokens', 'total_output_tokens',
     'efficiency_score', 'loops_detected',
 ];
+function parseSince(since) {
+    const match = since.match(/^(\d+)d$/);
+    if (!match)
+        throw new Error(`Invalid --since format: "${since}" — use e.g. "7d" or "30d"`);
+    return Date.now() - parseInt(match[1], 10) * 86400000;
+}
+function toMarkdownRow(r) {
+    return [
+        String(r.started_at).slice(0, 10),
+        r.project_path ? String(r.project_path).split('/').pop() ?? '—' : '—',
+        `$${Number(r.total_cost_usd).toFixed(4)}`,
+        String(r.total_input_tokens),
+        String(r.total_output_tokens),
+        `${r.efficiency_score}/100`,
+        String(r.loops_detected),
+    ].map(v => v.replace(/\|/g, '\\|')).join(' | ');
+}
 function toRow(s) {
     return {
         id: s.id,
@@ -40,6 +57,10 @@ function runExport(opts) {
     let fromMs;
     let toMs;
     try {
+        if (opts.since && !opts.from) {
+            const sinceMs = parseSince(opts.since);
+            opts.from = new Date(sinceMs).toISOString().slice(0, 10);
+        }
         if (opts.from)
             fromMs = parseDate(opts.from);
         if (opts.to)
@@ -71,12 +92,26 @@ function runExport(opts) {
         ];
         output = lines.join('\n') + '\n';
     }
+    else if (opts.format === 'markdown') {
+        const separator = MD_HEADERS.map(() => '---').join(' | ');
+        const lines = [
+            MD_HEADERS.join(' | '),
+            separator,
+            ...rows.map(toMarkdownRow),
+        ];
+        output = lines.join('\n') + '\n';
+    }
     else {
         output = JSON.stringify(rows, null, 2) + '\n';
     }
-    const date = new Date().toISOString().slice(0, 10);
-    const dest = path_1.default.resolve(opts.output ?? path_1.default.join(os_1.default.homedir(), 'Downloads', `claudestat-export-${date}.${opts.format}`));
-    fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
-    fs_1.default.writeFileSync(dest, output);
-    console.log(`✓ Exported ${rows.length} session(s) → ${dest}`);
+    if (!opts.output) {
+        process.stdout.write(output);
+        console.error(`✓ Exported ${rows.length} session(s)`); // stderr para no contaminar stdout
+    }
+    else {
+        const dest = path_1.default.resolve(opts.output);
+        fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+        fs_1.default.writeFileSync(dest, output);
+        console.log(`✓ Exported ${rows.length} session(s) → ${dest}`);
+    }
 }