clawculator 2.6.1 → 2.7.0

package/README.md

@@ -2,11 +2,11 @@
   <img src="logo.png" width="200" />
 </p>
 
-# Clawculator
+# Clawculator 🦞
 
 > **Your friendly penny pincher.**
 
-AI cost forensics for OpenClaw and multi-model setups. One command. Full analysis. 100% offline. Zero AI. Pure deterministic logic.
+AI cost forensics for OpenClaw and multi-model setups. Real-time browser dashboard. Terminal monitoring. Full offline analysis. Zero AI. Pure deterministic logic.
 
 [![npm version](https://badge.fury.io/js/clawculator.svg)](https://badge.fury.io/js/clawculator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -22,22 +22,94 @@ It could be any of these. Clawculator finds all of them — with zero AI, zero g
 
 ---
 
-![Clawculator Report](report-preview.png)
+## Quick start
+
+```bash
+npx clawculator --web     # Browser dashboard at localhost:3457
+```
+
+That's it. Pin the tab. Watch your costs in real-time while you work.
+
+---
 
 ## [▶ Live Demo](https://echoudhry.github.io/clawculator)
 
-See it run against a real config — findings, fix commands, cost exposure, session breakdown.
+See the full dashboard with simulated data — Pac-Claw, hourly charts, heat map, live feed, and more.
+
+![Clawculator Web Dashboard](web-dashboard.png)
 
+---
+
+## 🦞 The Pac-Claw
+
+The dashboard features a Pac-Man-style lobster claw that chomps across the header eating pennies. When an API call comes in, the claw goes into **TURBO mode** — speeds up 3x, glows red, and extra pennies spawn. Because your friendly penny pincher should look the part.
 
 ---
 
-## One command
+## Modes
+
+### `--web` — Browser Dashboard (new in v2.6)
+
+```bash
+npx clawculator --web
+```
+
+A live-updating browser dashboard at `localhost:3457` powered by SSE (Server-Sent Events) — no polling, instant updates when API calls land.
+
+**What you see:**
+- 🔥 **Today's Spend** — big number, real-time, color-coded (green → amber → red)
+- 📊 **Hourly Cost Chart** — bar chart with current hour highlighted
+- 🧠 **Model Mix Donut** — spend breakdown by model (Sonnet vs Opus vs Haiku)
+- ⚡ **Active Sessions** — table sorted by cost with model + message count
+- 🏆 **Costliest Calls** — leaderboard with gold/silver/bronze ranks
+- 📅 **Daily History** — 14-day bar chart with yesterday comparison
+- 🔥 **Spend Heat Map** — 30-day grid (like GitHub contributions, but for spend)
+- 🌊 **Live Feed** — every API call as it happens with slide-in animations
+- 💰 **Burn Rate** — projected monthly cost based on today's velocity
+
+**Persistence:** Data is stored in SQLite at `~/.openclaw/clawculator.db`. History builds over time — the longer you run it, the richer your charts get.
+
+```bash
+npx clawculator --web --port=8080    # Custom port
+```
+
+### `--live` — Terminal Dashboard
+
+```bash
+npx clawculator --live
+```
+
+A real-time terminal dashboard that watches `.jsonl` transcripts. Perfect for a tmux pane alongside your main session:
+
+```bash
+tmux split-window -h "npx clawculator --live"
+```
+
+Press `q` to quit, `r` to force refresh.
+
+### `--report` — HTML Report
+
+```bash
+npx clawculator --report
+```
+
+Generates a full HTML report and opens it in your browser. Includes findings with terminal-style fix commands, session tables, cost summary, and quick wins.
+
+### `--md` — Markdown Report
+
+```bash
+npx clawculator --md
+```
+
+Structured report your OpenClaw agent can read directly. Drop it in your workspace and ask your agent "what's my cost status?"
+
+### Default — Terminal Analysis
 
 ```bash
 npx clawculator
 ```
 
-No install. No account. No config. Auto-detects your OpenClaw setup. Full deterministic report in seconds.
+Color-coded findings by severity with cost estimates and exact fix commands. Today's spend, all-time spend, session breakdown, and actionable quick wins.
 
 ---
 
@@ -45,7 +117,7 @@ No install. No account. No config. Auto-detects your OpenClaw setup. Full determ
 
 Clawculator uses **pure switch/case deterministic logic** — no LLM, no Ollama, no model of any kind. Every finding and recommendation is hardcoded. Results are 100% reproducible and non-negotiable.
 
-Your `openclaw.json`, session logs, and API keys never leave your machine. There is no server. Disconnect your internet and run it — it works.
+Your `openclaw.json`, session logs, and API keys never leave your machine. The `--web` dashboard runs on `localhost` only. There is no external server. Disconnect your internet and run it — it works.
 
 ---
 
@@ -62,36 +134,32 @@ Your `openclaw.json`, session logs, and API keys never leave your machine. There
 | 🤖 Subagents | maxConcurrent too high — burst multiplier | 🟠 High |
 | 📁 Workspace | Too many root .md files inflating context | 🟡 Medium |
 | 🧠 Memory | memoryFlush on primary model | 🟡 Medium |
+| 💸 Transcript gaps | sessions.json vs actual .jsonl cost discrepancy | 🔴 Critical |
 | ⚙️ Primary model | Cost awareness of chosen model tier | ℹ️ Info |
 
 ---
 
-## Usage
-
-```bash
-npx clawculator                          # Terminal analysis (default)
-npx clawculator --md                     # Markdown report (readable by your AI agent)
-npx clawculator --report                 # Visual HTML dashboard
-npx clawculator --json                   # JSON for piping into other tools
-npx clawculator --md --out=~/cost.md     # Custom output path
-npx clawculator --config=/path/to/openclaw.json
-npx clawculator --help
-```
-
----
+## Transcript parsing
 
-## Output formats
+Clawculator reads `.jsonl` transcript files directly from `~/.openclaw/agents/*/sessions/` to calculate **actual API spend** — not what `sessions.json` reports (which can be 1000x+ under-reported).
 
-**Terminal** — color-coded findings by severity with cost estimates and exact fix commands.
+The `--web` and `--live` modes watch these files in real-time, tailing new lines as they're appended. Every API call shows up in your dashboard the moment it happens.
 
-**Markdown (`--md`)** — structured report your OpenClaw agent can read directly. Drop it in your workspace and ask your agent "what's my cost status?" It reads `clawculator-report.md` and answers.
+---
 
-**HTML (`--report`)** — visual dashboard with session breakdown table, cost exposure banner, opens in browser locally.
+## All flags
 
-**JSON (`--json`)** — machine-readable, pipeable:
 ```bash
-npx clawculator --json | jq '.summary'
-npx clawculator --json > cost-report.json
+npx clawculator                          # Terminal analysis (default)
+npx clawculator --web                    # Browser dashboard (localhost:3457)
+npx clawculator --web --port=8080        # Custom port
+npx clawculator --live                   # Real-time terminal dashboard
+npx clawculator --report                 # Visual HTML report
+npx clawculator --md                     # Markdown report
+npx clawculator --json                   # JSON for piping
+npx clawculator --md --out=~/cost.md     # Custom output path
+npx clawculator --config=/path/to/openclaw.json
+npx clawculator --help
 ```
 
 ---
@@ -120,18 +188,15 @@ curl -o ~/clawd/skills/clawculator/SKILL.md \
   https://raw.githubusercontent.com/echoudhry/clawculator/main/skills/clawculator/SKILL.md
 ```
 
-Start a new session to pick it up.
-
 ---
 
-## Why deterministic?
-
-Every recommendation is a hardcoded switch/case — not generated by an AI. This means:
+## Tech stack
 
-- Results are identical every time for the same input
-- No hallucinations, no surprises
-- Works completely offline with no model dependency
-- Fast — analysis runs in under a second
+- **Node.js** — zero dependencies for core analysis
+- **better-sqlite3** — optional, powers `--web` persistence and historical charts
+- **SSE** — Server-Sent Events for real-time browser updates (no WebSocket overhead)
+- **fs.watch** — native file watching for `.jsonl` transcript tailing
+- Pure CSS animations — no React, no build step, no bundler
 
 ---
 

package/bin/clawculator.js

@@ -15,6 +15,7 @@ const flags = {
   md:     args.includes('--md'),
   live:   args.includes('--live'),
   web:    args.includes('--web'),
+  prune:  args.includes('--prune'),
   help:   args.includes('--help') || args.includes('-h'),
   config: args.find(a => a.startsWith('--config='))?.split('=')[1],
   out:    args.find(a => a.startsWith('--out='))?.split('=')[1],
@@ -45,6 +46,8 @@ Options:
   --md              Save markdown report to ./clawculator-report.md
   --json            Output raw JSON
   --out=PATH        Custom output path for --md or --report
+  --port=PORT       Custom port for --web (default: 3457)
+  --prune           Clean up SQLite database (prune events > 14d, snapshots > 1y)
   --config=PATH     Path to openclaw.json (auto-detected by default)
   --help, -h        Show this help
 
@@ -69,6 +72,33 @@ async function main() {
 
   const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
 
+  if (flags.prune) {
+    const dbPath = path.join(openclawHome, 'clawculator.db');
+    if (!fs.existsSync(dbPath)) {
+      console.log('\x1b[90mNo database found at\x1b[0m', dbPath);
+      console.log('\x1b[90mRun --web first to create the database.\x1b[0m');
+      process.exit(0);
+    }
+    let Database;
+    try { Database = require('better-sqlite3'); } catch {
+      console.error('\x1b[31mError:\x1b[0m better-sqlite3 required for --prune. Run: npm install better-sqlite3');
+      process.exit(1);
+    }
+    const db = new Database(dbPath);
+    const eventsBefore = db.prepare('SELECT COUNT(*) as c FROM events').get().c;
+    const snapsBefore = db.prepare('SELECT COUNT(*) as c FROM daily_snapshots').get().c;
+    db.exec(`DELETE FROM events WHERE timestamp < datetime('now', '-14 days')`);
+    db.exec(`DELETE FROM daily_snapshots WHERE date < date('now', '-365 days')`);
+    db.exec('VACUUM');
+    const eventsAfter = db.prepare('SELECT COUNT(*) as c FROM events').get().c;
+    const snapsAfter = db.prepare('SELECT COUNT(*) as c FROM daily_snapshots').get().c;
+    db.close();
+    console.log(`\x1b[32m✓ Pruned database:\x1b[0m ${dbPath}`);
+    console.log(`  Events:    ${eventsBefore} → ${eventsAfter} (removed ${eventsBefore - eventsAfter})`);
+    console.log(`  Snapshots: ${snapsBefore} → ${snapsAfter} (removed ${snapsBefore - snapsAfter})`);
+    process.exit(0);
+  }
+
   if (flags.web) {
     const { startWebDashboard } = require('../src/webDashboard');
     startWebDashboard({ openclawHome, port: flags.port });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawculator",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "AI cost forensics for OpenClaw and multi-model setups. Your friendly penny pincher. 100% offline. Zero AI. Pure deterministic logic.",
   "main": "src/analyzer.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/clawculator.js",
-    "test": "node -e \"const {runAnalysis} = require('./src/analyzer'); runAnalysis({configPath:'~/.openclaw/openclaw.json',sessionsPath:'',logsDir:''}).then(r => console.log('OK:', r.summary))\""
+    "test": "node test/run.js"
   },
   "keywords": [
     "openclaw",
@@ -30,7 +30,8 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {},
   "optionalDependencies": {
-    "better-sqlite3": "^11.10.0"
+    "better-sqlite3": "^11.0.0"
   }
 }

package/skills/clawculator/analyzer.js

@@ -5,6 +5,10 @@ const path = require('path');
 const os   = require('os');
 
 // ── Model pricing (per million tokens, input/output) ─────────────
+// Last updated: 2026-02-28 — Update when Anthropic/OpenAI/Google change pricing
+const PRICING_UPDATED = '2026-02-28';
+const PRICING_STALE_DAYS = 60;
+
 const MODEL_PRICING = {
   'claude-opus-4-6':              { input: 5.00,  output: 25.00, label: 'Claude Opus 4.6' },
   'claude-opus-4-5':              { input: 5.00,  output: 25.00, label: 'Claude Opus 4.5' },
@@ -109,6 +113,10 @@ const FIXES = {
     fix: 'Lower imageMaxDimensionPx to reduce vision token costs — default 1200px is expensive',
     command: 'openclaw config set agents.defaults.imageMaxDimensionPx 800',
   },
+  PRICING_STALE: {
+    fix: 'Update clawculator to get the latest model pricing data',
+    command: 'npm update -g clawculator',
+  },
   MULTI_AGENT_PAID: (agentId) => ({
     fix: `Agent "${agentId}" has its own expensive model config — each agent bills independently`,
     command: `Review agents.list[${agentId}].model config and apply same cost rules as primary agent`,
@@ -503,6 +511,10 @@ function analyzeConfig(configPath) {
 
 /**
  * Parse a .jsonl session transcript file and sum up real usage/cost data.
+ * Version-aware: handles multiple OpenClaw schema formats:
+ *   - v2026.2.x+: entry.message.usage (standard)
+ *   - v2026.1.x:  entry.usage (legacy)
+ *   - Anthropic raw: usage.cache_creation_input_tokens / usage.cache_read_input_tokens
  * Returns { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs }
  */
 function parseTranscript(jsonlPath) {
@@ -512,6 +524,7 @@ function parseTranscript(jsonlPath) {
 
     let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, totalTokens = 0, totalCost = 0;
     let messageCount = 0, model = null, firstTs = null, lastTs = null;
+    let schemaDetected = null; // track which schema we're seeing
 
     for (const line of content.split('\n')) {
       if (!line.trim()) continue;
@@ -527,23 +540,29 @@ function parseTranscript(jsonlPath) {
       }
 
       // Only assistant messages with usage blocks have cost data
-      if (entry.type !== 'message') continue;
+      // Some schemas use entry.type === 'message', others use entry.role === 'assistant'
+      if (entry.type !== 'message' && entry.role !== 'assistant') continue;
 
-      // Usage can be at entry.usage (some formats) or entry.message.usage (standard format)
-      const u = entry.usage || entry.message?.usage;
+      // Usage can be in multiple locations depending on OpenClaw version
+      const u = entry.usage || entry.message?.usage || entry.response?.usage;
       if (!u) continue;
 
+      if (!schemaDetected) {
+        schemaDetected = entry.usage ? 'legacy' : entry.message?.usage ? 'standard' : 'response';
+      }
+
       messageCount++;
 
-      // Model can be at entry.model or entry.message.model
-      const entryModel = entry.model || entry.message?.model;
+      // Model can be at multiple locations
+      const entryModel = entry.model || entry.message?.model || entry.response?.model;
       if (entryModel && !model) model = entryModel;
 
-      input       += u.input       || 0;
-      output      += u.output      || 0;
-      cacheRead   += u.cacheRead   || 0;
-      cacheWrite  += u.cacheWrite  || 0;
-      totalTokens += u.totalTokens || 0;
+      // Token fields: handle both camelCase (OpenClaw) and snake_case (raw Anthropic API)
+      input       += u.input       || u.input_tokens               || 0;
+      output      += u.output      || u.output_tokens              || 0;
+      cacheRead   += u.cacheRead   || u.cache_read_input_tokens    || 0;
+      cacheWrite  += u.cacheWrite  || u.cache_creation_input_tokens || 0;
+      totalTokens += u.totalTokens || ((u.input || u.input_tokens || 0) + (u.output || u.output_tokens || 0)) || 0;
 
       // Prefer API-reported cost (already accounts for cache pricing)
       if (u.cost) {
@@ -557,7 +576,7 @@ function parseTranscript(jsonlPath) {
 
     if (messageCount === 0) return null;
 
-    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs };
+    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs, schemaDetected };
   } catch {
     return null;
   }
@@ -916,6 +935,19 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
 
   const realCost = sessionResult.totalRealCost || 0;
 
+  // Check pricing staleness — only affects cost estimates for config findings
+  // (actual transcript costs use API-reported cost.total, not the pricing table)
+  const pricingAge = Math.floor((Date.now() - new Date(PRICING_UPDATED).getTime()) / 86400000);
+  if (pricingAge > PRICING_STALE_DAYS) {
+    allFindings.push({
+      severity: 'low',
+      source: 'pricing',
+      title: `Model pricing table is ${pricingAge} days old`,
+      detail: `Pricing was last updated ${PRICING_UPDATED}. Actual costs from transcripts are unaffected (they use API-reported totals). Config-based cost estimates (heartbeat bleed, cron projections) may be slightly off. Update: npm update -g clawculator`,
+      ...FIXES.PRICING_STALE,
+    });
+  }
+
   return {
     scannedAt:    new Date().toISOString(),
     configPath,

package/skills/clawculator/webDashboard.js

@@ -18,7 +18,13 @@ function initDB(dbPath) {
   try {
     Database = require('better-sqlite3');
   } catch {
-    console.error('\x1b[31mError:\x1b[0m better-sqlite3 not installed. Run: npm install better-sqlite3');
+    console.error('\n\x1b[31m  ✗ better-sqlite3 is required for --web\x1b[0m\n');
+    console.error('  Install it with:\n');
+    console.error('    \x1b[36mnpm install -g better-sqlite3\x1b[0m');
+    console.error('    \x1b[90m# or, if installed locally:\x1b[0m');
+    console.error('    \x1b[36mcd $(npm root -g)/clawculator && npm install better-sqlite3\x1b[0m\n');
+    console.error('  \x1b[90mThis is a native module that compiles on install.\x1b[0m');
+    console.error('  \x1b[90mRequires: Node.js 18+, Python 3, and a C++ compiler (Xcode CLI tools on macOS).\x1b[0m\n');
     process.exit(1);
   }
 

package/src/analyzer.js

@@ -5,6 +5,10 @@ const path = require('path');
 const os   = require('os');
 
 // ── Model pricing (per million tokens, input/output) ─────────────
+// Last updated: 2026-02-28 — Update when Anthropic/OpenAI/Google change pricing
+const PRICING_UPDATED = '2026-02-28';
+const PRICING_STALE_DAYS = 60;
+
 const MODEL_PRICING = {
   'claude-opus-4-6':              { input: 5.00,  output: 25.00, label: 'Claude Opus 4.6' },
   'claude-opus-4-5':              { input: 5.00,  output: 25.00, label: 'Claude Opus 4.5' },
@@ -109,6 +113,10 @@ const FIXES = {
     fix: 'Lower imageMaxDimensionPx to reduce vision token costs — default 1200px is expensive',
     command: 'openclaw config set agents.defaults.imageMaxDimensionPx 800',
   },
+  PRICING_STALE: {
+    fix: 'Update clawculator to get the latest model pricing data',
+    command: 'npm update -g clawculator',
+  },
   MULTI_AGENT_PAID: (agentId) => ({
     fix: `Agent "${agentId}" has its own expensive model config — each agent bills independently`,
     command: `Review agents.list[${agentId}].model config and apply same cost rules as primary agent`,
@@ -503,6 +511,10 @@ function analyzeConfig(configPath) {
 
 /**
  * Parse a .jsonl session transcript file and sum up real usage/cost data.
+ * Version-aware: handles multiple OpenClaw schema formats:
+ *   - v2026.2.x+: entry.message.usage (standard)
+ *   - v2026.1.x:  entry.usage (legacy)
+ *   - Anthropic raw: usage.cache_creation_input_tokens / usage.cache_read_input_tokens
  * Returns { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs }
  */
 function parseTranscript(jsonlPath) {
@@ -512,6 +524,7 @@ function parseTranscript(jsonlPath) {
 
     let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, totalTokens = 0, totalCost = 0;
     let messageCount = 0, model = null, firstTs = null, lastTs = null;
+    let schemaDetected = null; // track which schema we're seeing
 
     for (const line of content.split('\n')) {
       if (!line.trim()) continue;
@@ -527,23 +540,29 @@ function parseTranscript(jsonlPath) {
       }
 
       // Only assistant messages with usage blocks have cost data
-      if (entry.type !== 'message') continue;
+      // Some schemas use entry.type === 'message', others use entry.role === 'assistant'
+      if (entry.type !== 'message' && entry.role !== 'assistant') continue;
 
-      // Usage can be at entry.usage (some formats) or entry.message.usage (standard format)
-      const u = entry.usage || entry.message?.usage;
+      // Usage can be in multiple locations depending on OpenClaw version
+      const u = entry.usage || entry.message?.usage || entry.response?.usage;
       if (!u) continue;
 
+      if (!schemaDetected) {
+        schemaDetected = entry.usage ? 'legacy' : entry.message?.usage ? 'standard' : 'response';
+      }
+
       messageCount++;
 
-      // Model can be at entry.model or entry.message.model
-      const entryModel = entry.model || entry.message?.model;
+      // Model can be at multiple locations
+      const entryModel = entry.model || entry.message?.model || entry.response?.model;
       if (entryModel && !model) model = entryModel;
 
-      input       += u.input       || 0;
-      output      += u.output      || 0;
-      cacheRead   += u.cacheRead   || 0;
-      cacheWrite  += u.cacheWrite  || 0;
-      totalTokens += u.totalTokens || 0;
+      // Token fields: handle both camelCase (OpenClaw) and snake_case (raw Anthropic API)
+      input       += u.input       || u.input_tokens               || 0;
+      output      += u.output      || u.output_tokens              || 0;
+      cacheRead   += u.cacheRead   || u.cache_read_input_tokens    || 0;
+      cacheWrite  += u.cacheWrite  || u.cache_creation_input_tokens || 0;
+      totalTokens += u.totalTokens || ((u.input || u.input_tokens || 0) + (u.output || u.output_tokens || 0)) || 0;
 
       // Prefer API-reported cost (already accounts for cache pricing)
       if (u.cost) {
@@ -557,7 +576,7 @@ function parseTranscript(jsonlPath) {
 
     if (messageCount === 0) return null;
 
-    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs };
+    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs, schemaDetected };
   } catch {
     return null;
   }
@@ -916,6 +935,19 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
 
   const realCost = sessionResult.totalRealCost || 0;
 
+  // Check pricing staleness — only affects cost estimates for config findings
+  // (actual transcript costs use API-reported cost.total, not the pricing table)
+  const pricingAge = Math.floor((Date.now() - new Date(PRICING_UPDATED).getTime()) / 86400000);
+  if (pricingAge > PRICING_STALE_DAYS) {
+    allFindings.push({
+      severity: 'low',
+      source: 'pricing',
+      title: `Model pricing table is ${pricingAge} days old`,
+      detail: `Pricing was last updated ${PRICING_UPDATED}. Actual costs from transcripts are unaffected (they use API-reported totals). Config-based cost estimates (heartbeat bleed, cron projections) may be slightly off. Update: npm update -g clawculator`,
+      ...FIXES.PRICING_STALE,
+    });
+  }
+
   return {
     scannedAt:    new Date().toISOString(),
     configPath,

package/src/webDashboard.js

@@ -18,7 +18,13 @@ function initDB(dbPath) {
   try {
     Database = require('better-sqlite3');
   } catch {
-    console.error('\x1b[31mError:\x1b[0m better-sqlite3 not installed. Run: npm install better-sqlite3');
+    console.error('\n\x1b[31m  ✗ better-sqlite3 is required for --web\x1b[0m\n');
+    console.error('  Install it with:\n');
+    console.error('    \x1b[36mnpm install -g better-sqlite3\x1b[0m');
+    console.error('    \x1b[90m# or, if installed locally:\x1b[0m');
+    console.error('    \x1b[36mcd $(npm root -g)/clawculator && npm install better-sqlite3\x1b[0m\n');
+    console.error('  \x1b[90mThis is a native module that compiles on install.\x1b[0m');
+    console.error('  \x1b[90mRequires: Node.js 18+, Python 3, and a C++ compiler (Xcode CLI tools on macOS).\x1b[0m\n');
     process.exit(1);
   }