clawculator 2.0.0 → 2.1.0

package/skills/clawculator/htmlReport.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function severityColor(severity) {
+  return { critical: '#ef4444', high: '#f97316', medium: '#eab308', low: '#38bdf8', info: '#22c55e' }[severity] || '#6b7280';
+}
+
+function severityBg(severity) {
+  return { critical: '#fef2f2', high: '#fff7ed', medium: '#fefce8', low: '#f0f9ff', info: '#f0fdf4' }[severity] || '#f9fafb';
+}
+
+function severityIcon(severity) {
+  return { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵', info: '✅' }[severity] || '⚪';
+}
+
+function relativeAge(ageMs) {
+  if (!ageMs) return 'unknown';
+  const s = Math.floor(ageMs / 1000);
+  if (s < 60)        return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60)        return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24)        return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30)        return `${d}d ago`;
+  return `${Math.floor(d / 30)}mo ago`;
+}
+
+const SOURCE_LABELS = {
+  heartbeat: '💓 Heartbeat', hooks: '🪝 Hooks', whatsapp: '📱 WhatsApp',
+  subagents: '🤖 Subagents', skills: '🔧 Skills', memory: '🧠 Memory',
+  primary_model: '⚙️ Primary Model', sessions: '💬 Sessions',
+  workspace: '📁 Workspace', config: '📄 Config',
+};
+
+async function generateHTMLReport(analysis, outPath) {
+  const { summary, findings, sessions } = analysis;
+  const bleed = summary.estimatedMonthlyBleed;
+
+  const findingCards = findings.map(f => `
+    <div class="finding" style="border-left: 4px solid ${severityColor(f.severity)}; background: ${severityBg(f.severity)}; padding: 16px; margin-bottom: 12px; border-radius: 0 8px 8px 0;">
+      <div style="display:flex; align-items:center; gap:8px; margin-bottom:6px;">
+        <span style="font-size:18px">${severityIcon(f.severity)}</span>
+        <strong style="color:${severityColor(f.severity)}">${f.severity.toUpperCase()}</strong>
+        <span style="color:#6b7280; font-size:14px">${SOURCE_LABELS[f.source] || f.source}</span>
+        ${f.monthlyCost ? `<span style="margin-left:auto; color:${severityColor(f.severity)}; font-weight:bold">$${f.monthlyCost.toFixed(2)}/mo</span>` : ''}
+      </div>
+      <div style="font-weight:600; color:#111; margin-bottom:4px">${f.message}</div>
+      ${f.detail ? `<div style="color:#555; font-size:14px; margin-bottom:6px; white-space:pre-line">${f.detail}</div>` : ''}
+      ${f.fix ? `<div style="color:#16a34a; font-size:14px; margin-top:8px">→ Fix: ${f.fix}</div>` : ''}
+      ${f.command ? `<div style="background:#0f172a; color:#7dd3fc; font-family:monospace; font-size:12px; padding:8px 12px; border-radius:6px; margin-top:8px">${f.command}</div>` : ''}
+    </div>
+  `).join('');
+
+  const sessionRows = (sessions || [])
+    .sort((a, b) => (b.inputTokens + b.outputTokens) - (a.inputTokens + a.outputTokens))
+    .slice(0, 20)
+    .map(s => {
+      const keyDisplay = s.key.length > 18 ? s.key.slice(0, 16) + '…' : s.key;
+      const flag = s.isOrphaned ? ' ⚠️' : '';
+      const age = s.ageMs ? relativeAge(s.ageMs) : 'unknown';
+      const absDate = s.updatedAt ? new Date(s.updatedAt).toLocaleString() : '';
+      const daily = s.dailyCost ? `$${s.dailyCost.toFixed(4)}/day` : '—';
+      return `
+      <tr style="${s.isOrphaned ? 'background:#fff7ed; color:#111;' : ''}">
+        <td style="padding:8px 12px; font-family:monospace; font-size:13px; ${s.isOrphaned ? 'color:#111;' : ''}">${keyDisplay}${flag}</td>
+        <td style="padding:8px 12px; ${s.isOrphaned ? 'color:#111;' : ''}">${s.modelLabel || s.model}</td>
+        <td style="padding:8px 12px; text-align:right; ${s.isOrphaned ? 'color:#111;' : ''}">${(s.inputTokens + s.outputTokens).toLocaleString()}</td>
+        <td style="padding:8px 12px; text-align:right; color:${s.cost > 0.01 ? '#ef4444' : '#22c55e'}">$${s.cost.toFixed(6)}</td>
+        <td style="padding:8px 12px; text-align:right; color:#f59e0b">${daily}</td>
+        <td style="padding:8px 12px; color:#94a3b8; font-size:13px; ${s.isOrphaned ? 'color:#6b7280;' : ''}" title="${absDate}">${age}</td>
+      </tr>
+    `}).join('');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Clawculator Report — ${new Date(analysis.scannedAt).toLocaleString()}</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; }
+    .header { background: linear-gradient(135deg, #0f172a 0%, #1e3a5f 100%); padding: 48px 32px; text-align: center; border-bottom: 1px solid #1e40af; }
+    .logo { font-size: 42px; font-weight: 900; letter-spacing: -2px; background: linear-gradient(90deg, #38bdf8, #818cf8); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+    .tagline { color: #94a3b8; margin-top: 8px; font-size: 16px; }
+    .container { max-width: 1000px; margin: 0 auto; padding: 32px 24px; }
+    .cards { display: table; width: 100%; border-spacing: 16px; border-collapse: separate; margin-bottom: 16px; }
+    .cards-row { display: table-row; }
+    .card { display: table-cell; background: #1e293b; border-radius: 12px; padding: 20px; border: 1px solid #334155; width: 16.6%; }
+    .card-value { font-size: 32px; font-weight: 800; }
+    .card-label { font-size: 13px; color: #94a3b8; margin-top: 4px; }
+    .section { background: #1e293b; border-radius: 12px; padding: 24px; margin-bottom: 24px; border: 1px solid #334155; }
+    .section-title { font-size: 18px; font-weight: 700; margin-bottom: 16px; color: #f1f5f9; }
+    table { width: 100%; border-collapse: collapse; }
+    th { background: #0f172a; padding: 10px 12px; text-align: left; font-size: 13px; color: #cbd5e1; font-weight: 600; }
+    td { color: #e2e8f0; }
+    tr:nth-child(even) { background: #0f172a33; }
+    .footer { text-align: center; color: #475569; font-size: 13px; padding: 32px; }
+    .bleed { background: linear-gradient(135deg, #7f1d1d, #991b1b); border-radius: 12px; padding: 20px 24px; margin-bottom: 24px; border: 1px solid #ef4444; }
+    .bleed-amount { font-size: 36px; font-weight: 900; color: #fca5a5; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="logo">CLAWCULATOR</div>
+    <div class="tagline">Your friendly penny pincher. · 100% offline · Zero AI · Pure deterministic logic</div>
+    <div style="color:#64748b; font-size:13px; margin-top:12px">Report generated: ${new Date(analysis.scannedAt).toLocaleString()}</div>
+  </div>
+
+  <div class="container">
+    ${bleed > 0 ? `
+    <div class="bleed">
+      <div style="color:#fca5a5; font-size:14px; font-weight:600; margin-bottom:4px">⚠️ ESTIMATED MONTHLY COST EXPOSURE</div>
+      <div class="bleed-amount">$${bleed.toFixed(2)}/month</div>
+      <div style="color:#fca5a5; font-size:14px; margin-top:4px">Based on current config — fix the critical issues below to stop the bleed</div>
+    </div>` : `
+    <div style="background:#14532d; border-radius:12px; padding:20px 24px; margin-bottom:24px; border:1px solid #22c55e">
+      <div style="color:#86efac; font-size:18px; font-weight:700">✅ No significant cost bleed detected</div>
+    </div>`}
+
+    <div class="cards"><div class="cards-row">
+      <div class="card">
+        <div class="card-value" style="color:#ef4444">${summary.critical}</div>
+        <div class="card-label">🔴 Critical</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#f97316">${summary.high}</div>
+        <div class="card-label">🟠 High</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#eab308">${summary.medium}</div>
+        <div class="card-label">🟡 Medium</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#38bdf8">${summary.low || 0}</div>
+        <div class="card-label">🔵 Low</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#22c55e">${summary.info}</div>
+        <div class="card-label">✅ OK</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#38bdf8">${summary.sessionsAnalyzed}</div>
+        <div class="card-label">Sessions Analyzed</div>
+      </div>
+      <div class="card">
+        <div class="card-value" style="color:#818cf8">${(summary.totalTokensFound || 0).toLocaleString()}</div>
+        <div class="card-label">Total Tokens Found</div>
+      </div>
+    </div></div>
+
+    <div class="section">
+      <div class="section-title">Findings</div>
+      <div style="color:#0f172a">
+        ${findingCards}
+      </div>
+    </div>
+
+    ${sessionRows ? `
+    <div class="section">
+      <div class="section-title">Session Breakdown</div>
+      <div style="overflow-x:auto">
+        <table>
+          <thead><tr><th>Session</th><th>Model</th><th style="text-align:right">Tokens</th><th style="text-align:right">Total Cost</th><th style="text-align:right">$/day</th><th>Last Active</th></tr></thead>
+          <tbody>${sessionRows}</tbody>
+        </table>
+      </div>
+    </div>` : ''}
+
+  </div>
+  <div class="footer">
+    Clawculator · github.com/echoudhry/clawculator · Your friendly penny pincher.
+  </div>
+</body>
+</html>`;
+
+  const finalPath = outPath || path.join(os.tmpdir(), `clawculator-report-${Date.now()}.html`);
+  fs.writeFileSync(finalPath, html, 'utf8');
+  return finalPath;
+}
+
+module.exports = { generateHTMLReport };

package/skills/clawculator/mdReport.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const SEVERITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', info: '✅' };
+const SOURCE_LABELS = {
+  heartbeat: '💓 Heartbeat', hooks: '🪝 Hooks', whatsapp: '📱 WhatsApp',
+  subagents: '🤖 Subagents', skills: '🔧 Skills', memory: '🧠 Memory',
+  primary_model: '⚙️ Primary Model', sessions: '💬 Sessions',
+  workspace: '📁 Workspace', config: '📄 Config',
+};
+
+function relativeAge(ageMs) {
+  if (!ageMs) return 'unknown';
+  const s = Math.floor(ageMs / 1000);
+  if (s < 60)          return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60)          return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24)          return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30)          return `${d}d ago`;
+  const mo = Math.floor(d / 30);
+  return `${mo}mo ago`;
+}
+
+function absoluteDate(updatedAt) {
+  if (!updatedAt) return '';
+  return new Date(updatedAt).toLocaleString();
+}
+
+function generateMarkdownReport(analysis) {
+  const { summary, findings, sessions, primaryModel, scannedAt } = analysis;
+  const bleed = summary.estimatedMonthlyBleed;
+  const lines = [];
+
+  lines.push('# Clawculator Report');
+  lines.push('> Your friendly penny pincher. · 100% offline · Zero AI · Pure deterministic logic');
+  lines.push('');
+  lines.push(`**Scanned:** ${new Date(scannedAt).toLocaleString()}`);
+  if (primaryModel) lines.push(`**Primary model:** ${primaryModel}`);
+  lines.push('');
+
+  // Cost alert
+  if (bleed > 0) {
+    lines.push(`## ⚠️ Estimated Monthly Cost Exposure: $${bleed.toFixed(2)}/month`);
+    lines.push('');
+  } else {
+    lines.push('## ✅ No significant cost bleed detected');
+    lines.push('');
+  }
+
+  // Summary table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Metric | Value |');
+  lines.push('|--------|-------|');
+  lines.push(`| 🔴 Critical | ${summary.critical} |`);
+  lines.push(`| 🟠 High | ${summary.high} |`);
+  lines.push(`| 🟡 Medium | ${summary.medium} |`);
+  lines.push(`| ✅ OK | ${summary.info} |`);
+  lines.push(`| Sessions analyzed | ${summary.sessionsAnalyzed} |`);
+  lines.push(`| Total tokens found | ${(summary.totalTokensFound || 0).toLocaleString()} |`);
+
+  // Session cost summary
+  if (sessions?.length > 0) {
+    const totalCost = sessions.reduce((sum, s) => sum + s.cost, 0);
+    const dailyRates = sessions.filter(s => s.dailyCost).map(s => s.dailyCost);
+    const totalDailyRate = dailyRates.reduce((sum, r) => sum + r, 0);
+    if (totalCost > 0)      lines.push(`| Total session cost (lifetime) | $${totalCost.toFixed(4)} |`);
+    if (totalDailyRate > 0) lines.push(`| Avg daily burn rate | $${totalDailyRate.toFixed(4)}/day (~$${(totalDailyRate * 30).toFixed(2)}/month) |`);
+  }
+  lines.push('');
+
+  // Findings by severity
+  lines.push('## Findings');
+  lines.push('');
+
+  for (const severity of ['critical', 'high', 'medium', 'info']) {
+    const group = findings.filter(f => f.severity === severity);
+    if (!group.length) continue;
+
+    lines.push(`### ${SEVERITY_ICON[severity]} ${severity.toUpperCase()} (${group.length})`);
+    lines.push('');
+
+    for (const f of group) {
+      lines.push(`#### ${SOURCE_LABELS[f.source] || f.source}`);
+      lines.push('');
+      lines.push(`**${f.message}**`);
+      lines.push('');
+      if (f.detail)          lines.push(`${f.detail}`);
+      if (f.monthlyCost > 0) lines.push(`**Monthly cost:** $${f.monthlyCost.toFixed(2)}/month`);
+      if (f.fix) {
+        lines.push('');
+        lines.push(`**Fix:** ${f.fix}`);
+      }
+      if (f.command) {
+        lines.push('');
+        lines.push('```bash');
+        lines.push(f.command);
+        lines.push('```');
+      }
+      lines.push('');
+    }
+  }
+
+  // Session breakdown
+  if (sessions?.length > 0) {
+    lines.push('## Session Breakdown');
+    lines.push('');
+    lines.push('| Session | Model | Tokens | Total Cost | $/day | Last Active |');
+    lines.push('|---------|-------|--------|-----------|-------|-------------|');
+
+    [...sessions]
+      .sort((a, b) => (b.inputTokens + b.outputTokens) - (a.inputTokens + a.outputTokens))
+      .slice(0, 20)
+      .forEach(s => {
+        const tok        = (s.inputTokens + s.outputTokens).toLocaleString();
+        const flag       = s.isOrphaned ? ' ⚠️' : '';
+        const keyDisplay = s.key.length > 12 ? s.key.slice(0, 8) + '…' : s.key;
+        const age        = s.ageMs ? `${relativeAge(s.ageMs)} (${absoluteDate(s.updatedAt)})` : 'unknown';
+        const daily      = s.dailyCost ? `$${s.dailyCost.toFixed(4)}` : '—';
+        lines.push(`| \`${keyDisplay}${flag}\` | ${s.modelLabel || s.model} | ${tok} | $${s.cost.toFixed(6)} | ${daily} | ${age} |`);
+      });
+
+    lines.push('');
+    lines.push('> ⚠️ = orphaned session · $/day = total cost ÷ session age');
+    lines.push('');
+  }
+
+  // Quick wins
+  const wins = findings.filter(f => f.fix && f.severity !== 'info');
+  if (wins.length > 0) {
+    lines.push('## Quick Wins');
+    lines.push('');
+    wins.slice(0, 5).forEach((f, i) => {
+      lines.push(`${i + 1}. **${f.fix}**`);
+      if (f.command) lines.push(`   \`${f.command}\``);
+    });
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Generated by [Clawculator](https://github.com/echoudhry/clawculator) · Your friendly penny pincher.*');
+
+  return lines.join('\n');
+}
+
+module.exports = { generateMarkdownReport };

package/skills/clawculator/reporter.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const SEVERITY_CONFIG = {
+  critical: { color: '\x1b[31m', icon: '🔴', label: 'CRITICAL' },
+  high:     { color: '\x1b[33m', icon: '🟠', label: 'HIGH' },
+  medium:   { color: '\x1b[33m', icon: '🟡', label: 'MEDIUM' },
+  low:      { color: '\x1b[36m', icon: '🔵', label: 'LOW' },
+  info:     { color: '\x1b[32m', icon: '✅', label: 'OK' },
+};
+
+const SOURCE_LABELS = {
+  heartbeat:     '💓 Heartbeat',
+  hooks:         '🪝 Hooks',
+  whatsapp:      '📱 WhatsApp',
+  subagents:     '🤖 Subagents',
+  skills:        '🔧 Skills',
+  memory:        '🧠 Memory',
+  primary_model: '⚙️  Primary Model',
+  sessions:      '💬 Sessions',
+  workspace:     '📁 Workspace',
+  context:       '📏 Context Pruning',
+  vision:        '🖼️  Vision Tokens',
+  fallbacks:     '🔀 Model Fallbacks',
+  multi_agent:   '👥 Multi-Agent',
+  cron:          '⏰ Cron Jobs',
+  telegram:      '✈️  Telegram',
+  discord:       '💬 Discord',
+  signal:        '📡 Signal',
+  config:        '📄 Config',
+};
+
+function formatCost(cost) {
+  if (!cost) return '';
+  if (cost === 0) return '\x1b[32m$0.00/mo\x1b[0m';
+  if (cost < 1)  return `\x1b[33m$${cost.toFixed(4)}/mo\x1b[0m`;
+  return `\x1b[31m$${cost.toFixed(2)}/mo\x1b[0m`;
+}
+
+function relativeAge(ageMs) {
+  if (!ageMs) return 'unknown';
+  const s = Math.floor(ageMs / 1000);
+  if (s < 60)        return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60)        return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24)        return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30)        return `${d}d ago`;
+  return `${Math.floor(d / 30)}mo ago`;
+}
+
+function generateTerminalReport(analysis) {
+  const { summary, findings, sessions } = analysis;
+  const R = '\x1b[0m';
+  const B = '\x1b[1m';
+  const D = '\x1b[90m';
+  const C = '\x1b[36m';
+  const RED = '\x1b[31m';
+  const GRN = '\x1b[32m';
+
+  console.log(`${C}━━━ Scan Complete ━━━${R}`);
+  console.log(`${D}${new Date(analysis.scannedAt).toLocaleString()}${R}`);
+  if (analysis.primaryModel) console.log(`${D}Primary model: ${analysis.primaryModel}${R}`);
+  console.log();
+
+  const bleed = summary.estimatedMonthlyBleed;
+  if (bleed > 0) {
+    console.log(`${B}${RED}⚠️  Estimated monthly cost exposure: $${bleed.toFixed(2)}/month${R}\n`);
+  }
+
+  for (const severity of ['critical', 'high', 'medium', 'low', 'info']) {
+    const group = findings.filter(f => f.severity === severity);
+    if (!group.length) continue;
+
+    const cfg = SEVERITY_CONFIG[severity];
+    console.log(`${cfg.color}${B}${cfg.icon} ${cfg.label} (${group.length})${R}`);
+    console.log(`${C}${'─'.repeat(60)}${R}`);
+
+    for (const f of group) {
+      console.log(`  ${B}${SOURCE_LABELS[f.source] || f.source}${R}`);
+      console.log(`  ${f.message}`);
+      if (f.detail)          console.log(`  ${D}${f.detail}${R}`);
+      if (f.monthlyCost > 0) console.log(`  ${D}Cost: ${R}${formatCost(f.monthlyCost)}`);
+      if (f.fix)             console.log(`  ${GRN}→ ${f.fix}${R}`);
+      if (f.command)         console.log(`  ${D}  ${f.command}${R}`);
+      console.log();
+    }
+  }
+
+  // Session breakdown
+  if (sessions?.length > 0) {
+    console.log(`${C}━━━ Top Sessions by Token Usage ━━━${R}\n`);
+    const sorted = [...sessions].sort((a, b) => (b.inputTokens + b.outputTokens) - (a.inputTokens + a.outputTokens)).slice(0, 8);
+    console.log(`  ${D}${'Session'.padEnd(16)} ${'Model'.padEnd(20)} ${'Tokens'.padEnd(10)} ${'Total Cost'.padEnd(12)} ${'$/day'.padEnd(10)} Last Active${R}`);
+    console.log(`  ${D}${'─'.repeat(95)}${R}`);
+    for (const s of sorted) {
+      const tok        = (s.inputTokens + s.outputTokens).toLocaleString();
+      const flag       = s.isOrphaned ? ' ⚠️' : '';
+      const keyDisplay = s.key.length > 12 ? s.key.slice(0, 8) + '…' : s.key;
+      const age        = s.ageMs ? `${relativeAge(s.ageMs)} (${new Date(s.updatedAt).toLocaleDateString()})` : 'unknown';
+      const daily      = s.dailyCost ? `$${s.dailyCost.toFixed(4)}` : '—';
+      console.log(`  ${(keyDisplay + flag).padEnd(16)} ${(s.modelLabel || s.model || 'unknown').slice(0, 20).padEnd(20)} ${tok.padEnd(10)} $${s.cost.toFixed(6).padEnd(11)} ${daily.padEnd(10)} ${D}${age}${R}`);
+    }
+
+    // Daily burn rate summary
+    const totalDailyRate = sessions.filter(s => s.dailyCost).reduce((sum, s) => sum + s.dailyCost, 0);
+    if (totalDailyRate > 0) {
+      console.log();
+      console.log(`  ${D}Combined burn rate: ${R}${RED}$${totalDailyRate.toFixed(4)}/day${R}${D} · ~$${(totalDailyRate * 30).toFixed(2)}/month${R}`);
+    }
+    console.log();
+  }
+
+  // Summary
+  console.log(`${C}━━━ Summary ━━━${R}`);
+  console.log(`  🔴 ${RED}${summary.critical}${R} critical  🟠 ${summary.high} high  🟡 ${summary.medium} medium  🔵 ${summary.low||0} low  ✅ ${summary.info} ok`);
+  console.log(`  Sessions analyzed: ${summary.sessionsAnalyzed} · Tokens found: ${(summary.totalTokensFound||0).toLocaleString()}`);
+  if (bleed > 0) {
+    console.log(`  ${RED}${B}Estimated monthly bleed: $${bleed.toFixed(2)}/month${R}`);
+  } else {
+    console.log(`  ${GRN}No significant cost bleed detected ✓${R}`);
+  }
+  console.log();
+
+  // Quick wins
+  const wins = findings.filter(f => f.fix && f.severity !== 'info');
+  if (wins.length > 0) {
+    console.log(`${C}━━━ Quick Wins ━━━${R}`);
+    wins.slice(0, 5).forEach((f, i) => {
+      console.log(`  ${i + 1}. ${GRN}${f.fix}${R}`);
+      if (f.command) console.log(`     ${D}${f.command}${R}`);
+    });
+    console.log();
+  }
+}
+
+module.exports = { generateTerminalReport };
+
+// Source label additions for new sources

package/skills/clawculator/run.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runAnalysis } = require('./analyzer');
+const { generateTerminalReport } = require('./reporter');
+const { generateMarkdownReport } = require('./mdReport');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const flags = {
+  json:   args.includes('--json'),
+  md:     args.includes('--md'),
+  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],
+};
+
+const BANNER = `
+\x1b[36m
+   ██████╗██╗      █████╗ ██╗    ██╗ ██████╗ █████╗ ██╗      ██████╗
+  ██╔════╝██║     ██╔══██╗██║    ██║██╔════╝██╔══██╗██║     ██╔════╝
+  ██║     ██║     ███████║██║ █╗ ██║██║     ███████║██║     ██║     
+  ██║     ██║     ██╔══██║██║███╗██║██║     ██╔══██║██║     ██║     
+  ╚██████╗███████╗██║  ██║╚███╔███╔╝╚██████╗██║  ██║███████╗╚██████╗
+   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝  ╚═════╝╚═╝  ╚═╝╚══════╝ ╚═════╝
+\x1b[0m
+  \x1b[33mYour friendly penny pincher.\x1b[0m
+  \x1b[90m100% offline · Zero AI · Pure deterministic logic · Your data never leaves your machine\x1b[0m
+`;
+
+const HELP = `
+Usage: node run.js [options]
+
+Options:
+  (no flags)        Full terminal analysis
+  --md              Save markdown report to ./clawculator-report.md
+  --json            Output raw JSON to stdout
+  --out=PATH        Custom output path for --md
+  --config=PATH     Path to openclaw.json (auto-detected by default)
+  --help, -h        Show this help
+
+Files read (read-only):
+  ~/.openclaw/openclaw.json
+  ~/.openclaw/agents/main/sessions/sessions.json
+  ~/clawd/ (file count only, no contents)
+  /tmp/openclaw (if present)
+
+Files written (only when --md is used):
+  ./clawculator-report.md (or --out path)
+
+No network requests are made. No data leaves your machine.
+Session keys are truncated in all output to protect sensitive identifiers.
+`;
+
+async function main() {
+  if (flags.help) {
+    console.log(BANNER);
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  console.log(BANNER);
+  console.log('\x1b[90mScanning your setup...\x1b[0m\n');
+
+  const configPath   = flags.config || path.join(os.homedir(), '.openclaw', 'openclaw.json');
+  const sessionsPath = path.join(os.homedir(), '.openclaw', 'agents', 'main', 'sessions', 'sessions.json');
+  const logsDir      = '/tmp/openclaw';
+
+  let analysis;
+  try {
+    analysis = await runAnalysis({ configPath, sessionsPath, logsDir });
+  } catch (err) {
+    console.error('\x1b[31mError:\x1b[0m', err.message);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(analysis, null, 2));
+    process.exit(0);
+  }
+
+  if (flags.md) {
+    const outPath = flags.out || path.join(process.cwd(), 'clawculator-report.md');
+    fs.writeFileSync(outPath, generateMarkdownReport(analysis), 'utf8');
+    console.log(`\x1b[32m✓ Markdown report saved:\x1b[0m ${outPath}`);
+    generateTerminalReport(analysis);
+    process.exit(0);
+  }
+
+  generateTerminalReport(analysis);
+  console.log('\x1b[90m────────────────────────────────────────────────────\x1b[0m');
+  console.log('\x1b[36mClawculator\x1b[0m · github.com/echoudhry/clawculator · Your friendly penny pincher.');
+  console.log('\x1b[90mTip: --md saves a report your AI agent can read directly\x1b[0m');
+  console.log('\x1b[90m────────────────────────────────────────────────────\x1b[0m\n');
+}
+
+main().catch(err => {
+  console.error('\x1b[31mFatal:\x1b[0m', err.message);
+  process.exit(1);
+});