@statforge/claudestat 1.0.1

package/dist/install.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * install.ts — Instalador de hooks en Claude Code
+ *
+ * Claude Code permite definir hooks en ~/.claude/settings.json.
+ * Este comando modifica ese archivo para agregar nuestros hooks
+ * sin pisar los que ya existan.
+ *
+ * IMPORTANTE: Hacemos un backup antes de modificar.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHooks = installHooks;
+exports.runInstall = runInstall;
+exports.runWizard = runWizard;
+exports.showInstallStatus = showInstallStatus;
+exports.uninstallHooks = uninstallHooks;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = __importDefault(require("readline"));
+const paths_1 = require("./paths");
+const config_1 = require("./config");
+const CLAUDESTAT_DIR = (0, paths_1.getClaudestatDir)();
+const CLAUDE_SETTINGS = path_1.default.join((0, paths_1.getClaudeDir)(), 'settings.json');
+const HOOKS_DIR = path_1.default.join(CLAUDESTAT_DIR, 'hooks');
+const HOOK_SCRIPT = path_1.default.join(HOOKS_DIR, 'event.js');
+function installHookScript() {
+    fs_1.default.mkdirSync(HOOKS_DIR, { recursive: true });
+    // El script original está en el paquete junto a este archivo
+    const source = path_1.default.join(__dirname, '..', 'hooks', 'event.js');
+    fs_1.default.copyFileSync(source, HOOK_SCRIPT);
+    if (!paths_1.isWindows) {
+        fs_1.default.chmodSync(HOOK_SCRIPT, 0o755);
+    }
+    console.log(`✓ Hook script installed → ${HOOK_SCRIPT}`);
+}
+function hookEntry(eventType, matcher = '.*') {
+    return {
+        matcher,
+        hooks: [{
+                type: 'command',
+                // Usamos el path absoluto para que funcione desde cualquier directorio
+                command: `node "${HOOK_SCRIPT}" ${eventType}`
+            }]
+    };
+}
+function installHooks() {
+    installHookScript();
+    // Leer settings.json existente
+    let settings = {};
+    try {
+        settings = JSON.parse(fs_1.default.readFileSync(CLAUDE_SETTINGS, 'utf8'));
+    }
+    catch {
+        console.error(`\n❌ Could not read ${CLAUDE_SETTINGS}`);
+        console.error('   Make sure Claude Code is installed.\n');
+        process.exit(1);
+    }
+    // Backup antes de modificar
+    const backupPath = CLAUDE_SETTINGS + '.bak';
+    fs_1.default.copyFileSync(CLAUDE_SETTINGS, backupPath);
+    console.log(`✓ Backup created → ${backupPath}`);
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hookTypes = ['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop'];
+    let added = 0;
+    for (const hookType of hookTypes) {
+        if (!settings.hooks[hookType])
+            settings.hooks[hookType] = [];
+        const exists = settings.hooks[hookType].some(hasClaudestatHook);
+        if (!exists) {
+            settings.hooks[hookType].push(hookEntry(hookType));
+            console.log(`✓ Hook configured: ${hookType}`);
+            added++;
+        }
+        else {
+            console.log(`  (already installed): ${hookType}`);
+        }
+    }
+    fs_1.default.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+    if (added > 0) {
+        console.log(`\n✅ ${added} hooks installed.`);
+        console.log('   Restart Claude Code to activate them.\n');
+    }
+    else {
+        console.log('\n✅ All hooks already installed.\n');
+    }
+}
+const CONFIG_PATH = path_1.default.join(CLAUDESTAT_DIR, 'config.json');
+function hasClaudestatHook(entry) {
+    return entry.hooks?.some((h) => typeof h.command === 'string' && h.command.includes('claudestat'));
+}
+async function runInstall() {
+    if (!fs_1.default.existsSync(CONFIG_PATH)) {
+        await runWizard();
+    }
+    else {
+        showInstallStatus();
+    }
+}
+async function runWizard() {
+    const nonInteractive = !process.stdin.isTTY;
+    console.log('\n╔═══════════════════════════════════════════╗');
+    console.log('║        claudestat — First Install         ║');
+    console.log('╚═══════════════════════════════════════════╝\n');
+    console.log('claudestat hooks into Claude Code to capture:');
+    console.log('  • Tool calls (name, duration, input/output)');
+    console.log('  • Token usage and costs per session');
+    console.log('  • Quota consumption (5h rolling window)\n');
+    console.log('It modifies ~/.claude/settings.json to add lifecycle hooks.');
+    console.log('A backup is created before any change.\n');
+    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // Paso 1: confirmación
+        if (!nonInteractive) {
+            const answer = await new Promise(resolve => rl.question('Continue with installation? [Y/n] ', resolve));
+            if (answer.trim().toLowerCase() === 'n') {
+                console.log('\nInstallation cancelled.\n');
+                return;
+            }
+        }
+        // Paso 2: verificar versión de Node
+        const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
+        if (nodeMajor < 22) {
+            console.log(`\n⚠  Node.js ${process.version} detected — claudestat requires Node ≥ 22.`);
+            console.log('   Some features may not work correctly.\n');
+        }
+        else {
+            console.log(`✓ Node.js ${process.version}`);
+        }
+        // Paso 3: selección de plan
+        let plan = 'pro';
+        if (!nonInteractive) {
+            console.log('\nSelect your Claude plan:');
+            console.log('  1) free   2) pro (default)   3) max5   4) max20');
+            const input = await new Promise(resolve => rl.question('Plan [1-4, default: 2]: ', resolve));
+            const planMap = { '1': 'free', '2': 'pro', '3': 'max5', '4': 'max20' };
+            plan = planMap[input.trim()] ?? 'pro';
+        }
+        console.log(`✓ Plan: ${plan}`);
+        // Paso 4: crear config inicial
+        const cfg = (0, config_1.readConfig)();
+        (0, config_1.writeConfig)({ ...cfg, plan: plan });
+        console.log(`✓ Config created → ${CONFIG_PATH}\n`);
+    }
+    finally {
+        rl.close();
+    }
+    // Paso 5: instalar hooks
+    installHooks();
+}
+function showInstallStatus() {
+    const cfg = (0, config_1.readConfig)();
+    console.log('\n╔═══════════════════════════════════════════╗');
+    console.log('║         claudestat — Status               ║');
+    console.log('╚═══════════════════════════════════════════╝\n');
+    console.log('✅ Already installed. Current config:\n');
+    console.log(`   plan:                ${cfg.plan ?? 'auto-detect'}`);
+    console.log(`   killSwitchEnabled:   ${cfg.killSwitchEnabled}`);
+    console.log(`   killSwitchThreshold: ${cfg.killSwitchThreshold}%`);
+    // Verificar si los hooks están en settings.json
+    let hooksOk = false;
+    try {
+        const settings = JSON.parse(fs_1.default.readFileSync(CLAUDE_SETTINGS, 'utf8'));
+        hooksOk = Object.values(settings.hooks ?? {})
+            .flat()
+            .some(hasClaudestatHook);
+    }
+    catch { }
+    console.log(`\n   hooks in settings.json: ${hooksOk ? '✅ installed' : '❌ not found'}`);
+    if (!hooksOk) {
+        console.log('\n   Run `claudestat install` again to reinstall hooks.\n');
+    }
+    else {
+        console.log('');
+    }
+}
+function uninstallHooks() {
+    let settings = {};
+    try {
+        settings = JSON.parse(fs_1.default.readFileSync(CLAUDE_SETTINGS, 'utf8'));
+    }
+    catch {
+        console.error('Could not read settings.json');
+        process.exit(1);
+    }
+    if (!settings.hooks) {
+        console.log('No hooks installed.');
+        return;
+    }
+    let removed = 0;
+    for (const hookType of Object.keys(settings.hooks)) {
+        const before = settings.hooks[hookType].length;
+        settings.hooks[hookType] = settings.hooks[hookType].filter((entry) => !hasClaudestatHook(entry));
+        removed += before - settings.hooks[hookType].length;
+    }
+    fs_1.default.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+    console.log(`✅ ${removed} claudestat hooks removed.`);
+    console.log('   Restart Claude Code for changes to take effect.\n');
+}

package/dist/intelligence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * intelligence.ts — Detección de loops y scoring de eficiencia
+ *
+ * Módulo puro: solo recibe datos y retorna análisis.
+ * Sin efectos secundarios, sin acceso a DB.
+ * Esto lo hace fácil de testear y reutilizar.
+ */
+import type { EventRow } from './db';
+export interface LoopAlert {
+    toolName: string;
+    count: number;
+    windowMs: number;
+    ts: number;
+}
+export interface IntelligenceReport {
+    loops: LoopAlert[];
+    efficiencyScore: number;
+    summary: string;
+}
+/**
+ * Detecta loops: cuando el mismo tool se llama ≥ LOOP_THRESHOLD veces
+ * dentro de LOOP_WINDOW_MS. Evita alertas duplicadas con LOOP_COOLDOWN_MS.
+ *
+ * Algoritmo: ventana deslizante sobre eventos ordenados por timestamp.
+ */
+export declare function detectLoops(events: EventRow[]): LoopAlert[];
+/**
+ * Calcula un score de 0-100 basado en:
+ * - Loops detectados     → -10 por loop, cap -25
+ * - Tool calls excesivos → -5 por cada 50 calls sobre el umbral (150), cap -20
+ * - Coste alto           → -5 si >$2, -10 si >$10, -20 si >$30
+ *
+ * Principio: una sesión de coding larga y productiva (88-200 tools) NO debería
+ * llegar a 0. El score 0 se reserva para sesiones con loops masivos + coste alto.
+ *
+ * Ejemplos calibrados:
+ *   88 tools, 5 loops, $6.49  → 100 - 25 - 0 - 5  = 70
+ *  236 tools, 2 loops, $25.34 → 100 - 20 - 9 - 10  = 61
+ *   20 tools, 0 loops, $0.30  → 100 - 0  - 0 - 0   = 100
+ */
+export declare function calcEfficiencyScore(events: EventRow[], loops: LoopAlert[], costUsd: number): number;
+/**
+ * Genera el reporte completo de inteligencia para una sesión.
+ */
+export declare function analyzeSession(events: EventRow[], costUsd: number): IntelligenceReport;

package/dist/intelligence.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * intelligence.ts — Detección de loops y scoring de eficiencia
+ *
+ * Módulo puro: solo recibe datos y retorna análisis.
+ * Sin efectos secundarios, sin acceso a DB.
+ * Esto lo hace fácil de testear y reutilizar.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLoops = detectLoops;
+exports.calcEfficiencyScore = calcEfficiencyScore;
+exports.analyzeSession = analyzeSession;
+// ─── Detección de loops ───────────────────────────────────────────────────────
+const LOOP_THRESHOLD = 8; // calls para considerar loop
+const LOOP_WINDOW_MS = 120000; // ventana de tiempo: 2 minutos (antes 60s → demasiados falsos positivos en coding)
+const LOOP_COOLDOWN_MS = 120000; // cooldown entre alertas del mismo tool: 2 min (antes 15s → re-alertaba constantemente)
+/**
+ * Detecta loops: cuando el mismo tool se llama ≥ LOOP_THRESHOLD veces
+ * dentro de LOOP_WINDOW_MS. Evita alertas duplicadas con LOOP_COOLDOWN_MS.
+ *
+ * Algoritmo: ventana deslizante sobre eventos ordenados por timestamp.
+ */
+function detectLoops(events) {
+    const alerts = [];
+    const windowsByTool = new Map(); // toolName → timestamps en ventana
+    for (const ev of events) {
+        // Solo contamos tool calls (PreToolUse o Done — uno de los dos)
+        if (ev.type !== 'Done' && ev.type !== 'PreToolUse')
+            continue;
+        if (!ev.tool_name)
+            continue;
+        const toolName = ev.tool_name;
+        const ts = ev.ts;
+        // Mantener solo los timestamps dentro de la ventana deslizante
+        const window = (windowsByTool.get(toolName) || []).filter(t => t >= ts - LOOP_WINDOW_MS);
+        window.push(ts);
+        windowsByTool.set(toolName, window);
+        if (window.length >= LOOP_THRESHOLD) {
+            // Verificar cooldown: no alertar si ya alertamos recientemente para este tool
+            const lastAlert = [...alerts].reverse().find(a => a.toolName === toolName);
+            if (!lastAlert || ts - lastAlert.ts >= LOOP_COOLDOWN_MS) {
+                alerts.push({ toolName, count: window.length, windowMs: LOOP_WINDOW_MS, ts });
+            }
+        }
+    }
+    return alerts;
+}
+// ─── Scoring de eficiencia ────────────────────────────────────────────────────
+/**
+ * Calcula un score de 0-100 basado en:
+ * - Loops detectados     → -10 por loop, cap -25
+ * - Tool calls excesivos → -5 por cada 50 calls sobre el umbral (150), cap -20
+ * - Coste alto           → -5 si >$2, -10 si >$10, -20 si >$30
+ *
+ * Principio: una sesión de coding larga y productiva (88-200 tools) NO debería
+ * llegar a 0. El score 0 se reserva para sesiones con loops masivos + coste alto.
+ *
+ * Ejemplos calibrados:
+ *   88 tools, 5 loops, $6.49  → 100 - 25 - 0 - 5  = 70
+ *  236 tools, 2 loops, $25.34 → 100 - 20 - 9 - 10  = 61
+ *   20 tools, 0 loops, $0.30  → 100 - 0  - 0 - 0   = 100
+ */
+function calcEfficiencyScore(events, loops, costUsd) {
+    let score = 100;
+    // Loops: señal fuerte de ineficiencia, pero no colapsa el score
+    score -= Math.min(loops.length * 10, 25);
+    // Tool calls: solo penalizar si supera un umbral alto (sesiones muy largas)
+    const toolCallCount = events.filter(e => e.type === 'Done').length;
+    if (toolCallCount > 150) {
+        score -= Math.min(Math.floor((toolCallCount - 150) / 50) * 5, 20);
+    }
+    // Coste: escala progresiva, no binaria
+    if (costUsd > 30)
+        score -= 20;
+    else if (costUsd > 10)
+        score -= 10;
+    else if (costUsd > 2)
+        score -= 5;
+    return Math.max(0, Math.min(100, score));
+}
+/**
+ * Genera el reporte completo de inteligencia para una sesión.
+ */
+function analyzeSession(events, costUsd) {
+    const loops = detectLoops(events);
+    const efficiencyScore = calcEfficiencyScore(events, loops, costUsd);
+    const summary = buildSummary(loops, efficiencyScore, costUsd, events);
+    return { loops, efficiencyScore, summary };
+}
+function buildSummary(loops, score, costUsd, events) {
+    const parts = [];
+    if (loops.length > 0) {
+        const loopDesc = loops.map(l => `${l.toolName} x${l.count}`).join(', ');
+        parts.push(`⚠️  Loop detected: ${loopDesc}`);
+    }
+    if (score >= 90)
+        parts.push('✅ Efficient session');
+    else if (score >= 70)
+        parts.push('⚡ Medium efficiency');
+    else
+        parts.push('🔴 Inefficient session');
+    const toolCalls = events.filter(e => e.type === 'Done').length;
+    parts.push(`${toolCalls} tool calls · $${costUsd.toFixed(4)}`);
+    return parts.join(' · ');
+}

package/dist/meta-stats.d.ts

@@ -0,0 +1,28 @@
+/**
+ * meta-stats.ts — Context overhead KPIs
+ *
+ * Detects files that Claude Code loads into context automatically
+ * (CLAUDE.md, settings, AGENTS.md, etc.) and estimates their token cost.
+ * Keeps a rolling history for sparklines (last 30 snapshots).
+ */
+export interface MetaAlert {
+    level: 'info' | 'warning' | 'critical';
+    message: string;
+    metric: string;
+}
+export interface ContextFileInfo {
+    label: string;
+    tokens: number;
+}
+export interface MetaStats {
+    ts: number;
+    contextFiles: ContextFileInfo[];
+    contextOverheadTokens: number;
+    alerts: MetaAlert[];
+}
+export interface MetaSnapshot {
+    ts: number;
+    contextOverheadTokens: number;
+}
+export declare function computeMetaStats(sessionCwd?: string, contextPct?: number): MetaStats;
+export declare function getMetaHistory(): MetaSnapshot[];

package/dist/meta-stats.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * meta-stats.ts — Context overhead KPIs
+ *
+ * Detects files that Claude Code loads into context automatically
+ * (CLAUDE.md, settings, AGENTS.md, etc.) and estimates their token cost.
+ * Keeps a rolling history for sparklines (last 30 snapshots).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeMetaStats = computeMetaStats;
+exports.getMetaHistory = getMetaHistory;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const paths_1 = require("./paths");
+// ─── In-memory history ────────────────────────────────────────────────────────
+const MAX_HISTORY = 30;
+const history = [];
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Decodes the real cwd from Claude Code's internal project path format.
+ *
+ * Claude Code stores transcript paths like:
+ *   /Users/db/.claude/projects/-Users-db-Documents-GitHub-myproject
+ *
+ * Where the suffix is the real cwd with each '/' replaced by '-'.
+ */
+function resolveProjectCwd(storedCwd) {
+    const homeDir = os_1.default.homedir();
+    const projectsDir = path_1.default.join((0, paths_1.getClaudeDir)(), 'projects');
+    if (!storedCwd.startsWith(projectsDir + path_1.default.sep))
+        return storedCwd;
+    const encodedPath = storedCwd.slice(projectsDir.length + 1);
+    const encodedHome = (0, paths_1.encodeClaudePath)(homeDir);
+    if (encodedPath.startsWith(encodedHome)) {
+        const rest = encodedPath.slice(encodedHome.length);
+        return homeDir + rest.replace(/-/g, path_1.default.sep);
+    }
+    return path_1.default.sep + encodedPath.replace(/-/g, path_1.default.sep);
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function readFile(filePath) {
+    try {
+        return fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function fmtTok(n) {
+    if (n >= 1000000)
+        return `${(n / 1000000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}K`;
+    return String(n);
+}
+// ─── Context file candidates ──────────────────────────────────────────────────
+/**
+ * Files that Claude Code automatically loads into context.
+ * Each candidate is resolved to a full path; non-existent files are skipped.
+ *
+ * Universal files (always checked):
+ *   - ~/.claude/CLAUDE.md         — global instructions for all projects
+ *   - ~/.claude/settings.json     — global config (hooks, permissions, model)
+ *   - ~/.claude/settings.local.json — personal overrides
+ *
+ * Project-level files (checked if a project cwd is known):
+ *   - {project}/CLAUDE.md         — project-specific instructions
+ *   - {project}/AGENTS.md         — instructions for agent mode
+ *   - {project}/.claude/CLAUDE.md — alternative project-level location
+ */
+function resolveContextCandidates(homeDir, projectCwd) {
+    const claudeDir = (0, paths_1.getClaudeDir)();
+    const candidates = [
+        { label: 'CLAUDE.md (global)', filePath: path_1.default.join(claudeDir, 'CLAUDE.md') },
+        { label: 'settings.json', filePath: path_1.default.join(claudeDir, 'settings.json') },
+        { label: 'settings.local.json', filePath: path_1.default.join(claudeDir, 'settings.local.json') },
+    ];
+    if (projectCwd) {
+        candidates.push({ label: 'CLAUDE.md (proyecto)', filePath: path_1.default.join(projectCwd, 'CLAUDE.md') }, { label: 'AGENTS.md', filePath: path_1.default.join(projectCwd, 'AGENTS.md') }, { label: '.claude/CLAUDE.md', filePath: path_1.default.join(projectCwd, '.claude', 'CLAUDE.md') });
+    }
+    return candidates;
+}
+// ─── Compute ──────────────────────────────────────────────────────────────────
+function computeMetaStats(sessionCwd, contextPct) {
+    const ts = Date.now();
+    const homeDir = os_1.default.homedir();
+    const projectCwd = sessionCwd ? resolveProjectCwd(sessionCwd) : undefined;
+    // ── Detect context files ───────────────────────────────────────────────────
+    const contextFiles = [];
+    let contextOverheadTokens = 0;
+    for (const { label, filePath } of resolveContextCandidates(homeDir, projectCwd)) {
+        const content = readFile(filePath);
+        if (!content)
+            continue;
+        const tokens = estimateTokens(content);
+        contextFiles.push({ label, tokens });
+        contextOverheadTokens += tokens;
+    }
+    // ── Alerts ────────────────────────────────────────────────────────────────
+    const alerts = [];
+    if (contextOverheadTokens > 20000) {
+        alerts.push({
+            level: 'critical',
+            message: `Overhead de contexto muy alto — ${fmtTok(contextOverheadTokens)} tokens en ${contextFiles.length} archivos`,
+            metric: 'context_files',
+        });
+    }
+    else if (contextOverheadTokens > 10000) {
+        alerts.push({
+            level: 'warning',
+            message: `Overhead de contexto alto — ${fmtTok(contextOverheadTokens)} tokens en ${contextFiles.length} archivos`,
+            metric: 'context_files',
+        });
+    }
+    if (contextPct !== undefined) {
+        if (contextPct > 85) {
+            alerts.push({ level: 'critical', message: `Auto-compact muy pronto — aprox. ${100 - contextPct}% libre`, metric: 'context' });
+        }
+        else if (contextPct > 65) {
+            alerts.push({ level: 'warning', message: `Contexto aproximado al ${contextPct}%`, metric: 'context' });
+        }
+    }
+    // ── History ───────────────────────────────────────────────────────────────
+    history.push({ ts, contextOverheadTokens });
+    if (history.length > MAX_HISTORY)
+        history.shift();
+    return { ts, contextFiles, contextOverheadTokens, alerts };
+}
+function getMetaHistory() {
+    return [...history];
+}

package/dist/middleware/rate-limiter.d.ts

@@ -0,0 +1,2 @@
+export declare function isRateLimited(ip: string): boolean;
+export declare function stopRateLimiter(): void;

package/dist/middleware/rate-limiter.js

@@ -0,0 +1,30 @@
+"use strict";
+// ─── Rate limiter simple para POST /event ────────────────────────────────────
+// Protege contra flood local. Límite: 120 requests/min por IP.
+// Usa ventana fija de 60s para simplicidad (sin dependencias externas).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRateLimited = isRateLimited;
+exports.stopRateLimiter = stopRateLimiter;
+const rateLimitMap = new Map();
+const RATE_LIMIT_MAX = 120;
+const RATE_LIMIT_WINDOW_MS = 60000;
+function isRateLimited(ip) {
+    const now = Date.now();
+    const entry = rateLimitMap.get(ip);
+    if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
+        rateLimitMap.set(ip, { count: 1, windowStart: now });
+        return false;
+    }
+    entry.count++;
+    return entry.count > RATE_LIMIT_MAX;
+}
+// Limpiar entradas expiradas cada 5 minutos para no acumular IPs inactivas
+const rateLimitCleanupInterval = setInterval(() => {
+    const now = Date.now();
+    rateLimitMap.forEach((v, k) => { if (now - v.windowStart > RATE_LIMIT_WINDOW_MS)
+        rateLimitMap.delete(k); });
+}, 5 * 60000);
+function stopRateLimiter() {
+    clearInterval(rateLimitCleanupInterval);
+    rateLimitMap.clear();
+}

package/dist/notifier.d.ts

@@ -0,0 +1 @@
+export declare function sendDesktopNotification(title: string, body: string): void;

package/dist/notifier.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendDesktopNotification = sendDesktopNotification;
+const child_process_1 = require("child_process");
+const os_1 = __importDefault(require("os"));
+function sendDesktopNotification(title, body) {
+    try {
+        if (os_1.default.platform() === 'darwin') {
+            const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            (0, child_process_1.execSync)(`osascript -e 'display notification "${escaped}" with title "${title}"'`, { stdio: 'ignore' });
+        }
+        else if (os_1.default.platform() === 'linux') {
+            (0, child_process_1.execSync)(`notify-send "${title}" "${body}"`, { stdio: 'ignore' });
+        }
+    }
+    catch {
+        // notification not available — already logged to console
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,79 @@
+/**
+ * paths.ts — Cross-platform path resolution for Claude Code data directories
+ *
+ * Claude Code stores data in the same location on all platforms:
+ *   All platforms: ~/.claude/
+ *
+ * ClaudeStat stores its own data in:
+ *   All platforms: ~/.claudestat/  (or CLAUDESTAT_DATA_DIR env var)
+ *
+ * Claude Code encodes project paths by replacing path separators AND colons with '-'.
+ * This module provides helpers to encode/decode those paths cross-platform.
+ */
+/**
+ * Returns the Claude Code data directory (~/.claude on all platforms).
+ * Empirically verified: Claude Code CLI stores settings at ~/.claude on macOS, Linux, and Windows.
+ */
+export declare function getClaudeDir(): string;
+/**
+ * Returns the ClaudeStat data directory.
+ * Can be overridden via CLAUDESTAT_DATA_DIR env var.
+ */
+export declare function getClaudestatDir(): string;
+/**
+ * Returns the PID file path for the daemon.
+ */
+export declare function getPidFile(): string;
+/**
+ * Encodes a real filesystem path into Claude Code's internal format.
+ * Claude Code replaces path separators AND colons with '-'.
+ *
+ *   macOS:   /Users/db/Documents/GitHub → -Users-db-Documents-GitHub
+ *   Windows: C:\Users\db\Documents      → C--Users-db-Documents
+ */
+export declare function encodeClaudePath(realPath: string): string;
+/**
+ * Decodes a Claude Code encoded directory name back to a real filesystem path.
+ *
+ * Since directory names with '-' are ambiguous (is "gmail-ai-agent" one dir or three?),
+ * this function requires a reference to the greedy filesystem resolver.
+ * Use project-scanner's findRealPath for the actual resolution.
+ *
+ * Returns the encodedHome + rest with '-' replaced by path.sep,
+ * but actual resolution should be done via findRealPath in project-scanner.
+ */
+export declare function decodeClaudePath(encoded: string): string | null;
+/**
+ * Creates the regex pattern for the encoded home path.
+ * Handles both / and \ separators.
+ */
+export declare function homeSlugRegex(): RegExp;
+/**
+ * Returns the engram-compatible slug for the home directory.
+ * Used for MEMORY.md path resolution.
+ *   macOS:   /Users/db   → -Users-db
+ *   Windows: C:\Users\db → C--Users-db
+ */
+export declare function getHomeSlug(): string;
+/**
+ * Returns the appropriate command to find an executable in PATH.
+ *   Unix:    which <name>
+ *   Windows: where <name>
+ */
+export declare function whichCmd(name: string): string;
+/**
+ * Returns the appropriate command to find all instances of an executable in PATH.
+ *   Unix:    which -a <name>
+ *   Windows: where <name>  (where already lists all matches)
+ */
+export declare function whichAllCmd(name: string): string;
+/**
+ * Returns the appropriate command to check if a port is in use.
+ *   Unix:    lsof -i :<port>
+ *   Windows: netstat -ano | findstr :<port>
+ */
+export declare function portCheckCmd(port: number): string;
+/**
+ * Returns true if running on Windows.
+ */
+export declare const isWindows: boolean;