@statforge/claudestat 1.1.1 → 1.2.0

package/README.md

@@ -43,7 +43,9 @@ Claude Code is powerful — but it's a black box while it runs. You can't see wh
 - Quota guard with configurable kill switch (block new sessions at X%)
 - Pattern analyzer: detects loops, Bash overuse, low cache reuse, and more
 - Per-session cost breakdown + cache savings + burn rate
+- Weekly usage insights with actionable tips
 - AI-generated weekly usage reports
+- MCP server: query quota, sessions, and tools from within Claude Code
 
 > If claudestat is useful, give it a ⭐ — it helps other developers find it.
 
@@ -140,6 +142,7 @@ That's it. Start a Claude Code session and watch the events flow in.
 | `claudestat status --compact` | One-line output for tmux status bar |
 | `claudestat config` | View or edit configuration |
 | `claudestat top` | Rank tools by cost, call count, or duration |
+| `claudestat weekly` | Weekly usage summary with actionable tips |
 | `claudestat export [format]` | Export session data to JSON or CSV |
 | `claudestat share [session-id]` | Generate shareable session card (ASCII/JSON) |
 | `claudestat roast` | Sarcastic usage analysis with roast jokes |
@@ -183,6 +186,22 @@ claudestat top
 
 Options: `--by cost|count|duration` · `--days 7|30|90` · `--limit N`
 
+### `claudestat weekly`
+
+Weekly usage summary with an actionable tip. Detects patterns like Bash overuse, low efficiency, high session count, and loop frequency.
+
+```
+claudestat weekly
+
+📊 claudestat weekly insight (May 5 — May 11)
+──────────────────────────────────────────────
+   Sessions: 42  ·  Cost: $146.21  ·  Loops: 93
+   Top tool: Bash (21% of cost)  ·  Efficiency: 93/100
+   ⚡ Tip: Group bash commands to reduce tool calls — each call costs context
+```
+
+Options: `--json` for machine-readable output.
+
 ### `claudestat status`
 
 ```
@@ -190,17 +209,17 @@ claudestat status
 
   Quota 5h   45/50 prompts (90%)  |  reset in 22m
   Plan        MAX5
-  Sonnet      3.2h / 5h  this week
+  Weekly      3.5h / 40h (9%)  this week
   Burn rate   1,240 tok/min
 ```
 
 ### `claudestat status --compact`
 
-One-line output for tmux status bar or scripting. Shows the 5h cycle quota percentage.
+One-line output for tmux status bar or scripting. Shows cycle quota and weekly usage with colored emoji.
 
 ```bash
 claudestat status --compact
-Current 45%🟡 pro
+C:45%🟡 W:9%🟢 pro
 ```
 
 ### `claudestat share`
@@ -324,6 +343,35 @@ Config is stored at `~/.claudestat/config.json` (macOS/Linux) or `%USERPROFILE%\
 
 ---
 
+## MCP Server
+
+claudestat includes an MCP (Model Context Protocol) server that lets Claude Code query its own usage stats — Claude can tell you its quota, session cost, and top tools in real time.
+
+### Tools exposed
+
+| Tool | Description |
+|------|------------|
+| `get_quota_status` | 5h cycle usage %, plan, weekly hours, burn rate |
+| `get_current_session` | Latest session: cost, tokens, efficiency, loops |
+| `get_session_stats` | Aggregated stats for N days |
+| `get_top_tools` | Top 10 tools by cost/count/duration |
+| `get_weekly_insight` | Weekly summary with actionable tip |
+
+### Register with Claude Code
+
+```bash
+claude mcp add --transport stdio claudestat -- claudestat-mcp
+```
+
+Once registered, ask Claude things like:
+- *"What's my current quota status?"*
+- *"Show me my latest session cost"*
+- *"What are my top 5 tools by cost this week?"*
+
+Zero extra dependencies — stdio JSON-RPC, works without the daemon running.
+
+---
+
 ## Dashboard
 
 The dashboard lives at `http://localhost:7337` and has six tabs:
@@ -501,6 +549,16 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
 
 ---
 
+## Contributors
+
+Thanks to everyone who has contributed to claudestat:
+
+[Deiby Gorrin](https://github.com/DeibyGS) — creator and maintainer
+
+Want to appear here? Pick a [good-first-issue](https://github.com/DeibyGS/claudestat/labels/good-first-issue) and open a PR.
+
+---
+
 ## FAQ
 
 **What is claudestat?**

package/dist/daemon.js

@@ -13,6 +13,39 @@
  * - Endpoint GET /meta-stats: KPIs de HANDOFF, Engram, config y alertas
  * - Procesa JSONL al conectar nuevo cliente SSE (contexto inmediato)
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -199,6 +232,19 @@ function startDaemon() {
         console.log(`\n● claudestat daemon  →  http://localhost:${PORT}`);
         console.log(`  Waiting for Claude Code events...\n`);
         console.log(`  In another terminal: \x1b[36mclaudestat watch\x1b[0m\n`);
+        // Weekly insight — se muestra una vez por semana al iniciar el daemon
+        Promise.resolve().then(() => __importStar(require('./insights'))).then(({ getWeeklyInsightData, shouldShowInsight, markInsightShown, renderWeeklyInsight }) => {
+            try {
+                if (!shouldShowInsight())
+                    return;
+                const data = getWeeklyInsightData();
+                if (data.total_sessions >= 3) {
+                    console.log(renderWeeklyInsight(data));
+                }
+                markInsightShown();
+            }
+            catch { /* insight is non-critical */ }
+        });
         // Etiquetar sesiones históricas que no tienen proyecto asignado
         migrateSessionProjects();
         // Pre-scan de proyectos al arrancar — garantiza respuesta inmediata en el tab

package/dist/db.d.ts

@@ -126,6 +126,19 @@ export declare const dbOps: {
         total_duration_ms: number;
         total_cost_usd: number;
     }[];
+    getWeeklyInsight(days?: number): {
+        total_sessions: number;
+        total_cost: number;
+        input_tokens: number;
+        output_tokens: number;
+        cache_read: number;
+        total_loops: number;
+        avg_efficiency: number;
+        week_start: number;
+        week_end: number;
+    };
+    setMeta(key: string, value: string): void;
+    getMeta(key: string): string | undefined;
     getCostProjection(days?: number): {
         total_cost_usd: number;
         earliest: number;

package/dist/db.js

@@ -42,6 +42,15 @@ try {
 `);
 }
 catch { /* ya existe */ }
+try {
+    db.exec(`
+  CREATE TABLE IF NOT EXISTS meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  )
+`);
+}
+catch { /* ya existe */ }
 db.exec(`
   CREATE TABLE IF NOT EXISTS sessions (
     id                     TEXT    PRIMARY KEY,
@@ -381,6 +390,25 @@ const stmts = {
     ORDER BY total_duration_ms DESC
     LIMIT ?
   `),
+    getWeeklyInsight: 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(CASE WHEN efficiency_score > 0 THEN efficiency_score END), 100) AS avg_efficiency,
+      MIN(started_at)                                               AS week_start,
+      MAX(last_event_at)                                            AS week_end
+    FROM sessions
+    WHERE started_at >= ?
+  `),
+    upsertMeta: db.prepare(`
+    INSERT INTO meta (key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `),
+    getMeta: db.prepare(`SELECT value FROM meta WHERE key = ?`),
     getCostProjection: db.prepare(`
     SELECT
       SUM(total_cost_usd)   AS total_cost_usd,
@@ -539,6 +567,17 @@ exports.dbOps = {
         }
         return tools;
     },
+    getWeeklyInsight(days = 7) {
+        const since = Date.now() - days * 86400000;
+        return stmts.getWeeklyInsight.get(since);
+    },
+    setMeta(key, value) {
+        stmts.upsertMeta.run(key, value);
+    },
+    getMeta(key) {
+        const row = stmts.getMeta.get(key);
+        return row?.value;
+    },
     getCostProjection(days = 7) {
         const since = Date.now() - days * 86400000;
         return stmts.getCostProjection.get(since);

package/dist/index.js

@@ -29,6 +29,7 @@ const config_1 = require("./config");
 const doctor_1 = require("./doctor");
 const share_1 = require("./share");
 const roast_1 = require("./roast");
+const insights_1 = require("./insights");
 const paths_1 = require("./paths");
 const program = new commander_1.Command();
 const PKG_VERSION = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', 'package.json'), 'utf8')).version;
@@ -64,7 +65,12 @@ async function stopDaemon() {
     catch { }
     try {
         const pid = parseInt(fs_1.default.readFileSync(PID_FILE, 'utf8').trim(), 10);
-        process.kill(pid, 'SIGTERM');
+        if (process.platform === 'win32') {
+            process.kill(pid);
+        }
+        else {
+            process.kill(pid, 'SIGTERM');
+        }
         console.log(`✅ claudestat daemon stopped (pid ${pid})`);
         removePidFile();
     }
@@ -160,7 +166,8 @@ program
         if (opts.compact) {
             const pctCycle = q.cyclePct;
             const cycleEmoji = pctCycle >= 95 ? '🔴' : pctCycle >= 70 ? '🟡' : '🟢';
-            console.log(`Current ${pctCycle}%${cycleEmoji} ${q.detectedPlan}`);
+            const wEmoji = q.weeklyPctAll >= 95 ? '🔴' : q.weeklyPctAll >= 70 ? '🟡' : '🟢';
+            console.log(`C:${pctCycle}%${cycleEmoji} W:${q.weeklyPctAll}%${wEmoji} ${q.detectedPlan}`);
             process.exit(0);
         }
         if (opts.json) {
@@ -174,6 +181,7 @@ program
                 weeklyLimitSonnet: q.weeklyLimitSonnet,
                 weeklyHoursOpus: q.weeklyHoursOpus,
                 weeklyLimitOpus: q.weeklyLimitOpus,
+                weeklyPctAll: q.weeklyPctAll,
                 burnRateTokensPerMin: q.burnRateTokensPerMin,
             }));
             process.exit(0);
@@ -187,19 +195,22 @@ program
         const resetLabel = resetMin >= 60
             ? `${Math.floor(resetMin / 60)}h ${resetMin % 60}m`
             : `${resetMin}m`;
-        const burnLabel = q.burnRateTokensPerMin > 0
-            ? ` │ 🔥 ${q.burnRateTokensPerMin.toLocaleString()} tok/min`
-            : '';
         const burnRow = q.burnRateTokensPerMin > 0
             ? `  Burn rate   ${q.burnRateTokensPerMin.toLocaleString()} tok/min\n`
             : '';
+        const weeklyTotalHours = q.weeklyHoursSonnet + q.weeklyHoursOpus;
+        const weeklyLimitTotal = q.weeklyLimitSonnet + q.weeklyLimitOpus;
+        const weeklyPctColor = q.weeklyPctAll >= 95 ? '\x1b[31m'
+            : q.weeklyPctAll >= 70 ? '\x1b[33m'
+                : '\x1b[32m';
         console.log(`\n📊 claudestat status\n` +
             `──────────────────────────────────────────\n` +
             `  Quota 5h    ${pctColor}${q.cyclePrompts}/${q.cycleLimit} prompts (${q.cyclePct}%)${R}  │  resets in ${resetLabel}\n` +
             `  Plan        ${q.detectedPlan.toUpperCase()}\n` +
-            `  Sonnet      ${q.weeklyHoursSonnet}h / ${q.weeklyLimitSonnet}h  this week\n` +
+            `  Weekly      ${weeklyTotalHours}h / ${weeklyLimitTotal}h (${weeklyPctColor}${q.weeklyPctAll}%${R})  this week\n` +
             (q.weeklyLimitOpus > 0
-                ? `  Opus        ${q.weeklyHoursOpus}h / ${q.weeklyLimitOpus}h  this week\n`
+                ? `   ├─ Sonnet  ${q.weeklyHoursSonnet}h / ${q.weeklyLimitSonnet}h\n` +
+                    `   └─ Opus    ${q.weeklyHoursOpus}h / ${q.weeklyLimitOpus}h\n`
                 : '') +
             `${burnRow}` +
             `──────────────────────────────────────────\n`);
@@ -358,4 +369,27 @@ program
         process.exit(1);
     }
 });
+program
+    .command('weekly')
+    .description('Show weekly usage summary')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    try {
+        const data = (0, insights_1.getWeeklyInsightData)();
+        if (data.total_sessions === 0) {
+            console.log('\n📊 No usage data yet — start using Claude Code and claudestat will track it.\n');
+            process.exit(0);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(data, null, 2));
+            process.exit(0);
+        }
+        console.log((0, insights_1.renderWeeklyInsight)(data));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('\n❌ Error:', err.message);
+        process.exit(1);
+    }
+});
 program.parse();

package/dist/insights.d.ts

@@ -0,0 +1,19 @@
+export interface WeeklyInsightData {
+    total_sessions: number;
+    total_cost: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read: number;
+    cache_hit_pct: number;
+    total_loops: number;
+    avg_efficiency: number;
+    top_tool: string;
+    top_tool_cost_pct: number;
+    week_start: number;
+    week_end: number;
+}
+export declare function getWeeklyInsightData(days?: number): WeeklyInsightData;
+export declare function generateTip(d: WeeklyInsightData): string;
+export declare function shouldShowInsight(): boolean;
+export declare function markInsightShown(): void;
+export declare function renderWeeklyInsight(d: WeeklyInsightData): string;

package/dist/insights.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWeeklyInsightData = getWeeklyInsightData;
+exports.generateTip = generateTip;
+exports.shouldShowInsight = shouldShowInsight;
+exports.markInsightShown = markInsightShown;
+exports.renderWeeklyInsight = renderWeeklyInsight;
+const db_1 = require("./db");
+const WEEK_MS = 7 * 86400000;
+const META_KEY = 'last_insight_at';
+function getWeeklyInsightData(days = 7) {
+    const agg = db_1.dbOps.getWeeklyInsight(days);
+    const topTools = db_1.dbOps.getTopTools(days, 'cost', 1);
+    const topTool = topTools[0];
+    const topToolName = topTool?.tool_name ?? 'Unknown';
+    const topToolPct = agg.total_cost > 0
+        ? Math.round((topTool?.total_cost_usd ?? 0) / agg.total_cost * 100)
+        : 0;
+    const totalInputWithCache = agg.input_tokens + agg.cache_read;
+    const cacheHitPct = totalInputWithCache > 0
+        ? Math.min(100, Math.round(agg.cache_read / totalInputWithCache * 100))
+        : 0;
+    return {
+        total_sessions: agg.total_sessions,
+        total_cost: agg.total_cost,
+        input_tokens: agg.input_tokens,
+        output_tokens: agg.output_tokens,
+        cache_read: agg.cache_read,
+        cache_hit_pct: cacheHitPct,
+        total_loops: agg.total_loops,
+        avg_efficiency: Math.round(agg.avg_efficiency),
+        top_tool: topToolName,
+        top_tool_cost_pct: topToolPct,
+        week_start: agg.week_start,
+        week_end: agg.week_end ?? agg.week_start,
+    };
+}
+function generateTip(d) {
+    const costPct = d.top_tool_cost_pct;
+    const tool = d.top_tool;
+    if (tool === 'Bash' && costPct >= 40) {
+        return 'Group bash commands to reduce tool calls — each call costs context';
+    }
+    if (d.total_loops >= 3) {
+        return `${d.total_loops} loops detected — consider using /compact earlier to prevent context thrashing`;
+    }
+    if (d.avg_efficiency < 60) {
+        return 'Low efficiency score — try smaller, focused tasks instead of long sessions';
+    }
+    if (d.total_sessions > 30) {
+        return `${d.total_sessions} sessions this week — consider batching related work into fewer sessions`;
+    }
+    if (d.cache_hit_pct < 10 && d.total_sessions > 5) {
+        return 'Low cache hit rate — repetitive context is costing you; use CLAUDE.md for common instructions';
+    }
+    if (d.total_cost > 20) {
+        return `$${d.total_cost.toFixed(0)} spent this week — enable quota alerts with "claudestat config --alerts true" to stay in control`;
+    }
+    return 'Enable quota alerts with "claudestat config --alerts true" to avoid surprise limits';
+}
+function shouldShowInsight() {
+    const last = db_1.dbOps.getMeta(META_KEY);
+    if (!last)
+        return true;
+    return Date.now() - parseInt(last, 10) >= WEEK_MS;
+}
+function markInsightShown() {
+    db_1.dbOps.setMeta(META_KEY, Date.now().toString());
+}
+function renderWeeklyInsight(d) {
+    const fmtTok = (n) => {
+        if (n >= 1000000)
+            return `${(n / 1000000).toFixed(1)}M`;
+        if (n >= 1000)
+            return `${Math.round(n / 1000)}K`;
+        return n.toString();
+    };
+    const fmtCost = (n) => `$${n.toFixed(2)}`;
+    const fmtDate = (ts) => {
+        const d = new Date(ts);
+        return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+    };
+    const R = '\x1b[0m';
+    const B = '\x1b[1m';
+    const D = '\x1b[2m';
+    const C = '\x1b[36m';
+    const lines = [];
+    lines.push(`\n${B}📊 claudestat weekly insight${R} ${D}(${fmtDate(d.week_start)} – ${fmtDate(d.week_end)})${R}`);
+    lines.push(`${'─'.repeat(60)}`);
+    lines.push(`   Sessions: ${d.total_sessions}  ·  Cost: ${fmtCost(d.total_cost)}  ·  Loops: ${d.total_loops}`);
+    lines.push(`   Top tool: ${d.top_tool} (${d.top_tool_cost_pct}% of cost)  ·  Efficiency: ${d.avg_efficiency}/100`);
+    const cacheLabel = d.total_sessions > 0
+        ? `  ·  Cache hit: ${d.cache_hit_pct}%`
+        : '';
+    const tokLabel = d.input_tokens + d.output_tokens > 0
+        ? `  ·  Tokens: ${fmtTok(d.input_tokens)}+${fmtTok(d.output_tokens)}`
+        : '';
+    if (cacheLabel || tokLabel) {
+        lines.push(`  ${D}${tokLabel}${cacheLabel}${R}`);
+    }
+    lines.push(`${'─'.repeat(60)}`);
+    lines.push(`   ${C}⚡${R} Tip: ${generateTip(d)}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * mcp-server.ts — MCP (Model Context Protocol) server for claudestat
+ *
+ * Exposes Claude Code usage metrics as tools that Claude can query.
+ * Zero extra dependencies — stdio JSON-RPC 2.0, readline only.
+ * Works without the daemon — reads SQLite + JSONL directly.
+ */
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * mcp-server.ts — MCP (Model Context Protocol) server for claudestat
+ *
+ * Exposes Claude Code usage metrics as tools that Claude can query.
+ * Zero extra dependencies — stdio JSON-RPC 2.0, readline only.
+ * Works without the daemon — reads SQLite + JSONL directly.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+process.on('warning', (w) => {
+    if (w.name === 'ExperimentalWarning' && w.message.includes('SQLite'))
+        return;
+    process.stderr.write(`${w.name}: ${w.message}\n`);
+});
+const readline = __importStar(require("readline"));
+const db_1 = require("./db");
+const quota_tracker_1 = require("./quota-tracker");
+const insights_1 = require("./insights");
+const SERVER_NAME = 'claudestat';
+const SERVER_VERSION = '1.2.0';
+const PROTOCOL_VERSION = '2025-06-18';
+const TOOLS = [
+    {
+        name: 'get_quota_status',
+        description: 'Get current Claude Code quota status: 5h cycle usage %, plan type, weekly hours per model, and burn rate (tokens/min)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: 'get_current_session',
+        description: 'Get details about the most recent Claude Code session: cost, tokens, efficiency score, and loops detected',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: 'get_session_stats',
+        description: 'Get aggregated session statistics for the last N days: session count, total cost, total tokens, loops, and average efficiency',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Number of days to look back (1–90, default 7)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_top_tools',
+        description: 'Get the top 10 most used tools by cost, call count, or duration in the last N days',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 30)'
+                },
+                sort_by: {
+                    type: 'string',
+                    description: 'Sort by: cost, count, or duration (default cost)'
+                }
+            },
+            required: []
+        }
+    },
+    {
+        name: 'get_weekly_insight',
+        description: 'Get the weekly usage summary with an actionable tip (same as claudestat weekly command)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Days to look back (default 7)'
+                }
+            },
+            required: []
+        }
+    }
+];
+function fmtDollar(n) {
+    if (n === 0)
+        return '$0.00';
+    if (n < 0.01)
+        return '< $0.01';
+    return `$${n.toFixed(2)}`;
+}
+function fmtTok(n) {
+    if (n >= 1000000)
+        return `${(n / 1000000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}K`;
+    return n.toString();
+}
+function toolGetQuotaStatus() {
+    const q = (0, quota_tracker_1.computeQuota)();
+    const resetMin = Math.ceil(q.cycleResetMs / 60000);
+    const resetLabel = resetMin >= 60
+        ? `${Math.floor(resetMin / 60)}h ${resetMin % 60}m`
+        : `${resetMin}m`;
+    const weeklyTotalHours = q.weeklyHoursSonnet + q.weeklyHoursOpus;
+    const weeklyLimitTotal = q.weeklyLimitSonnet + q.weeklyLimitOpus;
+    const parts = [
+        `Quota status — ${q.detectedPlan.toUpperCase()} plan`,
+        ``,
+        `5h cycle:    ${q.cyclePrompts}/${q.cycleLimit} prompts (${q.cyclePct}%)  ·  resets in ${resetLabel}`,
+        `Weekly:      ${weeklyTotalHours}h / ${weeklyLimitTotal}h (${q.weeklyPctAll}%)`,
+    ];
+    if (q.weeklyLimitOpus > 0) {
+        parts.push(`   ├─ Sonnet  ${q.weeklyHoursSonnet}h / ${q.weeklyLimitSonnet}h`);
+        parts.push(`   └─ Opus    ${q.weeklyHoursOpus}h / ${q.weeklyLimitOpus}h`);
+    }
+    if (q.burnRateTokensPerMin > 0) {
+        parts.push(`Burn rate:   ${q.burnRateTokensPerMin.toLocaleString()} tokens/min`);
+    }
+    return parts.join('\n');
+}
+function toolGetCurrentSession() {
+    const session = db_1.dbOps.getLatestSession();
+    if (!session)
+        return 'No sessions recorded yet.';
+    const cost = fmtDollar(session.total_cost_usd ?? 0);
+    const inp = fmtTok(session.total_input_tokens ?? 0);
+    const out = fmtTok(session.total_output_tokens ?? 0);
+    const cache = fmtTok(session.total_cache_read ?? 0);
+    const eff = session.efficiency_score ?? 100;
+    const loops = session.loops_detected ?? 0;
+    const started = new Date(session.started_at).toISOString();
+    const project = session.project_path ?? 'No project';
+    const model = session.dominant_model ?? 'unknown';
+    return [
+        `Latest session: ${session.id.slice(0, 8)}...`,
+        ``,
+        `Project:    ${project}`,
+        `Model:      ${model}`,
+        `Started:    ${started}`,
+        `Cost:       ${cost}`,
+        `Tokens:     ${inp} in + ${out} out  (${cache} cache read)`,
+        `Efficiency: ${eff}/100`,
+        `Loops:      ${loops}`,
+    ].join('\n');
+}
+function toolGetSessionStats(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const insight = db_1.dbOps.getWeeklyInsight(d);
+    if (!insight || insight.total_sessions === 0)
+        return `No sessions in the last ${d} days.`;
+    const totalTok = insight.input_tokens + insight.output_tokens;
+    return [
+        `Session stats — last ${d} days`,
+        ``,
+        `Sessions:     ${insight.total_sessions}`,
+        `Cost:         ${fmtDollar(insight.total_cost)}`,
+        `Tokens:       ${fmtTok(totalTok)} (${fmtTok(insight.input_tokens)} in + ${fmtTok(insight.output_tokens)} out)`,
+        `Cache read:   ${fmtTok(insight.cache_read)}`,
+        `Loops:        ${insight.total_loops}`,
+        `Efficiency:   ${Math.round(insight.avg_efficiency)}/100 avg`,
+    ].join('\n');
+}
+function toolGetTopTools(days, sortBy) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 30)));
+    const sort = (sortBy === 'count' || sortBy === 'duration') ? sortBy : 'cost';
+    const tools = db_1.dbOps.getTopTools(d, sort, 10);
+    if (tools.length === 0)
+        return `No tool usage data in the last ${d} days.`;
+    const lines = [
+        `Top tools — last ${d} days (sorted by ${sort})`,
+        '',
+    ];
+    for (let i = 0; i < tools.length; i++) {
+        const t = tools[i];
+        const idx = `${i + 1}.`.padEnd(4);
+        const name = t.tool_name.padEnd(14);
+        const cnt = `${t.count} calls`.padEnd(14);
+        const dur = t.total_duration_ms > 0
+            ? `${(t.total_duration_ms / 1000).toFixed(1)}s`.padEnd(10)
+            : '—'.padEnd(10);
+        const cost = fmtDollar(t.total_cost_usd);
+        lines.push(`  ${idx}${name}${cnt}${dur}${cost}`);
+    }
+    return lines.join('\n');
+}
+function toolGetWeeklyInsight(days) {
+    const d = Math.max(1, Math.min(90, Math.floor(days || 7)));
+    const data = (0, insights_1.getWeeklyInsightData)(d);
+    if (data.total_sessions === 0)
+        return `No usage data for the last ${d} days.`;
+    const fmtDate = (ts) => {
+        const dt = new Date(ts);
+        return dt.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+    };
+    return [
+        `Weekly insight (${fmtDate(data.week_start)} – ${fmtDate(data.week_end)})`,
+        `──────────────────────────────────────────────`,
+        `Sessions: ${data.total_sessions}  ·  Cost: ${fmtDollar(data.total_cost)}  ·  Loops: ${data.total_loops}`,
+        `Top tool: ${data.top_tool} (${data.top_tool_cost_pct}% of cost)  ·  Efficiency: ${data.avg_efficiency}/100`,
+        `Tokens: ${fmtTok(data.input_tokens)} in + ${fmtTok(data.output_tokens)} out  ·  Cache hit: ${data.cache_hit_pct}%`,
+        `Tip: ${(0, insights_1.generateTip)(data)}`,
+    ].join('\n');
+}
+function handleToolCall(name, args) {
+    const days = typeof args.days === 'number' ? args.days : 7;
+    const sortBy = typeof args.sort_by === 'string' ? args.sort_by : 'cost';
+    switch (name) {
+        case 'get_quota_status': return toolGetQuotaStatus();
+        case 'get_current_session': return toolGetCurrentSession();
+        case 'get_session_stats': return toolGetSessionStats(days);
+        case 'get_top_tools': return toolGetTopTools(days, sortBy);
+        case 'get_weekly_insight': return toolGetWeeklyInsight(days);
+        default: return `Unknown tool: ${name}`;
+    }
+}
+function handleRequest(msg) {
+    const { id, method, params } = msg;
+    if (id === undefined) {
+        if (method === 'notifications/initialized')
+            return null;
+        return null;
+    }
+    try {
+        switch (method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0', id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+                    }
+                };
+            case 'tools/list':
+                return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+            case 'tools/call': {
+                const toolName = params?.name;
+                const toolArgs = (params?.arguments ?? {});
+                const text = handleToolCall(toolName, toolArgs);
+                return {
+                    jsonrpc: '2.0', id,
+                    result: { content: [{ type: 'text', text }], isError: false }
+                };
+            }
+            default:
+                return {
+                    jsonrpc: '2.0', id,
+                    error: { code: -32601, message: `Method not found: ${method}` }
+                };
+        }
+    }
+    catch (e) {
+        return {
+            jsonrpc: '2.0', id,
+            result: { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+        };
+    }
+}
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    try {
+        const msg = JSON.parse(trimmed);
+        const response = handleRequest(msg);
+        if (response) {
+            process.stdout.write(JSON.stringify(response) + '\n');
+        }
+    }
+    catch (e) {
+        process.stderr.write(`[claudestat-mcp] Parse error: ${e.message}\n`);
+    }
+});
+process.on('SIGTERM', () => process.exit(0));
+process.on('SIGINT', () => process.exit(0));
+process.stderr.write(`[claudestat-mcp] Server ready (stdio, protocol ${PROTOCOL_VERSION})\n`);

package/dist/quota-tracker.d.ts

@@ -32,6 +32,7 @@ export interface QuotaData {
     weeklyTokensHaiku: number;
     weeklyLimitSonnet: number;
     weeklyLimitOpus: number;
+    weeklyPctAll: number;
     burnRateTokensPerMin: number;
     detectedPlan: ClaudePlan;
     planSource: 'config' | 'keychain' | 'inferred';

package/dist/quota-tracker.js

@@ -293,6 +293,10 @@ function computeQuota(forcePlan) {
     const burnRateTokensPerMin = recentAssistant.length > 0
         ? Math.round(totalRecentTok / 30)
         : 0;
+    // ─ % semanal combinado (Sonnet + Opus, coincide con "Todos los modelos" de claude.ai) ─
+    const weeklyPctAll = limits.weeklyHoursSonnet + limits.weeklyHoursOpus > 0
+        ? Math.min(100, Math.round((weeklyHoursSonnet + weeklyHoursOpus) / (limits.weeklyHoursSonnet + limits.weeklyHoursOpus) * 100))
+        : 0;
     const data = {
         cyclePrompts: cycleEntries.filter(e => e.type === 'human').length,
         cycleLimit: limits.prompts5h,
@@ -310,6 +314,7 @@ function computeQuota(forcePlan) {
         weeklyTokensHaiku,
         weeklyLimitSonnet: limits.weeklyHoursSonnet,
         weeklyLimitOpus: limits.weeklyHoursOpus,
+        weeklyPctAll,
         burnRateTokensPerMin,
         detectedPlan: plan,
         planSource,

package/dist/routes/events.js

@@ -75,7 +75,7 @@ exports.eventsRouter.post('/event', (req, res) => {
         return;
     }
     const resolvedCwd = cwd
-        ?? (transcript_path ? transcript_path.split('/').slice(0, -1).join('/') : undefined);
+        ?? (transcript_path ? path_1.default.dirname(transcript_path) || undefined : undefined);
     db_1.dbOps.upsertSession({ id: session_id, cwd: resolvedCwd, started_at: ts, last_event_at: ts });
     // Skill grouping: get current parent BEFORE processing this event
     // (the Skill Done event itself is NOT tagged — only its subsequent sub-calls are)
@@ -125,7 +125,7 @@ exports.eventsRouter.post('/event', (req, res) => {
         try {
             const inp = typeof tool_input === 'string' ? JSON.parse(tool_input) : (tool_input ?? {});
             const filePath = inp?.file_path ?? inp?.path;
-            if (typeof filePath === 'string' && filePath.startsWith('/')) {
+            if (typeof filePath === 'string' && path_1.default.isAbsolute(filePath)) {
                 const projectCwd = findProjectCwdForFile(filePath);
                 if (projectCwd)
                     db_1.dbOps.updateSessionProject(session_id, projectCwd);

package/dist/routes/projects.js

@@ -39,7 +39,7 @@ function inferProjectCwd(events) {
         try {
             const inp = JSON.parse(ev.tool_input);
             const filePath = (inp.file_path || inp.path);
-            if (!filePath?.startsWith('/'))
+            if (!filePath || !path_1.default.isAbsolute(filePath))
                 continue;
             const cwd = findProjectCwdForFile(filePath);
             if (cwd)
@@ -71,7 +71,7 @@ function inferActiveProjectByMajority(events, windowMs) {
         try {
             const inp = JSON.parse(ev.tool_input);
             const filePath = (inp.file_path || inp.path);
-            if (!filePath?.startsWith('/'))
+            if (!filePath || !path_1.default.isAbsolute(filePath))
                 continue;
             const project = findProjectCwdForFile(filePath);
             if (!project)

package/dist/share.js

@@ -1,8 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runShare = runShare;
 const db_js_1 = require("./db.js");
 const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
 function formatDuration(ms) {
     const seconds = Math.floor(ms / 1000);
     const minutes = Math.floor(seconds / 60);
@@ -45,7 +49,7 @@ async function getSessionData(sessionId) {
         topToolPct = Math.round((sorted[0][1] / toolCalls.length) * 100);
     }
     const durationMs = (session.last_event_at || session.started_at) - session.started_at;
-    const project = session.project_path?.split('/').pop() || 'unknown';
+    const project = path_1.default.basename(session.project_path ?? '') || 'unknown';
     return {
         id: session.id,
         project: project.length > 18 ? project.slice(0, 15) + '...' : project,

package/dist/summarizer.js

@@ -92,7 +92,7 @@ function buildContext(events, costUsd, projectName) {
         try {
             const inp = JSON.parse(e.tool_input);
             const fp = inp.file_path || inp.path;
-            if (typeof fp === 'string' && fp.startsWith('/')) {
+            if (typeof fp === 'string' && path_1.default.isAbsolute(fp)) {
                 filesSet.add(path_1.default.basename(fp));
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statforge/claudestat",
-  "version": "1.1.1",
+  "version": "1.2.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",
@@ -48,7 +48,8 @@
     "dashboard/dist/"
   ],
   "bin": {
-    "claudestat": "dist/index.js"
+    "claudestat": "dist/index.js",
+    "claudestat-mcp": "dist/mcp-server.js"
   },
   "scripts": {
     "build": "tsc && npm run build:dashboard",
@@ -58,7 +59,7 @@
     "dev": "tsx src/index.ts",
     "dev:full": "tsx src/index.ts start & sleep 1 && cd dashboard && npm run dev",
     "start": "node dist/index.js",
-    "test": "bash run-tests.sh"
+    "test": "node --require tsx/cjs tests/index.ts"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",