@statforge/claudestat 1.0.1

package/dist/paths.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWindows = void 0;
+exports.getClaudeDir = getClaudeDir;
+exports.getClaudestatDir = getClaudestatDir;
+exports.getPidFile = getPidFile;
+exports.encodeClaudePath = encodeClaudePath;
+exports.decodeClaudePath = decodeClaudePath;
+exports.homeSlugRegex = homeSlugRegex;
+exports.getHomeSlug = getHomeSlug;
+exports.whichCmd = whichCmd;
+exports.whichAllCmd = whichAllCmd;
+exports.portCheckCmd = portCheckCmd;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const isWin = process.platform === 'win32';
+// ─── Claude Code data directory ────────────────────────────────────────────────
+/**
+ * Returns the Claude Code data directory (~/.claude on all platforms).
+ * Empirically verified: Claude Code CLI stores settings at ~/.claude on macOS, Linux, and Windows.
+ */
+function getClaudeDir() {
+    return path_1.default.join(os_1.default.homedir(), '.claude');
+}
+// ─── ClaudeStat data directory ─────────────────────────────────────────────────
+/**
+ * Returns the ClaudeStat data directory.
+ * Can be overridden via CLAUDESTAT_DATA_DIR env var.
+ */
+function getClaudestatDir() {
+    return process.env.CLAUDESTAT_DATA_DIR ?? path_1.default.join(os_1.default.homedir(), '.claudestat');
+}
+/**
+ * Returns the PID file path for the daemon.
+ */
+function getPidFile() {
+    return path_1.default.join(getClaudestatDir(), 'daemon.pid');
+}
+// ─── Path encoding (Claude Code format) ────────────────────────────────────────
+/**
+ * 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
+ */
+function encodeClaudePath(realPath) {
+    return realPath.replace(/[/\\:]/g, '-');
+}
+/**
+ * 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.
+ */
+function decodeClaudePath(encoded) {
+    const homeDir = os_1.default.homedir();
+    const encodedHome = encodeClaudePath(homeDir);
+    if (!encoded.startsWith(encodedHome))
+        return null;
+    const rest = encoded.slice(encodedHome.length);
+    if (!rest || rest === '')
+        return null;
+    // Replace '-' with path separator — but note this is ambiguous for dirs with '-'
+    // For actual resolution, use findRealPath() from project-scanner
+    return homeDir + rest.replace(/-/g, path_1.default.sep);
+}
+/**
+ * Creates the regex pattern for the encoded home path.
+ * Handles both / and \ separators.
+ */
+function homeSlugRegex() {
+    const escaped = encodeClaudePath(os_1.default.homedir()).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp('^' + escaped);
+}
+/**
+ * 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
+ */
+function getHomeSlug() {
+    return encodeClaudePath(os_1.default.homedir());
+}
+// ─── Platform utilities ────────────────────────────────────────────────────────
+/**
+ * Returns the appropriate command to find an executable in PATH.
+ *   Unix:    which <name>
+ *   Windows: where <name>
+ */
+function whichCmd(name) {
+    return isWin ? `where ${name}` : `which ${name}`;
+}
+/**
+ * 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)
+ */
+function whichAllCmd(name) {
+    return isWin ? `where ${name}` : `which -a ${name} 2>/dev/null`;
+}
+/**
+ * Returns the appropriate command to check if a port is in use.
+ *   Unix:    lsof -i :<port>
+ *   Windows: netstat -ano | findstr :<port>
+ */
+function portCheckCmd(port) {
+    return isWin
+        ? `netstat -ano | findstr :${port}`
+        : `lsof -i :${port}`;
+}
+/**
+ * Returns true if running on Windows.
+ */
+exports.isWindows = isWin;

package/dist/pattern-analyzer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * pattern-analyzer.ts — Detects inefficiency patterns in Claude Code usage.
+ *
+ * Pure logic module: receives pre-fetched DB data, returns actionable insights.
+ * No DB or filesystem access here — easier to test and reason about.
+ *
+ * Patterns detected:
+ *   - Read dominance   → suggest offset+limit or batching
+ *   - Bash overuse     → suggest Read/Grep instead
+ *   - High loop rate   → review prompts / agent instructions
+ *   - Low cache ratio  → context changes too much between messages
+ *   - High cache ratio → positive: great cost efficiency
+ *   - High avg cost    → consider Haiku for simpler tasks
+ *   - Low efficiency   → linked to loops
+ */
+export type InsightLevel = 'tip' | 'warning' | 'positive';
+export interface PatternInsight {
+    level: InsightLevel;
+    title: string;
+    description: string;
+    metric?: string;
+}
+export interface ToolCount {
+    tool_name: string;
+    count: number;
+}
+export interface SessionStats {
+    session_count: number;
+    avg_cache_read: number;
+    avg_total_input: number;
+    avg_loops: number;
+    avg_cost_usd: number;
+    avg_efficiency: number;
+}
+export declare function analyzePatterns(toolCounts: ToolCount[], stats: SessionStats): PatternInsight[];

package/dist/pattern-analyzer.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * pattern-analyzer.ts — Detects inefficiency patterns in Claude Code usage.
+ *
+ * Pure logic module: receives pre-fetched DB data, returns actionable insights.
+ * No DB or filesystem access here — easier to test and reason about.
+ *
+ * Patterns detected:
+ *   - Read dominance   → suggest offset+limit or batching
+ *   - Bash overuse     → suggest Read/Grep instead
+ *   - High loop rate   → review prompts / agent instructions
+ *   - Low cache ratio  → context changes too much between messages
+ *   - High cache ratio → positive: great cost efficiency
+ *   - High avg cost    → consider Haiku for simpler tasks
+ *   - Low efficiency   → linked to loops
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzePatterns = analyzePatterns;
+// ─── Thresholds ───────────────────────────────────────────────────────────────
+const MIN_SESSIONS = 2; // need at least 2 sessions for meaningful patterns
+const MIN_TOOLS = 15; // need at least 15 tool calls total to trust ratios
+// ─── Analyzer ────────────────────────────────────────────────────────────────
+function analyzePatterns(toolCounts, stats) {
+    const insights = [];
+    if (stats.session_count < MIN_SESSIONS)
+        return insights;
+    const totalTools = toolCounts.reduce((s, t) => s + t.count, 0);
+    if (totalTools < MIN_TOOLS)
+        return insights;
+    const byName = new Map(toolCounts.map(t => [t.tool_name, t.count]));
+    const get = (name) => byName.get(name) ?? 0;
+    // ── Read dominance ────────────────────────────────────────────────────────
+    const readCount = get('Read');
+    const readPct = Math.round(readCount / totalTools * 100);
+    if (readPct >= 45 && readCount >= 20) {
+        insights.push({
+            level: 'tip',
+            title: 'High Read frequency',
+            description: 'More than 40% of tool calls are Read. Consider using offset+limit to read only the needed lines, or batch reads of multiple files in a single response.',
+            metric: `${readPct}% of calls (${readCount} uses)`,
+        });
+    }
+    // ── Bash overuse vs Read/Grep ─────────────────────────────────────────────
+    const bashCount = get('Bash');
+    const readGrep = get('Read') + get('Grep') + get('Glob');
+    const bashPct = Math.round(bashCount / totalTools * 100);
+    if (bashCount > readGrep && bashCount >= 10) {
+        insights.push({
+            level: 'tip',
+            title: 'Bash used more than Read/Grep',
+            description: 'Bash can do the same as cat, grep or find, but is slower and less transparent. Dedicated tools (Read, Grep, Glob) are safer and faster for Claude.',
+            metric: `${bashPct}% Bash (${bashCount}) vs ${readGrep} Read+Grep+Glob`,
+        });
+    }
+    // ── High loop rate ────────────────────────────────────────────────────────
+    if (stats.avg_loops >= 1.5) {
+        insights.push({
+            level: 'warning',
+            title: 'Frequent loops detected',
+            description: 'Claude repeats the same tools in a loop more than 1.5 times per session on average. This usually indicates ambiguous instructions or an unnecessary confirmation cycle.',
+            metric: `~${stats.avg_loops.toFixed(1)} loops / session`,
+        });
+    }
+    // ── Cache efficiency ──────────────────────────────────────────────────────
+    const cacheRatio = stats.avg_total_input > 0
+        ? stats.avg_cache_read / stats.avg_total_input
+        : 0;
+    if (cacheRatio < 0.15 && stats.avg_total_input > 5000) {
+        insights.push({
+            level: 'tip',
+            title: 'Low cache reuse',
+            description: 'Only 15% or less of the context comes from cache. The context varies a lot between messages. If there are fixed instructions (CLAUDE.md, long system prompts), Claude reprocesses them on every response.',
+            metric: `${Math.round(cacheRatio * 100)}% cache hit ratio`,
+        });
+    }
+    else if (cacheRatio >= 0.65 && stats.avg_total_input > 5000) {
+        insights.push({
+            level: 'positive',
+            title: 'Excellent cache usage',
+            description: 'More than 65% of the context is served from cache in this project. A large portion of input cost is avoided thanks to Claude prompt caching.',
+            metric: `${Math.round(cacheRatio * 100)}% cache hit ratio`,
+        });
+    }
+    // ── High average cost per session ─────────────────────────────────────────
+    if (stats.avg_cost_usd >= 0.50) {
+        insights.push({
+            level: 'tip',
+            title: 'High cost per session',
+            description: 'The average cost per session exceeds $0.50. If there are repetitive analysis or file reading tasks, consider using Haiku (10× cheaper) for those parts.',
+            metric: `~$${stats.avg_cost_usd.toFixed(2)} / session`,
+        });
+    }
+    // ── Low efficiency score ──────────────────────────────────────────────────
+    if (stats.avg_efficiency !== null && stats.avg_efficiency < 65) {
+        insights.push({
+            level: 'warning',
+            title: 'Low efficiency score',
+            description: 'The average efficiency score is below 65/100. This is correlated with high loop counts. Check if prompts provide enough context on the first attempt.',
+            metric: `${Math.round(stats.avg_efficiency)}/100 average`,
+        });
+    }
+    // ── Heavy context per session ─────────────────────────────────────────────
+    if (stats.avg_total_input > 150000) {
+        insights.push({
+            level: 'tip',
+            title: 'Very large context per session',
+            description: 'The average context exceeds 150K tokens per session. Consider using /checkpoint + /compact frequently to reduce context size and lower the cost of each call.',
+            metric: `~${Math.round(stats.avg_total_input / 1000)}K tokens / session`,
+        });
+    }
+    // ── Agent heavy usage (positive) ─────────────────────────────────────────
+    const agentCount = get('Agent');
+    const agentPct = Math.round(agentCount / totalTools * 100);
+    if (agentPct >= 20) {
+        insights.push({
+            level: 'positive',
+            title: 'Heavy agent usage',
+            description: 'More than 20% of calls are to Agent. This project makes good use of Claude Code multi-agent mode to parallelize tasks.',
+            metric: `${agentPct}% Agent (${agentCount} uses)`,
+        });
+    }
+    return insights;
+}

package/dist/project-scanner.d.ts

@@ -0,0 +1,71 @@
+/**
+ * project-scanner.ts — Descubrimiento de proyectos desde ~/.claude/projects/
+ *
+ * Escanea los directorios de Claude Code, decodifica sus paths reales,
+ * lee los HANDOFF.md y extrae métricas de progreso.
+ */
+export interface HandoffProgress {
+    done: number;
+    total: number;
+    pct: number;
+    nextTask: string | null;
+}
+export interface ProjectScanResult {
+    path: string;
+    name: string;
+    encodedDir: string;
+    hasHandoff: boolean;
+    autoHandoff: boolean;
+    progress: HandoffProgress;
+    jsonlStats: JSONLStats;
+}
+export interface ModelUsage {
+    opusTokens: number;
+    sonnetTokens: number;
+    haikuTokens: number;
+}
+export interface JSONLStats {
+    session_count: number;
+    total_cost_usd: number;
+    total_tokens: number;
+    last_active: number | null;
+    modelUsage: ModelUsage;
+}
+/**
+ * Decodifica el nombre de directorio de Claude Code al path real.
+ * "-Users-db-Documents-GitHub-claudestat" → "/Users/db/Documents/GitHub/claudestat"
+ *
+ * Problema: directorios con '-' en el nombre (ej: "gmail-ai-agent") se confunden
+ * con separadores de path. Solución: búsqueda greedy recursiva por el filesystem.
+ */
+export declare function decodeProjectDir(encodedName: string): string | null;
+/**
+ * Dado un directorio base y un string con segmentos separados por '-',
+ * encuentra el path real en disco probando cada combinación posible.
+ * Ejemplo: base="/Users/db/Documents/GitHub", remaining="gmail-ai-agent"
+ *   → prueba "gmail" (no existe), "gmail-ai" (no existe), "gmail-ai-agent" (✓)
+ */
+export declare function findRealPath(base: string, remaining: string, depth?: number): string | null;
+export declare function parseHandoffProgress(content: string): HandoffProgress;
+/**
+ * Lee todos los JSONL del directorio codificado de un proyecto y acumula
+ * tokens y coste. No requiere que el daemon haya estado corriendo.
+ */
+export declare function getJSONLStats(encodedDir: string): JSONLStats;
+/**
+ * Genera y escribe un HANDOFF.md mínimo para proyectos que no tienen uno.
+ * El archivo se marca como auto-generado para que el usuario lo complete.
+ * No sobreescribe si ya existe.
+ */
+export declare function autoCreateHandoff(projectPath: string, stats: JSONLStats): void;
+/**
+ * Descubre todos los proyectos en los que se ha trabajado con Claude Code.
+ *
+ * Estrategia (Opción A):
+ * 1. Para cada directorio en ~/.claude/projects/:
+ *    a. Intenta decodificar el nombre (rápido) → busca mejor raíz subiendo árbol
+ *    b. Si falla → infiere desde file paths del JSONL
+ * 2. Agrupa por raíz de proyecto (varios dirs Claude Code → mismo repo)
+ * 3. Para cada raíz única: lee HANDOFF, calcula progreso, suma stats JSONL
+ */
+export declare function discoverProjects(): ProjectScanResult[];