@statforge/claudestat 1.2.3 → 1.3.0

package/README.md

@@ -2,9 +2,11 @@
 
 # claudestat
 
-**Real-time execution trace and cost intelligence for Claude Code**
+**Live Claude Code monitor — real-time trace, quota guard, and MCP server**
+
+Most tools read your logs after a session ends. claudestat hooks into every event as it fires.
+See what Claude is spending right now, get alerted before you hit your quota, and ask Claude about its own usage — from inside the terminal.
 
-Hook into every tool call, token, and dollar — as it happens.
 Works with Claude Pro, Max 5, and Max 20. Zero cloud dependencies. Pure Node.js. Runs on macOS, Linux, and Windows.
 
 [![npm version](https://img.shields.io/npm/v/@statforge/claudestat?color=blue)](https://www.npmjs.com/package/@statforge/claudestat)
@@ -17,7 +19,7 @@ Works with Claude Pro, Max 5, and Max 20. Zero cloud dependencies. Pure Node.js.
 
 [Installation](#installation) • [Quick Start](#quick-start) • [Commands](#commands) • [Dashboard](#dashboard) • [Contributing](#contributing)
 
-![ClaudeStat dashboard](https://res.cloudinary.com/dgscloudinary/image/upload/v1778225605/My%20portfolio%7D/ClaudeStat_vnfmup.png)
+![ClaudeStat banner](https://raw.githubusercontent.com/DeibyGS/claudestat/main/assets/banner.png)
 
 ---
 
@@ -31,26 +33,57 @@ Works with Claude Pro, Max 5, and Max 20. Zero cloud dependencies. Pure Node.js.
 
 ---
 
-## Why?
+## Why claudestat?
+
+Tools like ccusage are great for reviewing history. claudestat is for while you're coding.
 
-You're burning tokens right now and you have no idea how many, on what, or whether Claude is stuck in a loop.
+It taps into Claude Code's hook system to capture every event the moment it fires, stores everything locally in SQLite, and gives you a live dashboard, quota alerts, and an MCP server — not just a report.
 
-Claude Code is powerful — but it's a black box while it runs. You can't see what it's spending, how deep the context is, whether it's looping, or if you're about to hit your quota limit.
+| | claudestat | ccusage |
+|---|:---:|:---:|
+| Real-time event stream | ✅ | ❌ |
+| Live terminal trace (`watch`) | ✅ | ❌ |
+| Web dashboard | ✅ | ❌ |
+| Quota alerts + kill switch | ✅ | ❌ |
+| Loop detector | ✅ | ❌ |
+| MCP server (ask Claude about itself) | ✅ | ❌ |
+| Historical usage analysis | ✅ | ✅ |
 
-**claudestat fixes that.** It taps into Claude Code's hook system to capture every event, stores it locally in SQLite, and shows you everything in a live dashboard or terminal trace.
+**What you get:**
 
-- Live tool trace with duration and token cost per call
-- 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
+- Live tool trace — every call with duration and token cost as it runs
+- Quota guard — alerts at 70%, 85%, 95%; optional kill switch blocks new sessions at X%
+- Loop detector — flags context thrashing with estimated waste cost
+- Top tools — know which tools eat most of your budget
+- Web dashboard — session history, analytics, model breakdown, charts
+- MCP server — 7 tools so Claude can answer questions about its own usage
+- Weekly insights — pattern analysis with actionable tips
 
 > If claudestat is useful, give it a ⭐ — it helps other developers find it.
 
 ---
 
+## Ask Claude about itself
+
+claudestat ships an MCP server. Once registered, you can ask Claude Code questions about its own usage — without leaving the terminal.
+
+```bash
+claude mcp add claudestat -s user -- claudestat-mcp
+```
+
+Then just ask:
+
+```
+> What's my current quota status?
+> How much did I spend this week?
+> What are my top 5 tools by cost?
+> Break down my usage by model
+```
+
+Claude reads your local SQLite data through the MCP server and answers in real time. No cloud, no API key, no extra setup. [Full MCP reference →](#mcp-server)
+
+---
+
 ## How it works
 
 ```
@@ -478,6 +511,8 @@ Once registered, ask Claude things like:
 - *"Give me usage insights for the last 14 days"*
 - *"Break down my usage by model"*
 
+![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.
 
 ---
@@ -673,9 +708,8 @@ Want to appear here? Pick a [good-first-issue](https://github.com/DeibyGS/claude
 
 ## FAQ
 
-**What is claudestat?**
-claudestat is a real-time token monitoring and cost analytics tool for Claude Code.
-It captures every tool call, token usage, and API cost as it happens — locally, with zero cloud dependencies.
+**What is claudestat? How is it different from ccusage?**
+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.

package/dist/index.js

@@ -24,6 +24,7 @@ const daemon_1 = require("./daemon");
 const watchdog_1 = require("./watchdog");
 const watch_1 = require("./watch");
 const install_1 = require("./install");
+const service_1 = require("./service");
 const export_1 = require("./export");
 const config_1 = require("./config");
 const doctor_1 = require("./doctor");
@@ -186,14 +187,34 @@ program
     console.error('\n❌ Error:', err.message);
     process.exit(1);
 }));
+program
+    .command('setup')
+    .description('One-command setup: install hooks + register daemon as system service (auto-starts on login)')
+    .option('--uninstall', 'Remove hooks and system service')
+    .action(async (opts) => {
+    if (opts.uninstall) {
+        console.log('Uninstalling claudestat...');
+        (0, service_1.uninstallService)();
+        (0, install_1.uninstallHooks)();
+        await stopDaemon().catch(() => { });
+        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');
+    process.exit(0);
+});
 program
     .command('install')
     .description('Install hooks into Claude Code settings')
-    .action(install_1.runInstall);
+    .action(async () => { await (0, install_1.runInstall)(); process.exit(0); });
 program
     .command('uninstall')
     .description('Remove hooks from Claude Code')
-    .action(install_1.uninstallHooks);
+    .action(() => { (0, install_1.uninstallHooks)(); process.exit(0); });
 program
     .command('export [format]')
     .description('Export session data (json | csv, default: json). Max 500 sessions.')

package/dist/mcp-server.js

@@ -40,6 +40,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 process.on('warning', (w) => {
     if (w.name === 'ExperimentalWarning' && w.message.includes('SQLite'))
@@ -47,10 +50,27 @@ process.on('warning', (w) => {
     process.stderr.write(`${w.name}: ${w.message}\n`);
 });
 const readline = __importStar(require("readline"));
+const fs_1 = __importDefault(require("fs"));
 const db_1 = require("./db");
 const quota_tracker_1 = require("./quota-tracker");
 const insights_1 = require("./insights");
 const config_1 = require("./config");
+const paths_1 = require("./paths");
+function isDaemonRunning() {
+    try {
+        const pid = parseInt(fs_1.default.readFileSync((0, paths_1.getPidFile)(), 'utf8').trim(), 10);
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const DAEMON_WARNING = `⚠️ claudestat daemon is not running — real-time monitoring is disabled.
+Start it with: claudestat start
+
+Data shown below is from the last recorded session.
+---`;
 const SERVER_NAME = 'claudestat';
 const SERVER_VERSION = '1.2.2';
 const PROTOCOL_VERSION = '2025-03-26';
@@ -364,17 +384,18 @@ function toolGetWeeklyInsight(days) {
     ].join('\n');
 }
 async function handleToolCall(name, args) {
+    const warning = isDaemonRunning() ? '' : DAEMON_WARNING + '\n';
     const sortBy = typeof args.sort_by === 'string' ? args.sort_by : 'cost';
     switch (name) {
         case 'get_quota_status':
             await (0, quota_tracker_1.refreshFromApi)();
-            return toolGetQuotaStatus();
-        case 'get_current_session': return toolGetCurrentSession();
-        case 'get_session_stats': return toolGetSessionStats(typeof args.days === 'number' ? args.days : 7);
-        case 'get_top_tools': return toolGetTopTools(typeof args.days === 'number' ? args.days : 30, sortBy);
-        case 'get_usage_insights': return toolGetUsageInsights(typeof args.days === 'number' ? args.days : 7);
-        case 'get_model_breakdown': return toolGetModelBreakdown(typeof args.days === 'number' ? args.days : 7);
-        case 'get_weekly_insight': return toolGetWeeklyInsight(typeof args.days === 'number' ? args.days : 7);
+            return warning + toolGetQuotaStatus();
+        case 'get_current_session': return warning + toolGetCurrentSession();
+        case 'get_session_stats': return warning + toolGetSessionStats(typeof args.days === 'number' ? args.days : 7);
+        case 'get_top_tools': return warning + toolGetTopTools(typeof args.days === 'number' ? args.days : 30, sortBy);
+        case 'get_usage_insights': return warning + toolGetUsageInsights(typeof args.days === 'number' ? args.days : 7);
+        case 'get_model_breakdown': return warning + toolGetModelBreakdown(typeof args.days === 'number' ? args.days : 7);
+        case 'get_weekly_insight': return warning + toolGetWeeklyInsight(typeof args.days === 'number' ? args.days : 7);
         default: return `Unknown tool: ${name}`;
     }
 }

package/dist/service.d.ts

@@ -0,0 +1,2 @@
+export declare function installService(): void;
+export declare function uninstallService(): void;

package/dist/service.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installService = installService;
+exports.uninstallService = uninstallService;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const PLIST_LABEL = 'com.statforge.claudestat';
+const PLIST_PATH = path_1.default.join(process.env.HOME ?? '~', 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+const SYSTEMD_DIR = path_1.default.join(process.env.HOME ?? '~', '.config', 'systemd', 'user');
+const SYSTEMD_PATH = path_1.default.join(SYSTEMD_DIR, 'claudestat.service');
+function makePlist() {
+    const node = process.execPath;
+    const script = process.argv[1];
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${PLIST_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${script}</string>
+    <string>start</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CLAUDESTAT_DAEMON</key>
+    <string>1</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/claudestat-daemon.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/claudestat-daemon.err</string>
+</dict>
+</plist>`;
+}
+function makeUnit() {
+    const node = process.execPath;
+    const script = process.argv[1];
+    return `[Unit]
+Description=ClaudeStat daemon — real-time Claude Code monitor
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${node} ${script} start
+Restart=on-failure
+RestartSec=5
+Environment=CLAUDESTAT_DAEMON=1
+
+[Install]
+WantedBy=default.target`;
+}
+function installService() {
+    if (process.platform === 'darwin') {
+        fs_1.default.mkdirSync(path_1.default.dirname(PLIST_PATH), { recursive: true });
+        try {
+            (0, child_process_1.execSync)(`launchctl unload "${PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' });
+        }
+        catch { }
+        fs_1.default.writeFileSync(PLIST_PATH, makePlist());
+        (0, child_process_1.execSync)(`launchctl load "${PLIST_PATH}"`);
+        console.log(`   service  → ${PLIST_PATH}`);
+        console.log(`   node     → ${process.execPath}`);
+    }
+    else if (process.platform === 'linux') {
+        const hasSystemd = (() => {
+            try {
+                (0, child_process_1.execSync)('which systemctl', { stdio: 'pipe' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!hasSystemd) {
+            console.log('   systemd not found — run `claudestat start` manually to start the daemon');
+            return;
+        }
+        fs_1.default.mkdirSync(SYSTEMD_DIR, { recursive: true });
+        fs_1.default.writeFileSync(SYSTEMD_PATH, makeUnit());
+        (0, child_process_1.execSync)('systemctl --user daemon-reload');
+        (0, child_process_1.execSync)('systemctl --user enable --now claudestat');
+        console.log(`   service  → ${SYSTEMD_PATH}`);
+        console.log(`   node     → ${process.execPath}`);
+    }
+    else {
+        console.log('   Auto-start on Windows coming soon. Run `claudestat start` manually.');
+    }
+}
+function uninstallService() {
+    if (process.platform === 'darwin') {
+        try {
+            (0, child_process_1.execSync)(`launchctl unload "${PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' });
+        }
+        catch { }
+        try {
+            fs_1.default.unlinkSync(PLIST_PATH);
+            console.log(`   removed  → ${PLIST_PATH}`);
+        }
+        catch {
+            console.log('   service file not found (already removed)');
+        }
+    }
+    else if (process.platform === 'linux') {
+        try {
+            (0, child_process_1.execSync)('systemctl --user disable --now claudestat 2>/dev/null', { stdio: 'ignore' });
+        }
+        catch { }
+        try {
+            fs_1.default.unlinkSync(SYSTEMD_PATH);
+            (0, child_process_1.execSync)('systemctl --user daemon-reload');
+            console.log(`   removed  → ${SYSTEMD_PATH}`);
+        }
+        catch {
+            console.log('   service file not found (already removed)');
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statforge/claudestat",
-  "version": "1.2.3",
+  "version": "1.3.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",