@statforge/claudestat 1.3.0 → 1.4.0

package/README.md

@@ -118,40 +118,43 @@ Claude Code event
 ## Installation
 
 ```bash
-npm install -g @statforge/claudestat
+npm install -g @statforge/claudestat && claudestat setup
 ```
 
+`claudestat setup` installs the Claude Code hooks and registers the daemon as a system service (launchd on macOS, systemd on Linux) — no sudo required. The daemon starts automatically whenever you log in.
+
 > **Using NVM?** Make sure you're on your default Node version before installing to avoid stale binary conflicts:
 > ```bash
 > nvm use default && npm install -g @statforge/claudestat
+> claudestat setup
 > ```
 > Works with [nvm](https://github.com/nvm-sh/nvm) (macOS/Linux) and [nvm-windows](https://github.com/coreybutler/nvm-windows).
 
-Then wire up the hooks into Claude Code:
+> Restart Claude Code after setup so the hooks take effect.
 
-```bash
-claudestat install
-```
+### Manual setup (alternative)
 
-This modifies `~/.claude/settings.json` to add `SessionStart`, `PreToolUse`, `PostToolUse`, and `Stop` hooks. A backup is created before any change.
+If you prefer to manage the daemon yourself:
 
-> Restart Claude Code after installing so the hooks take effect.
+```bash
+npm install -g @statforge/claudestat
+claudestat install   # installs hooks into Claude Code
+claudestat start     # start the daemon manually
+```
 
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Start the background daemon
-claudestat start
+# 1. Install and set up everything in one command
+npm install -g @statforge/claudestat && claudestat setup
 
 # 2. Open the dashboard in your browser
 #    macOS:
 open http://localhost:7337
-#    Windows:
-start http://localhost:7337
-#    Linux:
-xdg-open http://localhost:7337
+#    Windows / Linux:
+claudestat start   # start daemon manually, then open http://localhost:7337
 
 # 3. Or watch a live terminal trace
 claudestat watch
@@ -165,7 +168,9 @@ That's it. Start a Claude Code session and watch the events flow in.
 
 | Command | Description |
 |---|---|
-| `claudestat start` | Start the background daemon |
+| `claudestat setup` | One-command setup: install hooks + register daemon as system service |
+| `claudestat setup --uninstall` | Remove hooks and system service |
+| `claudestat start` | Start the background daemon manually |
 | `claudestat stop` | Stop the daemon |
 | `claudestat restart` | Restart the daemon |
 | `claudestat install` | Install hooks into Claude Code |
@@ -432,8 +437,9 @@ claudestat doctor
   ✓  Daemon running (localhost:7337)
   ✓  Global CLI symlink valid
   ✓  No duplicate claudestat binaries in PATH
-  ✓  Version match (installed: v1.2.2)
+  ✓  Version match (installed: v1.3.0)
   ✓  NVM prefix matches active binary
+  ✓  MCP server registered in Claude Code
 ──────────────────────────────────────────────
   All checks passed — claudestat is healthy!
 ```
@@ -449,11 +455,11 @@ Shows the current version and checks npm for updates.
 ```bash
 claudestat version
 
-1.2.2
+1.3.0
   latest ✓
 ```
 
-If a newer version is available, it shows: `latest: 1.3.0 — run npm update`.
+If a newer version is available, it shows: `latest: 1.4.0 — run npm update`.
 
 ### `claudestat export`
 
@@ -513,7 +519,7 @@ Once registered, ask Claude things like:
 
 ![claudestat MCP demo](https://raw.githubusercontent.com/DeibyGS/claudestat/main/assets/mcp-demo.gif)
 
-Zero extra dependencies — stdio JSON-RPC, works without the daemon running. Uses on-demand API refresh with shared disk cache for accurate quota data.
+Zero extra dependencies — stdio JSON-RPC. Works without the daemon running (reads SQLite directly), but will warn you to start it if it's not active: `claudestat start`. Uses on-demand API refresh with shared disk cache for accurate quota data.
 
 ---
 
@@ -648,15 +654,19 @@ Have an idea? [Open an issue](https://github.com/DeibyGS/claudestat/issues) or s
 ## Uninstall
 
 ```bash
-claudestat uninstall        # removes hooks from Claude Code settings
+# Full uninstall (hooks + system service + daemon):
+claudestat setup --uninstall
 
+# Then remove the data directory:
 # macOS / Linux:
-rm -rf ~/.claudestat        # removes DB, config, and PID file
+rm -rf ~/.claudestat
 
 # Windows (PowerShell):
 Remove-Item -Recurse -Force "$env:USERPROFILE\.claudestat"
 ```
 
+> If you installed manually (without `setup`), use `claudestat uninstall` to remove only the hooks.
+
 ---
 
 ## Contributing
@@ -712,7 +722,7 @@ Want to appear here? Pick a [good-first-issue](https://github.com/DeibyGS/claude
 claudestat is a real-time monitor for Claude Code — not a log reader. It hooks into every tool call as it fires, tracks token usage and cost live, guards your quota with configurable alerts, and exposes an MCP server so Claude can answer questions about its own usage. ccusage reads JSONL history after sessions end; claudestat runs while you code.
 
 **How do I monitor Claude Code token usage?**
-Install with `npm install -g @statforge/claudestat`, run `claudestat start`, and open `http://localhost:7337` for the live dashboard.
+Install with `npm install -g @statforge/claudestat && claudestat setup`, then open `http://localhost:7337` for the live dashboard. The daemon starts automatically on login after setup.
 
 **How do I track Claude Code costs?**
 claudestat records every session's token usage and estimates API cost per tool call.

package/dist/config.d.ts

@@ -25,6 +25,7 @@ export interface ClaudestatConfig {
     warnThresholds: number[];
     weeklyWarnThresholds: number[];
     resetReminderMins: number;
+    sessionCostLimitUsd: number;
     plan: ClaudePlan | null;
     reportsEnabled: boolean;
     reportFrequency: ReportFrequency;

package/dist/config.js

@@ -36,6 +36,7 @@ const DEFAULTS = {
     warnThresholds: [70, 85, 95],
     weeklyWarnThresholds: [50, 75, 90],
     resetReminderMins: 10,
+    sessionCostLimitUsd: 0,
     plan: null,
     reportsEnabled: false,
     reportFrequency: 'weekly',
@@ -92,6 +93,11 @@ function validateConfig(raw) {
         if (typeof v !== 'number' || isNaN(v) || v < 0 || v > 60)
             return 'resetReminderMins must be a number between 0 and 60';
     }
+    if ('sessionCostLimitUsd' in cfg) {
+        const v = cfg.sessionCostLimitUsd;
+        if (typeof v !== 'number' || isNaN(v) || v < 0)
+            return 'sessionCostLimitUsd debe ser un número >= 0 (0 = desactivado)';
+    }
     if ('alertsEnabled' in cfg && typeof cfg.alertsEnabled !== 'boolean')
         return 'alertsEnabled debe ser boolean';
     if ('reportsEnabled' in cfg && typeof cfg.reportsEnabled !== 'boolean')

package/dist/index.js

@@ -200,11 +200,20 @@ program
         console.log('✅ claudestat fully removed');
         process.exit(0);
     }
-    console.log('Setting up claudestat...');
-    (0, install_1.installHooks)();
-    (0, service_1.installService)();
-    console.log('✅ claudestat is running and will start automatically on login');
-    console.log('   Dashboard → http://localhost:7337');
+    // 1. Wizard: Node check + plan + config + hooks + MCP
+    await (0, install_1.runWizard)();
+    // 2. Start daemon now
+    const daemonRunning = await fetch('http://localhost:7337/health', {
+        signal: AbortSignal.timeout(2000),
+    }).then(r => r.ok).catch(() => false);
+    if (!daemonRunning) {
+        spawnDaemon();
+    }
+    else {
+        console.log('✅ Daemon already running');
+        console.log('   Dashboard → http://localhost:7337');
+    }
+    console.log('\n   Run \x1b[36mclaudestat watch\x1b[0m to see live activity');
     process.exit(0);
 });
 program
@@ -315,6 +324,7 @@ program
     .option('--threshold <number>', 'Quota percentage to trigger the kill switch (default: 95)')
     .option('--plan <plan>', 'Force plan detection: pro|max5|max20|auto')
     .option('--alerts <bool>', 'Enable/disable daemon rate limit alerts: true|false')
+    .option('--session-limit <usd>', 'Alert when a session exceeds this cost in USD (0 = disabled)')
     .action((opts) => {
     const cfg = (0, config_1.readConfig)();
     let changed = false;
@@ -344,6 +354,15 @@ program
         cfg.alertsEnabled = opts.alerts === 'true';
         changed = true;
     }
+    if (opts.sessionLimit !== undefined) {
+        const v = parseFloat(opts.sessionLimit);
+        if (!isNaN(v) && v >= 0) {
+            cfg.sessionCostLimitUsd = v;
+            changed = true;
+        }
+        else
+            console.warn('  ⚠️  session-limit must be a number >= 0 (e.g. 5 for $5)');
+    }
     if (changed) {
         (0, config_1.writeConfig)(cfg);
         console.log('✅ Config saved to ~/.claudestat/config.json');
@@ -373,6 +392,7 @@ program
     if (cfg.killSwitchEnabled) {
         lines.push(`                    ${bar(cfg.killSwitchThreshold)}`);
     }
+    lines.push(`  Session limit     ${cfg.sessionCostLimitUsd > 0 ? `${Y}$${cfg.sessionCostLimitUsd.toFixed(2)}${R}` : `${D}OFF${R}`}`);
     lines.push('');
     lines.push(`  Cycle thresholds  ${cfg.warnThresholds.join('%, ')}%`);
     lines.push(`                    ${D}yellow${R} ${bar(cfg.warnThresholds[0], 8)}  ${D}orange${R} ${bar(cfg.warnThresholds[1], 8)}  ${D}red${R} ${bar(cfg.warnThresholds[2], 8)}`);

package/dist/routes/events.js

@@ -17,8 +17,14 @@ const quota_tracker_1 = require("../quota-tracker");
 const config_1 = require("../config");
 const rate_limiter_1 = require("../middleware/rate-limiter");
 const stream_1 = require("./stream");
+const notifier_1 = require("../notifier");
 const enricher_1 = require("../enricher");
 Object.defineProperty(exports, "processLatestForSession", { enumerable: true, get: function () { return enricher_1.processLatestForSession; } });
+// ─── Loop alert cooldown (toolName:sessionId → last alert ts) ─────────────────
+const loopAlertCooldown = new Map();
+const LOOP_ALERT_COOLDOWN_MS = 120000; // coincide con LOOP_COOLDOWN_MS en intelligence.ts
+// ─── Session cost alert: sesiones que ya recibieron notificación ───────────────
+const sessionCostAlertFired = new Set();
 exports.eventsRouter = (0, express_1.Router)();
 // Skill activa por sesión — se setea tras Skill Done, se limpia en Stop.
 // Permite taggear los eventos siguientes con skill_parent para agruparlos en la UI.
@@ -248,6 +254,24 @@ const onCostUpdate = (sessionId, cost) => {
             projected_hourly_usd: projectedHourlyUsd,
         }
     });
+    // ─── Session cost alert: notificar si la sesión supera el límite configurado ──
+    const cfg = (0, config_1.readConfig)();
+    if (cfg.alertsEnabled && cfg.sessionCostLimitUsd > 0 && cost.cost_usd >= cfg.sessionCostLimitUsd && !sessionCostAlertFired.has(sessionId)) {
+        sessionCostAlertFired.add(sessionId);
+        (0, notifier_1.sendDesktopNotification)('claudestat — Session cost limit reached', `Session cost: $${cost.cost_usd.toFixed(2)} — limit $${cfg.sessionCostLimitUsd.toFixed(2)} reached`);
+    }
+    // ─── Loop alert: notificación de escritorio si hay loops activos ─────────────
+    if (cfg.alertsEnabled && report.loops.length > 0) {
+        const now = Date.now();
+        for (const loop of report.loops) {
+            const key = `${loop.toolName}:${sessionId}`;
+            const lastSent = loopAlertCooldown.get(key) ?? 0;
+            if (now - lastSent >= LOOP_ALERT_COOLDOWN_MS) {
+                loopAlertCooldown.set(key, now);
+                (0, notifier_1.sendDesktopNotification)('claudestat — Loop detected', `${loop.toolName} called ${loop.count}× in 2min — session may be stuck`);
+            }
+        }
+    }
     // Emitir desglose de costo del último bloque (input vs output) para el TracePanel
     if (cost.lastEntry) {
         (0, stream_1.broadcast)({

package/dist/routes/misc.js

@@ -90,7 +90,7 @@ exports.miscRouter.get('/kill-switch', (_req, res) => {
         const data = (0, quota_tracker_1.computeQuota)(cfg.plan ?? undefined);
         const blocked = cfg.killSwitchEnabled && data.cyclePct >= cfg.killSwitchThreshold;
         const reason = blocked
-            ? `5h quota at ${data.cyclePct}% (limit: ${cfg.killSwitchThreshold}%). Resets in ${formatMs(data.cycleResetMs)}.`
+            ? `Quota at ${data.cyclePct}% — kill switch threshold is ${cfg.killSwitchThreshold}%. Resets in ${formatMs(data.cycleResetMs)}.`
             : undefined;
         res.json({ blocked, reason, cyclePct: data.cyclePct });
     }

package/hooks/event.js

@@ -46,18 +46,13 @@ process.stdin.on('end', () => {
         signal: AbortSignal.timeout(1500),
       })
         .then(r => r.json())
-        .catch(() => {
-          // Si el daemon no responde, loggeamos en stderr (visible en logs de Claude)
-          // pero NO bloqueamos — un fallo del daemon no debe interrumpir el trabajo
-          process.stderr.write(`[claudetrace] daemon no disponible — kill-switch desactivado\n`)
-          return { blocked: false }
-        }),
+        .catch(() => ({ blocked: false })),  // daemon no disponible → fail-open
     ])
     .then(([_, ks]) => {
       if (ks && ks.blocked) {
-        // Claude Code muestra este stderr al usuario antes de cancelar la acción
-        process.stderr.write(`\n🚫 claudetrace kill switch activado\n`)
-        process.stderr.write(`   ${ks.reason ?? 'Cuota de uso superada.'}\n\n`)
+        process.stderr.write(`\n🚫 claudestat — kill switch active\n`)
+        process.stderr.write(`   ${ks.reason ?? 'Usage quota exceeded.'}\n`)
+        process.stderr.write(`   To disable: claudestat config --kill-switch false\n\n`)
         process.exit(2)
       } else {
         process.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statforge/claudestat",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Observability layer for Claude Code — live token tracking, cost analytics, quota guard, loop detection, and usage dashboard. The htop for Claude Code.",
   "keywords": [
     "claude-code",