@hasna/terminal 2.2.0 → 2.3.0

package/dist/cli.js

@@ -28,6 +28,7 @@ SUBCOMMANDS:
   collection create|list       Recipe collections
   mcp serve                    Start MCP server for AI agents
   mcp install --claude|--codex Install MCP server
+  discover [--days=N] [--json]  Scan Claude sessions, show token savings potential
   snapshot                     Terminal state as JSON
   --help                       Show this help
   --version                    Show version
@@ -253,17 +254,8 @@ else if (args[0] === "collection") {
 }
 // ── Stats command ────────────────────────────────────────────────────────────
 else if (args[0] === "stats") {
-    const { getEconomyStats, formatTokens } = await import("./economy.js");
-    const s = getEconomyStats();
-    console.log("Token Economy:");
-    console.log(`  Total saved:  ${formatTokens(s.totalTokensSaved)}`);
-    console.log(`  Total used:   ${formatTokens(s.totalTokensUsed)}`);
-    console.log(`  By feature:`);
-    console.log(`    Structured: ${formatTokens(s.savingsByFeature.structured)}`);
-    console.log(`    Compressed: ${formatTokens(s.savingsByFeature.compressed)}`);
-    console.log(`    Diff cache: ${formatTokens(s.savingsByFeature.diff)}`);
-    console.log(`    NL cache:   ${formatTokens(s.savingsByFeature.cache)}`);
-    console.log(`    Search:     ${formatTokens(s.savingsByFeature.search)}`);
+    const { formatEconomicsSummary } = await import("./economy.js");
+    console.log(formatEconomicsSummary());
 }
 // ── Sessions command ─────────────────────────────────────────────────────────
 else if (args[0] === "sessions") {
@@ -407,6 +399,19 @@ else if (args[0] === "explain" && args[1]) {
     const explanation = await explainCommand(command);
     console.log(explanation);
 }
+// ── Discover command ─────────────────────────────────────────────────────────
+else if (args[0] === "discover") {
+    const { discover, formatDiscoverReport } = await import("./discover.js");
+    const days = parseInt(args.find(a => a.startsWith("--days="))?.split("=")[1] ?? "30");
+    const json = args.includes("--json");
+    const report = discover({ maxAgeDays: days });
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(formatDiscoverReport(report));
+    }
+}
 // ── Snapshot command ─────────────────────────────────────────────────────────
 else if (args[0] === "snapshot") {
     const { captureSnapshot } = await import("./snapshots.js");
@@ -430,6 +435,7 @@ else if (args.length > 0) {
     const { processOutput, shouldProcess } = await import("./output-processor.js");
     const { rewriteCommand } = await import("./command-rewriter.js");
     const { shouldBeLazy, toLazy } = await import("./lazy-executor.js");
+    const { saveOutput, formatOutputHint } = await import("./output-store.js");
     const { parseOutput, estimateTokens } = await import("./parsers/index.js");
     const { recordSaving, recordUsage } = await import("./economy.js");
     const { isTestOutput, trackTests, formatWatchResult } = await import("./test-watchlist.js");
@@ -437,6 +443,7 @@ else if (args.length > 0) {
     const { loadConfig } = await import("./history.js");
     const { loadContext, saveContext, formatContext } = await import("./session-context.js");
     const { getLearned, recordMapping } = await import("./usage-cache.js");
+    const { recordCorrection, findSimilarCorrections, recordOutput } = await import("./sessions-db.js");
     const config = loadConfig();
     const perms = config.permissions;
     const sessionCtx = formatContext();
@@ -580,7 +587,15 @@ else if (args.length > 0) {
             if (processed.aiProcessed) {
                 if (processed.tokensSaved > 0)
                     recordSaving("compressed", processed.tokensSaved);
-                console.log(processed.summary);
+                // Save full output for lazy recovery — agents can read the file
+                if (processed.tokensSaved > 50) {
+                    const outputPath = saveOutput(actualCmd, clean);
+                    console.log(processed.summary);
+                    console.log(formatOutputHint(outputPath));
+                }
+                else {
+                    console.log(processed.summary);
+                }
                 if (processed.tokensSaved > 10)
                     console.error(`[open-terminal] ${rawTokens} → ${rawTokens - processed.tokensSaved} tokens (saved ${processed.tokensSaved})`);
                 process.exit(0);
@@ -637,6 +652,8 @@ else if (args.length > 0) {
                     const retryResult = execSync(retryCmd + " #(retry)", { encoding: "utf8", maxBuffer: 10 * 1024 * 1024, cwd: process.cwd() });
                     const retryClean = stripNoise(stripAnsi(retryResult)).cleaned;
                     if (retryClean.length > 5) {
+                        // Record the correction so we learn from it
+                        recordCorrection(prompt, actualCmd, errStderr.slice(0, 500), retryCmd, true);
                         const processed = await processOutput(retryCmd, retryClean, prompt);
                         console.log(processed.aiProcessed ? processed.summary : retryClean);
                         process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/terminal",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Smart terminal wrapper for AI agents and humans — structured output, token compression, MCP server, natural language",
   "type": "module",
   "bin": {

package/src/ai.ts

@@ -6,51 +6,48 @@ import { join } from "path";
 import { discoverProjectHints, discoverSafetyHints, formatHints } from "./context-hints.js";
 
 // ── model routing ─────────────────────────────────────────────────────────────
-// Simple queries → fast model. Complex/ambiguous → smart model.
+// Config-driven model selection. Defaults per provider, user can override in ~/.terminal/config.json
 
 const COMPLEX_SIGNALS = [
   /\b(undo|revert|rollback|previous|last)\b/i,
   /\b(all files?|recursively|bulk|batch)\b/i,
   /\b(pipeline|chain|then|and then|after)\b/i,
   /\b(if|when|unless|only if)\b/i,
-  /\b(go into|go to|navigate|cd into|enter)\b.*\b(and|then)\b/i, // multi-step navigation
-  /\b(inside|within|under)\b/i,  // relative references need context awareness
-  /[|&;]{2}/,           // pipes / &&  in NL (unusual = complex intent)
+  /\b(go into|go to|navigate|cd into|enter)\b.*\b(and|then)\b/i,
+  /\b(inside|within|under)\b/i,
+  /[|&;]{2}/,
 ];
 
-/** Model routing per provider */
+/** Default models per provider — user can override in ~/.terminal/config.json under "models" */
+const MODEL_DEFAULTS: Record<string, { fast: string; smart: string }> = {
+  cerebras:  { fast: "qwen-3-235b-a22b-instruct-2507", smart: "qwen-3-235b-a22b-instruct-2507" },
+  groq:      { fast: "openai/gpt-oss-120b",             smart: "moonshotai/kimi-k2-instruct" },
+  xai:       { fast: "grok-code-fast-1",                smart: "grok-4-fast-non-reasoning" },
+  anthropic: { fast: "claude-haiku-4-5-20251001",       smart: "claude-sonnet-4-6" },
+};
+
+/** Load user model overrides from ~/.terminal/config.json */
+function loadModelOverrides(): Record<string, { fast?: string; smart?: string }> {
+  try {
+    const configPath = join(process.env.HOME ?? "~", ".terminal", "config.json");
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, "utf8"));
+      return config.models ?? {};
+    }
+  } catch {}
+  return {};
+}
+
+/** Model routing per provider — config-driven with defaults */
 function pickModel(nl: string): { fast: string; smart: string; pick: "fast" | "smart" } {
   const isComplex = COMPLEX_SIGNALS.some((r) => r.test(nl)) || nl.split(" ").length > 10;
   const provider = getProvider();
+  const defaults = MODEL_DEFAULTS[provider.name] ?? MODEL_DEFAULTS.cerebras;
+  const overrides = loadModelOverrides()[provider.name] ?? {};
 
-  if (provider.name === "anthropic") {
-    return {
-      fast: "claude-haiku-4-5-20251001",
-      smart: "claude-sonnet-4-6",
-      pick: isComplex ? "smart" : "fast",
-    };
-  }
-
-  if (provider.name === "groq") {
-    return {
-      fast: "openai/gpt-oss-120b",
-      smart: "moonshotai/kimi-k2-instruct",
-      pick: isComplex ? "smart" : "fast",
-    };
-  }
-
-  if (provider.name === "xai") {
-    return {
-      fast: "grok-code-fast-1",
-      smart: "grok-4-fast-non-reasoning",
-      pick: isComplex ? "smart" : "fast",
-    };
-  }
-
-  // Cerebras — qwen for everything (llama3.1-8b too unreliable)
   return {
-    fast: "qwen-3-235b-a22b-instruct-2507",
-    smart: "qwen-3-235b-a22b-instruct-2507",
+    fast: overrides.fast ?? defaults.fast,
+    smart: overrides.smart ?? defaults.smart,
     pick: isComplex ? "smart" : "fast",
   };
 }
@@ -124,6 +121,23 @@ export interface SessionEntry {
   error?: boolean;
 }
 
+// ── correction memory ───────────────────────────────────────────────────────
+
+/** Load past corrections relevant to a prompt — injected as negative examples */
+function loadCorrectionHints(prompt: string): string {
+  try {
+    // Dynamic import to avoid circular deps
+    const { findSimilarCorrections } = require("./sessions-db.js");
+    const corrections = findSimilarCorrections(prompt, 3);
+    if (corrections.length === 0) return "";
+
+    const lines = corrections.map((c: any) =>
+      `AVOID: "${c.failed_command}" (failed: ${c.error_type}). USE: "${c.corrected_command}" instead.`
+    );
+    return `\n\nLEARNED CORRECTIONS (from past failures):\n${lines.join("\n")}`;
+  } catch { return ""; }
+}
+
 // ── project context (powered by context-hints) ──────────────────────────────
 
 function detectProjectContext(): string {
@@ -133,7 +147,7 @@ function detectProjectContext(): string {
 
 // ── system prompt ─────────────────────────────────────────────────────────────
 
-function buildSystemPrompt(perms: Permissions, sessionEntries: SessionEntry[]): string {
+function buildSystemPrompt(perms: Permissions, sessionEntries: SessionEntry[], currentPrompt?: string): string {
   const restrictions: string[] = [];
   if (!perms.destructive)
     restrictions.push("- NEVER generate commands that delete, remove, or overwrite files/data");
@@ -233,7 +247,7 @@ EXISTENCE CHECKS: If the prompt starts with "is there", "does this have", "do we
 
 MONOREPO: If the project context says "MONOREPO", search packages/ or apps/ NOT src/. Use: grep -rn "pattern" packages/ --include="*.ts". For specific packages, use packages/PKGNAME/src/.
 cwd: ${process.cwd()}
-shell: zsh / macOS${projectContext}${safetyBlock}${restrictionBlock}${contextBlock}`;
+shell: zsh / macOS${projectContext}${safetyBlock}${restrictionBlock}${contextBlock}${currentPrompt ? loadCorrectionHints(currentPrompt) : ""}`;
 }
 
 // ── streaming translate ───────────────────────────────────────────────────────
@@ -253,7 +267,7 @@ export async function translateToCommand(
   const provider = getProvider();
   const routing = pickModel(nl);
   const model = routing.pick === "smart" ? routing.smart : routing.fast;
-  const system = buildSystemPrompt(perms, sessionEntries);
+  const system = buildSystemPrompt(perms, sessionEntries, nl);
 
   let text: string;
 
@@ -332,7 +346,7 @@ export async function fixCommand(
     {
       model: routing.smart, // always use smart model for fixes
       maxTokens: 256,
-      system: buildSystemPrompt(perms, sessionEntries),
+      system: buildSystemPrompt(perms, sessionEntries, originalNl),
     }
   );
   if (text.startsWith("BLOCKED:")) throw new Error(text);

package/src/cli.tsx

@@ -31,6 +31,7 @@ SUBCOMMANDS:
   collection create|list       Recipe collections
   mcp serve                    Start MCP server for AI agents
   mcp install --claude|--codex Install MCP server
+  discover [--days=N] [--json]  Scan Claude sessions, show token savings potential
   snapshot                     Terminal state as JSON
   --help                       Show this help
   --version                    Show version
@@ -243,17 +244,8 @@ else if (args[0] === "collection") {
 // ── Stats command ────────────────────────────────────────────────────────────
 
 else if (args[0] === "stats") {
-  const { getEconomyStats, formatTokens } = await import("./economy.js");
-  const s = getEconomyStats();
-  console.log("Token Economy:");
-  console.log(`  Total saved:  ${formatTokens(s.totalTokensSaved)}`);
-  console.log(`  Total used:   ${formatTokens(s.totalTokensUsed)}`);
-  console.log(`  By feature:`);
-  console.log(`    Structured: ${formatTokens(s.savingsByFeature.structured)}`);
-  console.log(`    Compressed: ${formatTokens(s.savingsByFeature.compressed)}`);
-  console.log(`    Diff cache: ${formatTokens(s.savingsByFeature.diff)}`);
-  console.log(`    NL cache:   ${formatTokens(s.savingsByFeature.cache)}`);
-  console.log(`    Search:     ${formatTokens(s.savingsByFeature.search)}`);
+  const { formatEconomicsSummary } = await import("./economy.js");
+  console.log(formatEconomicsSummary());
 }
 
 // ── Sessions command ─────────────────────────────────────────────────────────
@@ -381,6 +373,20 @@ else if (args[0] === "explain" && args[1]) {
   console.log(explanation);
 }
 
+// ── Discover command ─────────────────────────────────────────────────────────
+
+else if (args[0] === "discover") {
+  const { discover, formatDiscoverReport } = await import("./discover.js");
+  const days = parseInt(args.find(a => a.startsWith("--days="))?.split("=")[1] ?? "30");
+  const json = args.includes("--json");
+  const report = discover({ maxAgeDays: days });
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatDiscoverReport(report));
+  }
+}
+
 // ── Snapshot command ─────────────────────────────────────────────────────────
 
 else if (args[0] === "snapshot") {
@@ -411,6 +417,7 @@ else if (args.length > 0) {
   const { processOutput, shouldProcess } = await import("./output-processor.js");
   const { rewriteCommand } = await import("./command-rewriter.js");
   const { shouldBeLazy, toLazy } = await import("./lazy-executor.js");
+  const { saveOutput, formatOutputHint } = await import("./output-store.js");
   const { parseOutput, estimateTokens } = await import("./parsers/index.js");
   const { recordSaving, recordUsage } = await import("./economy.js");
   const { isTestOutput, trackTests, formatWatchResult } = await import("./test-watchlist.js");
@@ -418,6 +425,7 @@ else if (args.length > 0) {
   const { loadConfig } = await import("./history.js");
   const { loadContext, saveContext, formatContext } = await import("./session-context.js");
   const { getLearned, recordMapping } = await import("./usage-cache.js");
+  const { recordCorrection, findSimilarCorrections, recordOutput } = await import("./sessions-db.js");
 
   const config = loadConfig();
   const perms = config.permissions;
@@ -566,7 +574,14 @@ else if (args.length > 0) {
       const processed = await processOutput(actualCmd, clean, prompt);
       if (processed.aiProcessed) {
         if (processed.tokensSaved > 0) recordSaving("compressed", processed.tokensSaved);
-        console.log(processed.summary);
+        // Save full output for lazy recovery — agents can read the file
+        if (processed.tokensSaved > 50) {
+          const outputPath = saveOutput(actualCmd, clean);
+          console.log(processed.summary);
+          console.log(formatOutputHint(outputPath));
+        } else {
+          console.log(processed.summary);
+        }
         if (processed.tokensSaved > 10) console.error(`[open-terminal] ${rawTokens} → ${rawTokens - processed.tokensSaved} tokens (saved ${processed.tokensSaved})`);
         process.exit(0);
       }
@@ -625,6 +640,8 @@ else if (args.length > 0) {
           const retryResult = execSync(retryCmd + " #(retry)", { encoding: "utf8", maxBuffer: 10 * 1024 * 1024, cwd: process.cwd() });
           const retryClean = stripNoise(stripAnsi(retryResult)).cleaned;
           if (retryClean.length > 5) {
+            // Record the correction so we learn from it
+            recordCorrection(prompt, actualCmd, errStderr.slice(0, 500), retryCmd, true);
             const processed = await processOutput(retryCmd, retryClean, prompt);
             console.log(processed.aiProcessed ? processed.summary : retryClean);
             process.exit(0);

package/src/context-hints.ts

@@ -160,9 +160,98 @@ export function discoverOutputHints(output: string, command: string): string[] {
   // Sensitive data (only env var assignments, not code containing the word KEY/TOKEN)
   if (output.match(/^[A-Z_]+(KEY|TOKEN|SECRET|PASSWORD)\s*=\s*\S+/m)) hints.push("Output may contain sensitive data — redact credentials");
 
+  // Error block extraction — state machine that captures multi-line errors
+  if (!isGrepOutput) {
+    const errorBlocks = extractErrorBlocks(output);
+    if (errorBlocks.length > 0) {
+      const summary = errorBlocks.slice(0, 3).map(b => b.trim().split("\n").slice(0, 5).join("\n")).join("\n---\n");
+      hints.push(`ERROR BLOCKS FOUND (${errorBlocks.length}):\n${summary}`);
+    }
+  }
+
   return hints;
 }
 
+/** Extract multi-line error blocks using a state machine */
+function extractErrorBlocks(output: string): string[] {
+  const lines = output.split("\n");
+  const blocks: string[] = [];
+  let currentBlock: string[] = [];
+  let inErrorBlock = false;
+  let blankCount = 0;
+
+  // Patterns that START an error block
+  const errorStarters = [
+    /^error/i, /^Error:/i, /^ERROR/,
+    /^Traceback/i, /^panic:/i, /^fatal:/i,
+    /^FAIL/i, /^✗/, /^✘/,
+    /error\s*TS\d+/i, /error\[E\d+\]/,
+    /^SyntaxError/i, /^TypeError/i, /^ReferenceError/i,
+    /^Unhandled/i, /^Exception/i,
+    /ENOENT|EACCES|EADDRINUSE|ECONNREFUSED/,
+  ];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      blankCount++;
+      if (inErrorBlock) {
+        currentBlock.push(line);
+        // 2+ blank lines = end of error block
+        if (blankCount >= 2) {
+          blocks.push(currentBlock.join("\n").trim());
+          currentBlock = [];
+          inErrorBlock = false;
+        }
+      }
+      continue;
+    }
+    blankCount = 0;
+
+    // Check if this line starts a new error block
+    if (!inErrorBlock && errorStarters.some(p => p.test(trimmed))) {
+      inErrorBlock = true;
+      currentBlock = [line];
+      continue;
+    }
+
+    if (inErrorBlock) {
+      // Continuation: indented lines, "at ..." stack frames, "--->" pointers, "File ..." python traces
+      const isContinuation =
+        /^\s+/.test(line) ||
+        /^\s*at\s/.test(trimmed) ||
+        /^\s*-+>/.test(trimmed) ||
+        /^\s*\|/.test(trimmed) ||
+        /^\s*File "/.test(trimmed) ||
+        /^\s*\d+\s*\|/.test(trimmed) || // rust/compiler line numbers
+        /^Caused by:/i.test(trimmed);
+
+      if (isContinuation) {
+        currentBlock.push(line);
+      } else {
+        // Non-continuation, non-blank = end of error block
+        blocks.push(currentBlock.join("\n").trim());
+        currentBlock = [];
+        inErrorBlock = false;
+
+        // Check if THIS line starts a new error block
+        if (errorStarters.some(p => p.test(trimmed))) {
+          inErrorBlock = true;
+          currentBlock = [line];
+        }
+      }
+    }
+  }
+
+  // Flush remaining block
+  if (currentBlock.length > 0) {
+    blocks.push(currentBlock.join("\n").trim());
+  }
+
+  return blocks;
+}
+
 /** Discover safety hints about a command */
 export function discoverSafetyHints(command: string): string[] {
   const hints: string[] = [];

package/src/discover.ts

@@ -0,0 +1,238 @@
+// Discover — scan Claude Code session history to find token savings opportunities
+// Reads ~/.claude/projects/*/sessions/*.jsonl, extracts Bash commands + output sizes,
+// estimates how much terminal would have saved.
+
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { estimateTokens } from "./parsers/index.js";
+
+export interface DiscoveredCommand {
+  command: string;
+  outputTokens: number;
+  outputChars: number;
+  sessionFile: string;
+  timestamp?: string;
+}
+
+export interface DiscoverReport {
+  totalSessions: number;
+  totalCommands: number;
+  totalOutputTokens: number;
+  estimatedSavings: number; // tokens saved at 70% compression
+  estimatedSavingsUsd: number; // at Opus rates ($5/M input)
+  topCommands: { command: string; count: number; totalTokens: number; avgTokens: number }[];
+  commandsByCategory: Record<string, { count: number; tokens: number }>;
+}
+
+/** Find all Claude session JSONL files */
+function findSessionFiles(claudeDir: string, maxAge?: number): string[] {
+  const files: string[] = [];
+  const projectsDir = join(claudeDir, "projects");
+  if (!existsSync(projectsDir)) return files;
+
+  const now = Date.now();
+  const cutoff = maxAge ? now - maxAge : 0;
+
+  try {
+    for (const project of readdirSync(projectsDir)) {
+      const projectPath = join(projectsDir, project);
+      // Look for session JSONL files (not subagents)
+      try {
+        for (const entry of readdirSync(projectPath)) {
+          if (entry.endsWith(".jsonl")) {
+            const filePath = join(projectPath, entry);
+            try {
+              const stat = statSync(filePath);
+              if (stat.mtimeMs > cutoff) files.push(filePath);
+            } catch {}
+          }
+        }
+      } catch {}
+    }
+  } catch {}
+
+  return files;
+}
+
+/** Extract Bash commands and their output sizes from a session file */
+function extractCommands(sessionFile: string): DiscoveredCommand[] {
+  const commands: DiscoveredCommand[] = [];
+
+  try {
+    const content = readFileSync(sessionFile, "utf8");
+    const lines = content.split("\n").filter(l => l.trim());
+
+    // Track tool_use IDs to match with tool_results
+    const pendingToolUses: Map<string, string> = new Map(); // id -> command
+
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        const msg = obj.message;
+        if (!msg?.content || !Array.isArray(msg.content)) continue;
+
+        for (const block of msg.content) {
+          // Capture Bash tool_use commands
+          if (block.type === "tool_use" && block.name === "Bash" && block.input?.command) {
+            pendingToolUses.set(block.id, block.input.command);
+          }
+
+          // Capture tool_result outputs and match to commands
+          if (block.type === "tool_result" && block.tool_use_id) {
+            const command = pendingToolUses.get(block.tool_use_id);
+            if (command) {
+              let outputText = "";
+              if (typeof block.content === "string") {
+                outputText = block.content;
+              } else if (Array.isArray(block.content)) {
+                outputText = block.content
+                  .filter((c: any) => c.type === "text")
+                  .map((c: any) => c.text)
+                  .join("\n");
+              }
+
+              if (outputText.length > 0) {
+                commands.push({
+                  command,
+                  outputTokens: estimateTokens(outputText),
+                  outputChars: outputText.length,
+                  sessionFile,
+                });
+              }
+              pendingToolUses.delete(block.tool_use_id);
+            }
+          }
+        }
+      } catch {} // skip malformed lines
+    }
+  } catch {} // skip unreadable files
+
+  return commands;
+}
+
+/** Categorize a command into a bucket */
+function categorizeCommand(cmd: string): string {
+  const trimmed = cmd.trim();
+  if (/^git\b/.test(trimmed)) return "git";
+  if (/\b(bun|npm|yarn|pnpm)\s+(test|run\s+test)/.test(trimmed)) return "test";
+  if (/\b(bun|npm|yarn|pnpm)\s+run\s+(build|typecheck|lint)/.test(trimmed)) return "build";
+  if (/^(grep|rg)\b/.test(trimmed)) return "grep";
+  if (/^find\b/.test(trimmed)) return "find";
+  if (/^(cat|head|tail|less)\b/.test(trimmed)) return "read";
+  if (/^(ls|tree|du|wc)\b/.test(trimmed)) return "list";
+  if (/^(curl|wget|fetch)\b/.test(trimmed)) return "network";
+  if (/^(docker|kubectl|helm)\b/.test(trimmed)) return "infra";
+  if (/^(python|pip|pytest)\b/.test(trimmed)) return "python";
+  if (/^(cargo|rustc)\b/.test(trimmed)) return "rust";
+  if (/^(go\s|golangci)\b/.test(trimmed)) return "go";
+  return "other";
+}
+
+/** Normalize command for grouping (strip variable parts like paths, hashes) */
+function normalizeCommand(cmd: string): string {
+  return cmd
+    .replace(/[0-9a-f]{7,40}/g, "{hash}") // git hashes
+    .replace(/\/[\w./-]+\.(ts|tsx|js|json|py|rs|go)\b/g, "{file}") // file paths
+    .replace(/\d{4}-\d{2}-\d{2}/g, "{date}") // dates
+    .replace(/:\d+/g, ":{line}") // line numbers
+    .trim();
+}
+
+/** Run discover across all Claude sessions */
+export function discover(options: { maxAgeDays?: number; minTokens?: number } = {}): DiscoverReport {
+  const claudeDir = join(process.env.HOME ?? "~", ".claude");
+  const maxAge = (options.maxAgeDays ?? 30) * 24 * 60 * 60 * 1000;
+  const minTokens = options.minTokens ?? 50;
+
+  const sessionFiles = findSessionFiles(claudeDir, maxAge);
+  const allCommands: DiscoveredCommand[] = [];
+
+  for (const file of sessionFiles) {
+    allCommands.push(...extractCommands(file));
+  }
+
+  // Filter to commands with meaningful output
+  const significant = allCommands.filter(c => c.outputTokens >= minTokens);
+
+  // Group by normalized command
+  const groups = new Map<string, { count: number; totalTokens: number; example: string }>();
+  for (const cmd of significant) {
+    const key = normalizeCommand(cmd.command);
+    const existing = groups.get(key) ?? { count: 0, totalTokens: 0, example: cmd.command };
+    existing.count++;
+    existing.totalTokens += cmd.outputTokens;
+    groups.set(key, existing);
+  }
+
+  // Top commands by total tokens
+  const topCommands = [...groups.entries()]
+    .map(([cmd, data]) => ({
+      command: data.example,
+      count: data.count,
+      totalTokens: data.totalTokens,
+      avgTokens: Math.round(data.totalTokens / data.count),
+    }))
+    .sort((a, b) => b.totalTokens - a.totalTokens)
+    .slice(0, 20);
+
+  // Category breakdown
+  const commandsByCategory: Record<string, { count: number; tokens: number }> = {};
+  for (const cmd of significant) {
+    const cat = categorizeCommand(cmd.command);
+    if (!commandsByCategory[cat]) commandsByCategory[cat] = { count: 0, tokens: 0 };
+    commandsByCategory[cat].count++;
+    commandsByCategory[cat].tokens += cmd.outputTokens;
+  }
+
+  const totalOutputTokens = significant.reduce((sum, c) => sum + c.outputTokens, 0);
+  // Conservative 70% compression estimate (RTK claims 60-90%)
+  const estimatedSavings = Math.round(totalOutputTokens * 0.7);
+  // Each saved input token is repeated across ~5 turns on average before compaction
+  const multipliedSavings = estimatedSavings * 5;
+  // At Opus rates ($5/M input tokens)
+  const estimatedSavingsUsd = (multipliedSavings * 5) / 1_000_000;
+
+  return {
+    totalSessions: sessionFiles.length,
+    totalCommands: significant.length,
+    totalOutputTokens,
+    estimatedSavings,
+    estimatedSavingsUsd,
+    topCommands,
+    commandsByCategory,
+  };
+}
+
+/** Format discover report for CLI display */
+export function formatDiscoverReport(report: DiscoverReport): string {
+  const lines: string[] = [];
+
+  lines.push(`📊 Terminal Discover — Token Savings Analysis`);
+  lines.push(`   Scanned ${report.totalSessions} sessions, ${report.totalCommands} commands with >50 token output\n`);
+
+  lines.push(`💰 Estimated savings with open-terminal:`);
+  lines.push(`   Output tokens: ${report.totalOutputTokens.toLocaleString()}`);
+  lines.push(`   Compressible:  ${report.estimatedSavings.toLocaleString()} tokens (70% avg)`);
+  lines.push(`   Repeated ~5x before compaction = ${(report.estimatedSavings * 5).toLocaleString()} billable tokens`);
+  lines.push(`   At Opus rates: $${report.estimatedSavingsUsd.toFixed(2)} saved\n`);
+
+  if (report.topCommands.length > 0) {
+    lines.push(`🔝 Top commands by token cost:`);
+    for (const cmd of report.topCommands.slice(0, 15)) {
+      const avg = cmd.avgTokens.toLocaleString().padStart(6);
+      const total = cmd.totalTokens.toLocaleString().padStart(8);
+      lines.push(`   ${String(cmd.count).padStart(4)}× ${avg} avg → ${total} total  ${cmd.command.slice(0, 60)}`);
+    }
+    lines.push("");
+  }
+
+  if (Object.keys(report.commandsByCategory).length > 0) {
+    lines.push(`📁 By category:`);
+    const sorted = Object.entries(report.commandsByCategory).sort((a, b) => b[1].tokens - a[1].tokens);
+    for (const [cat, data] of sorted) {
+      lines.push(`   ${cat.padEnd(10)} ${String(data.count).padStart(5)} cmds  ${data.tokens.toLocaleString().padStart(10)} tokens`);
+    }
+  }
+
+  return lines.join("\n");
+}