@statforge/claudestat 1.2.0 → 1.2.2

package/README.md

@@ -12,7 +12,7 @@ Works with Claude Pro, Max 5, and Max 20. Zero cloud dependencies. Pure Node.js.
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-brightgreen)]()
-[![Tests](https://img.shields.io/badge/tests-214%2F214-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-243%2F243-brightgreen)]()
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 [Installation](#installation) • [Quick Start](#quick-start) • [Commands](#commands) • [Dashboard](#dashboard) • [Contributing](#contributing)
@@ -139,13 +139,14 @@ That's it. Start a Claude Code session and watch the events flow in.
 | `claudestat uninstall` | Remove hooks from Claude Code |
 | `claudestat watch` | Live terminal trace view |
 | `claudestat status` | Show quota, cost, and burn rate |
-| `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 insights` | Deep usage insights: cost breakdown, cache savings, efficiency, peak hours, model breakdown |
 | `claudestat roast` | Sarcastic usage analysis with roast jokes |
+| `claudestat roast --stats` | Raw stats with visual bars |
+| `claudestat version` | Show version and check for npm updates |
+| `claudestat export [format]` | Export session data to JSON or CSV |
 | `claudestat doctor` | Check installation health and diagnose issues |
 
 ### `claudestat watch`
@@ -173,15 +174,32 @@ Ranks your most-used tools by estimated cost, call count, or duration across all
 ```
 claudestat top
 
-  🏆 claudestat top — by est. cost (last 30 days)
-
-  #  Tool              Calls    Duration   Est. Cost      %
-  ── ───────────────── ──────── ───────────── ───────── ────
-   1  Bash              1,240       18.3m     $1.24    38%
-   2  Read                890        4.1m     $0.87    27%
-   3  Edit                430        2.8m     $0.61    19%
-   4  Agent (haiku)       120        9.2m     $0.38    12%
-   5  Write               210        1.1m     $0.12     4%
+🏆 claudestat top  by est. cost (last 30 days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   1  Edit                ████████████████░░░░     $146.47  21%
+     2479 calls · 38.5m
+   2  Bash                ███████████████░░░░░     $140.66  20%
+     2651 calls · 153.6m
+   3  Read                ██████████████░░░░░░     $126.08  18%
+     2315 calls · 34.0m
+   4  Grep                ████░░░░░░░░░░░░░░░░      $39.93  6%
+     699 calls · 9.3m
+   5  ToolSearch          ██░░░░░░░░░░░░░░░░░░      $21.83  3%
+     469 calls · 7.4m
+   6  Glob                ██░░░░░░░░░░░░░░░░░░      $13.96  2%
+     269 calls · 5.7m
+   7  Write               █░░░░░░░░░░░░░░░░░░░      $12.93  2%
+     237 calls · 87.1m
+   8  mcp__plugin_engr…   █░░░░░░░░░░░░░░░░░░░       $8.10  1%
+     149 calls · 2.6m
+   9  Agent               █░░░░░░░░░░░░░░░░░░░       $8.09  1%
+     168 calls · 95.7m
+  10  WebFetch            █░░░░░░░░░░░░░░░░░░░       $5.86  1%
+     106 calls · 9.9m
+  Other                     —     $184.79  26%
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Options: `--by cost|count|duration` · `--days 7|30|90` · `--limit N`
@@ -193,88 +211,177 @@ Weekly usage summary with an actionable tip. Detects patterns like Bash overuse,
 ```
 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
+📊 claudestat weekly  May 8 – May 13
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  💰  $198.38 total  ·  40 sessions  ·  114 loops
+
+  🔧  Top tool    Bash  22% of cost
+
+  📈  Efficiency    ██████████████████░░  91/100
+
+  💾  Cache hit     ████████████████████  100%
+
+  📦  Tokens  73K in + 1.2M out
+
+  ⚡  Tip: 114 loops detected — consider using /compact earlier to prevent context thrashing
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 Options: `--json` for machine-readable output.
 
 ### `claudestat status`
 
+Shows your current quota usage with visual progress bars, plan detection, and burn rate.
+
 ```
 claudestat status
 
-  Quota 5h   45/50 prompts (90%)  |  reset in 22m
-  Plan        MAX5
-  Weekly      3.5h / 40h (9%)  this week
-  Burn rate   1,240 tok/min
+📊 claudestat  PRO plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  5h      ████████████████████  100%   resets 4:10 AM
+
+  Week    ██████░░░░░░░░░░░░░░  31%   resets May 18
+
+  🔥 490 tok/min  ·  101 prompts used
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### `claudestat status --compact`
+Options: `--json` for machine-readable output.
 
-One-line output for tmux status bar or scripting. Shows cycle quota and weekly usage with colored emoji.
+### `claudestat insights`
+
+Deep usage insights: cost breakdown by project, cache savings, output/input ratio, efficiency trend, peak activity hours, and model breakdown.
 
-```bash
-claudestat status --compact
-C:45%🟡 W:9%🟢 pro
 ```
+claudestat insights
 
-### `claudestat share`
+💡 claudestat insights  last 7 days
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Generate a shareable session card — perfect for sharing on social media or in bug reports.
+  💰  $4.96/session  ·  40 sessions  ·  $198.38 total
 
-```bash
-claudestat share
-╔═══════════════════════════════════╗
-║     Session Report · claudestat   ║
-╠═══════════════════════════════════╣
-║  Project     my-project          ║
-║  Duration   2h 14m               ║
-║  Tools      847 calls            ║
-║  Cost       $0.84                ║
-║  Cache hit  27% saved ($0.31)    ║
-║  Top tool  Bash (38%)            ║
-║  Efficiency 91 / 100             ║
-╚═══════════════════════════════════╝
-  github.com/DeibyGS/claudestat
+  🗂  Top projects
+     no project      █████████░░░░░░░░░░░  $93.69  47%
+
+     claudestat      ████████░░░░░░░░░░░░  $74.60  38%
+
+     wodrival        ███░░░░░░░░░░░░░░░░░  $24.95  13%
+
+     aprendiendo-in  ░░░░░░░░░░░░░░░░░░░░  $3.32  2%
+
+     other           ░░░░░░░░░░░░░░░░░░░░  $1.81  1%
+
+  ⚡  Cache ~$1029.43 saved  ·  100% hit rate
+
+  📊  16× output/input  ·  cache-heavy workload
+
+  📈  Efficiency  91/100  ↓ -2 vs prev period  ·  114 loops
+
+  ⏰  Activity by time of day
+     🌙  00:00–05:59  ████████████████████  18 sessions
+
+     🌅  06:00–11:59  ███████░░░░░░░░░░░░░   6 sessions
+
+     ☀️  12:00–17:59  ███░░░░░░░░░░░░░░░░░   3 sessions
+
+     🌆  18:00–23:59  ██████████████░░░░░░  13 sessions
+
+  🤖  Models
+     claude-sonnet-4-6             ████████████████████  $197.11  99% · 23 sessions
+
+     claude-haiku-4-5-20251001     ░░░░░░░░░░░░░░░░░░░░  $1.26  1% · 15 sessions
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Options:
-- `--format ascii|json` — output format (default: ascii)
-- `--copy` — copy to clipboard automatically (macOS only)
+Options: `--days 7|14|30|90` · `--json` for machine-readable output.
 
-### `claudestat roast`
+### `claudestat config`
 
-Get a sarcastic analysis of your Claude Code usage — humor with insights.
+```
+claudestat config
+
+⚙️  claudestat config
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Plan              PRO
+  Alerts            enabled
+
+  Kill switch       OFF
+                    ████████████████████
+
+  Cycle thresholds  70%, 85%, 95%
+                    yellow ████████░░  orange █████████░  red ██████████
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
 ```bash
-claudestat roast
+# Enable kill switch at 90% quota
+claudestat config --kill-switch true --threshold 90
+
+# Force plan detection
+claudestat config --plan max5   # pro | max5 | max20 | auto
 
-=== Claude Code Stats (last 30 days) ===
-Sessions: 47
-Total cost: $12.40
-Bash calls: 1,240
-Loops: 8
-Efficiency: 72/100
+# Toggle daemon rate limit alerts
+claudestat config --alerts false
+```
 
-🔥 Your Claude Code Roast
+Config is stored at `~/.claudestat/config.json` (macOS/Linux) or `%USERPROFILE%\.claudestat\config.json` (Windows).
 
-  You called Bash 1,240 times last month.
-  That's once every 2.3 minutes.
-  Are you okay?
+### `claudestat roast`
 
-  You hit 90%+ context in 12 sessions.
-  Claude was writing with amnesia half the time.
+Get a sarcastic analysis of your Claude Code usage — humor with insights.
 
-  You spent $4.20 on loops you never noticed.
-  That's 14 coffees. Just saying.
+```bash
+claudestat roast
 
-  Efficiency: 72/100 — room for growth, champ.
+🔥 Your Claude Code Roast  (30 days)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Score  ██████████████████░░  92/100  ★★★★★
+
+  Scorecard
+  ┌─────────────────┬──────────────┬──────────────┐
+  │ Metric          │ Value        │ Rating       │
+  ├─────────────────┼──────────────┼──────────────┤
+  │ Sessions        │ 47           │ normal       │
+  │ Total cost      │ $12.40       │ frugal       │
+  │ Avg/session     │ $0.26/session│ efficient    │
+  │ Bash calls      │ 1240         │ 🔨 overload  │
+  │ Loops           │ 8            │ clean        │
+  │ Efficiency      │ 92/100       │ 🏆 elite     │
+  │ Tokens          │ 4.2M         │ —            │
+  │ Top tool        │ Bash 38%     │ —            │
+  └─────────────────┴──────────────┴──────────────┘
+
+  Roast Cards
+
+  ┌──────────────────────────────────────────────────┐
+  │ 🖥️  BASH OVERLOAD                                │
+  │ 1240 calls in 30d — once every 2.3 min           │
+  │ Are you okay?                                    │
+  └──────────────────────────────────────────────────┘
+
+  ┌──────────────────────────────────────────────────┐
+  │ 🔄  LOOP MONEY PIT                               │
+  │ $4.20 wasted on loops — that's 14 coffees        │
+  │ Just saying.                                     │
+  └──────────────────────────────────────────────────┘
+
+  Verdict
+  You're a machine. Or maybe you're just not using Claude enough.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  github.com/DeibyGS/claudestat
 ```
 
+Options: `--stats` for raw stats with visual bars · `--months N` to look back N months.
+
 ### `claudestat doctor`
 
 Diagnoses common installation problems — useful if `claudestat start` fails or hooks are not firing.
@@ -291,6 +398,9 @@ claudestat doctor
   ✓  Hook script deployed (~/.claudestat/hooks/event.js)
   ✓  Daemon running (localhost:7337)
   ✓  Global CLI symlink valid
+  ✓  No duplicate claudestat binaries in PATH
+  ✓  Version match (installed: v1.2.2)
+  ✓  NVM prefix matches active binary
 ──────────────────────────────────────────────
   All checks passed — claudestat is healthy!
 ```
@@ -299,6 +409,19 @@ If a check fails, `doctor` prints the exact fix command to run.
 
 ---
 
+### `claudestat version`
+
+Shows the current version and checks npm for updates.
+
+```bash
+claudestat version
+
+1.2.2
+  latest ✓
+```
+
+If a newer version is available, it shows: `latest: 1.3.0 — run npm update`.
+
 ### `claudestat export`
 
 Export session data to JSON or CSV. Supports date and project filters.
@@ -326,23 +449,6 @@ Each row includes: `id`, `started_at`, `cwd`, `project_path`, `total_cost_usd`,
 
 ---
 
-### `claudestat config`
-
-```bash
-# Enable kill switch — block new sessions when quota exceeds 95%
-claudestat config --kill-switch true --threshold 95
-
-# Force plan detection instead of auto
-claudestat config --plan max5   # pro | max5 | max20 | auto
-
-# Disable daemon rate limit alerts
-claudestat config --alerts false
-```
-
-Config is stored at `~/.claudestat/config.json` (macOS/Linux) or `%USERPROFILE%\.claudestat\config.json` (Windows).
-
----
-
 ## 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.
@@ -351,10 +457,12 @@ claudestat includes an MCP (Model Context Protocol) server that lets Claude Code
 
 | Tool | Description |
 |------|------------|
-| `get_quota_status` | 5h cycle usage %, plan, weekly hours, burn rate |
+| `get_quota_status` | 5h cycle usage %, plan, weekly hours, burn rate (with on-demand API refresh + disk cache) |
 | `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_top_tools` | Top 10 tools by cost/count/duration (default 30 days) |
+| `get_usage_insights` | Deep insights: cost per project, cache savings, efficiency trend, peak hours, model breakdown |
+| `get_model_breakdown` | Cost and session count broken down by Claude model (Sonnet, Haiku, Opus) |
 | `get_weekly_insight` | Weekly summary with actionable tip |
 
 ### Register with Claude Code
@@ -367,8 +475,10 @@ 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?"*
+- *"Give me usage insights for the last 14 days"*
+- *"Break down my usage by model"*
 
-Zero extra dependencies — stdio JSON-RPC, works without the daemon running.
+Zero extra dependencies — stdio JSON-RPC, works without the daemon running. Uses on-demand API refresh with shared disk cache for accurate quota data.
 
 ---
 
@@ -525,7 +635,7 @@ Whether you want to fix a bug, improve a dashboard view, add a new pattern to th
 1. Fork the repository
 2. Create a branch: `git checkout -b feat/your-feature`
 3. Make your changes
-4. Run the test suite: `npm test` (208 tests)
+4. Run the test suite: `node --require tsx/cjs tests/index.ts` (243 tests)
 5. Open a PR with a clear description of what you changed and why
 
 ### Good first areas
@@ -542,11 +652,13 @@ git clone https://github.com/YOUR_USERNAME/claudestat
 cd claudestat
 npm install
 npm run dev:full   # starts daemon + dashboard hot-reload together
-npm test           # run all tests
+node --require tsx/cjs tests/index.ts   # run all tests
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
 
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
 ---
 
 ## Contributors

package/dist/claude-auth.d.ts

@@ -18,7 +18,14 @@ export interface ClaudeAuthInfo {
     expiresAt: number;
     tokenValid: boolean;
     source: 'keychain' | 'file' | 'unknown';
+    accessToken?: string;
 }
+/**
+ * Devuelve el accessToken OAuth para autenticar llamadas a la API de Anthropic.
+ * Usa el mismo caché de 5 minutos que readClaudeAuth().
+ * Retorna null si no hay credenciales disponibles (Linux sin configurar, token expirado).
+ */
+export declare function getOAuthAccessToken(): string | null;
 /**
  * Lee las credenciales de autenticación de Claude Code.
  * Intenta: keychain (macOS) → archivo → unknown.

package/dist/claude-auth.js

@@ -17,6 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOAuthAccessToken = getOAuthAccessToken;
 exports.readClaudeAuth = readClaudeAuth;
 exports.subscriptionTypeToPlan = subscriptionTypeToPlan;
 const child_process_1 = require("child_process");
@@ -50,6 +51,7 @@ function readFromKeychain() {
             expiresAt: oa.expiresAt ?? 0,
             tokenValid: Date.now() < (oa.expiresAt ?? 0),
             source: 'keychain',
+            accessToken: oa.accessToken,
         };
     }
     catch {
@@ -82,6 +84,7 @@ function readFromFile() {
                 expiresAt: oa.expiresAt ?? 0,
                 tokenValid: Date.now() < (oa.expiresAt ?? 0),
                 source: 'file',
+                accessToken: oa.accessToken,
             };
         }
         catch {
@@ -90,6 +93,15 @@ function readFromFile() {
     }
     return null;
 }
+// ─── Token OAuth para llamadas a la API ───────────────────────────────────────
+/**
+ * Devuelve el accessToken OAuth para autenticar llamadas a la API de Anthropic.
+ * Usa el mismo caché de 5 minutos que readClaudeAuth().
+ * Retorna null si no hay credenciales disponibles (Linux sin configurar, token expirado).
+ */
+function getOAuthAccessToken() {
+    return readClaudeAuth().accessToken ?? null;
+}
 // ─── API pública ──────────────────────────────────────────────────────────────
 /**
  * Lee las credenciales de autenticación de Claude Code.

package/dist/config.d.ts

@@ -23,6 +23,8 @@ export interface ClaudestatConfig {
     killSwitchEnabled: boolean;
     killSwitchThreshold: number;
     warnThresholds: number[];
+    weeklyWarnThresholds: number[];
+    resetReminderMins: number;
     plan: ClaudePlan | null;
     reportsEnabled: boolean;
     reportFrequency: ReportFrequency;

package/dist/config.js

@@ -34,6 +34,8 @@ const DEFAULTS = {
     killSwitchEnabled: false,
     killSwitchThreshold: 95,
     warnThresholds: [70, 85, 95],
+    weeklyWarnThresholds: [50, 75, 90],
+    resetReminderMins: 10,
     plan: null,
     reportsEnabled: false,
     reportFrequency: 'weekly',
@@ -80,6 +82,16 @@ function validateConfig(raw) {
     }
     if ('plan' in cfg && !VALID_PLANS.has(cfg.plan))
         return `plan debe ser uno de: free, pro, max5, max20 o null`;
+    if ('weeklyWarnThresholds' in cfg) {
+        const v = cfg.weeklyWarnThresholds;
+        if (!Array.isArray(v) || v.length !== 3 || v.some(n => typeof n !== 'number' || isNaN(n) || n < 1 || n > 100))
+            return 'weeklyWarnThresholds must be an array of 3 numbers between 1 and 100';
+    }
+    if ('resetReminderMins' in cfg) {
+        const v = cfg.resetReminderMins;
+        if (typeof v !== 'number' || isNaN(v) || v < 0 || v > 60)
+            return 'resetReminderMins must be a number between 0 and 60';
+    }
     if ('alertsEnabled' in cfg && typeof cfg.alertsEnabled !== 'boolean')
         return 'alertsEnabled debe ser boolean';
     if ('reportsEnabled' in cfg && typeof cfg.reportsEnabled !== 'boolean')

package/dist/daemon.js

@@ -139,7 +139,7 @@ async function migrateSessionSummaries(limit = 5) {
             const summary = await (0, summarizer_1.summarizeSession)(events, s.total_cost_usd ?? 0, projectName);
             if (summary) {
                 db_1.dbOps.updateSessionSummary(s.id, summary);
-                console.log(`[daemon] Summary generado para sesión ${s.id.slice(0, 8)}: "${summary}"`);
+                console.log(`[daemon] Summary generated for session ${s.id.slice(0, 8)}: "${summary}"`);
             }
         }
         catch (err) {
@@ -175,7 +175,20 @@ const LEVEL_COLOR = {
     orange: '\x1b[33m',
     red: '\x1b[31m',
 };
-let _lastAlertLevel = null;
+let _lastCycleAlertLevel = null;
+let _lastWeeklyAlertLevel = null;
+let _resetReminderFired = false;
+function checkAlertLevel(level, lastLevel, logMsg, notifTitle, notifBody) {
+    if (!level)
+        return null;
+    const prevRank = lastLevel ? LEVEL_RANK[lastLevel] ?? 0 : 0;
+    const currRank = LEVEL_RANK[level];
+    if (currRank > prevRank) {
+        process.stderr.write(`${LEVEL_COLOR[level]}${logMsg}\x1b[0m\n`);
+        (0, notifier_1.sendDesktopNotification)(notifTitle, notifBody);
+    }
+    return currRank > prevRank ? level : lastLevel;
+}
 function startAlertPolling() {
     alertInterval = setInterval(() => {
         try {
@@ -183,20 +196,23 @@ function startAlertPolling() {
             if (!cfg.alertsEnabled)
                 return;
             const data = (0, quota_tracker_1.computeQuota)(cfg.plan ?? undefined);
-            const level = (0, config_1.getWarnLevel)(data.cyclePct, cfg.warnThresholds);
-            if (!level) {
-                _lastAlertLevel = null;
-                return;
-            }
-            const prevRank = _lastAlertLevel ? LEVEL_RANK[_lastAlertLevel] ?? 0 : 0;
-            const currRank = LEVEL_RANK[level] ?? 0;
-            if (currRank > prevRank) {
-                const color = LEVEL_COLOR[level];
-                process.stderr.write(`${color}[claudestat] ⚠️  Rate limit alert: ${data.cyclePct}% of quota used (${data.cyclePrompts}/${data.cycleLimit} prompts)\x1b[0m\n`);
-                if (data.cyclePct >= cfg.killSwitchThreshold) {
-                    (0, notifier_1.sendDesktopNotification)('claudestat — Rate limit warning', `${data.cyclePct}% of 5h quota used (${data.cyclePrompts}/${data.cycleLimit} prompts)`);
+            const resetMins = Math.ceil(data.cycleResetMs / 60000);
+            // ── Cycle 5h alerts ──────────────────────────────────────────────────────
+            _lastCycleAlertLevel = checkAlertLevel((0, config_1.getWarnLevel)(data.cyclePct, cfg.warnThresholds), _lastCycleAlertLevel, `[claudestat] ⚠️  5h cycle at ${data.cyclePct}% (${data.cyclePrompts}/${data.cycleLimit} prompts)`, 'claudestat — 5h cycle alert', `${data.cyclePct}% of cycle used · resets in ${resetMins}m`);
+            // ── Weekly alerts ────────────────────────────────────────────────────────
+            _lastWeeklyAlertLevel = checkAlertLevel((0, config_1.getWarnLevel)(data.weeklyPctAll, cfg.weeklyWarnThresholds), _lastWeeklyAlertLevel, `[claudestat] ⚠️  Weekly usage at ${data.weeklyPctAll}%`, 'claudestat — Weekly usage alert', `${data.weeklyPctAll}% of weekly quota used`);
+            // ── Reset reminder ───────────────────────────────────────────────────────
+            const reminderMs = (cfg.resetReminderMins ?? 10) * 60000;
+            if (reminderMs > 0) {
+                if (data.cycleResetMs > reminderMs * 1.5) {
+                    _resetReminderFired = false; // cycle reset happened — arm reminder again
+                }
+                else if (data.cycleResetMs <= reminderMs && data.cycleResetMs > 0 && !_resetReminderFired) {
+                    const mins = Math.ceil(data.cycleResetMs / 60000);
+                    process.stderr.write(`\x1b[36m[claudestat] ⏰  Quota resets in ${mins}m — good time to wrap up\x1b[0m\n`);
+                    (0, notifier_1.sendDesktopNotification)('claudestat — Quota reset soon', `Your 5h cycle resets in ${mins} min — good time to start a new task`);
+                    _resetReminderFired = true;
                 }
-                _lastAlertLevel = level;
             }
         }
         catch {
@@ -281,6 +297,7 @@ function startDaemon() {
         }
         // Polling de alertas de rate limit cada 60s
         startAlertPolling();
+        // API quota data is refreshed on-demand by the CLI status command (disk cache shared)
     });
     // Manejo de error de puerto ocupado — fuera del callback para capturar EADDRINUSE
     _server.on('error', (err) => {

package/dist/db.d.ts

@@ -144,4 +144,22 @@ export declare const dbOps: {
         earliest: number;
         latest: number;
     };
+    getProjectCosts(days?: number): {
+        project: string;
+        session_count: number;
+        total_cost: number;
+    }[];
+    getHourlyDistribution(days?: number): {
+        hour: number;
+        session_count: number;
+    }[];
+    getCacheReadByModel(days: number): {
+        model: string;
+        cache_read: number;
+    }[];
+    getModelBreakdown(days: number): {
+        model: string;
+        total_cost: number;
+        session_count: number;
+    }[];
 };

package/dist/db.js

@@ -416,6 +416,26 @@ const stmts = {
       MAX(last_event_at)   AS latest
     FROM sessions
     WHERE started_at >= ?
+  `),
+    getProjectCosts: db.prepare(`
+    SELECT
+      COALESCE(project_path, 'no project') AS project,
+      COUNT(*)                              AS session_count,
+      COALESCE(SUM(total_cost_usd), 0)     AS total_cost
+    FROM sessions
+    WHERE started_at >= ? AND total_cost_usd > 0
+    GROUP BY project_path
+    ORDER BY total_cost DESC
+    LIMIT 5
+  `),
+    getHourlyDistribution: db.prepare(`
+    SELECT
+      CAST(strftime('%H', datetime(started_at/1000, 'unixepoch', 'localtime')) AS INTEGER) AS hour,
+      COUNT(*) AS session_count
+    FROM sessions
+    WHERE started_at >= ?
+    GROUP BY hour
+    ORDER BY hour ASC
   `),
     getUnattributedCost: db.prepare(`
     WITH period_cost AS (
@@ -582,4 +602,34 @@ exports.dbOps = {
         const since = Date.now() - days * 86400000;
         return stmts.getCostProjection.get(since);
     },
+    getProjectCosts(days = 7) {
+        const since = Date.now() - days * 86400000;
+        return stmts.getProjectCosts.all(since);
+    },
+    getHourlyDistribution(days = 7) {
+        const since = Date.now() - days * 86400000;
+        return stmts.getHourlyDistribution.all(since);
+    },
+    getCacheReadByModel(days) {
+        const since = Date.now() - days * 86400000;
+        return db.prepare(`
+      SELECT COALESCE(dominant_model, 'unknown') as model, SUM(total_cache_read) as cache_read
+      FROM sessions
+      WHERE started_at >= ?
+      GROUP BY dominant_model
+    `).all(since);
+    },
+    getModelBreakdown(days) {
+        const since = Date.now() - days * 86400000;
+        return db.prepare(`
+      SELECT
+        COALESCE(dominant_model, 'unknown') as model,
+        SUM(total_cost_usd) as total_cost,
+        COUNT(*) as session_count
+      FROM sessions
+      WHERE started_at >= ?
+      GROUP BY dominant_model
+      ORDER BY total_cost DESC
+    `).all(since);
+    },
 };

package/dist/doctor.js

@@ -183,6 +183,7 @@ async function runDoctor() {
     const failed = checks.filter(c => !c.ok).length;
     if (failed === 0) {
         console.log('  \x1b[32mAll checks passed — claudestat is healthy!\x1b[0m\n');
+        process.exit(0);
     }
     else {
         console.log(`  \x1b[31m${failed} check(s) failed — see fixes above\x1b[0m\n`);