getprismo 0.1.20 → 0.1.21

package/README.md

@@ -146,6 +146,42 @@ watch caught lockfiles entering context, a file being read 286 times, and tool o
 
 ---
 
+## new: optimizer fit
+
+not every token optimizer solves the same bottleneck. before stacking compression proxies, repo packers, code indexes, and MCP tools, run:
+
+```bash
+npx getprismo scan --optimizer-fit
+```
+
+PrismoDev scores your actual repo/session signals and recommends the right path:
+
+```text
+Prismo Optimizer Fit
+
+Primary bottleneck: Generated artifacts / ignore cleanup: HIGH
+
+Bottlenecks
+- Generated artifacts / ignore cleanup: High
+  .claudeignore is missing
+- Oversized command/tool output: Medium
+  237k tool/output tokens found in local sessions
+- Repeated source exploration: Low
+  Repo/source exploration does not look like the main bottleneck
+
+Recommended Stack
+1. Apply safe ignore/context fixes first.
+   Run: npx getprismo doctor --apply-suggestions --dry-run
+   Category: ignore cleanup (.claudeignore, .cursorignore)
+2. Sandbox noisy command output before adding more code-indexing tools.
+   Run: npx getprismo shield -- <noisy command>
+   Category: output sandboxing (Prismo shield, context-mode, RTK, tokf, distill)
+```
+
+This makes PrismoDev the measure-first layer: it tells you whether you need ignore cleanup, output sandboxing, code indexing, repo packing, instruction trimming, session splitting, or MCP/tool hygiene.
+
+---
+
 ## new: context shield
 
 if you know a command may dump huge output, run it through prismo:
@@ -543,6 +579,7 @@ no install needed. npx runs it directly.
 | `cc` | claude code cost breakdown |
 | `cc timeline` | session reconstruction with events |
 | `scan --usage` | full repo scan with local usage data |
+| `scan --optimizer-fit` | recommend which token-optimization path fits your repo/session |
 | `scan --simple` | plain-english summary |
 | `scan --fix` | create safe fix files |
 | `scan --ci` | fail CI when token-risk gates fail |

package/lib/prismo-dev/report.js

@@ -105,6 +105,47 @@ function renderTerminalReport(result, options = {}) {
   return lines.join("\n");
 }
 
+function renderOptimizerFitTerminal(result, options = {}) {
+  const useColor = options.color !== false;
+  const fit = result.optimizerFit;
+  const tone = fit.summary.includes("High") ? "red" : fit.summary.includes("Medium") ? "yellow" : "green";
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Optimizer Fit", "bold", useColor));
+  lines.push("");
+  lines.push(`Primary bottleneck: ${color(fit.summary, tone, useColor)}`);
+  if (result.realUsage && result.realUsage.sessions.length) {
+    lines.push(`Local usage: ${formatTokenCount(result.realUsage.totals.displayTokens)} tokens across ${result.realUsage.sessions.length} session(s)`);
+  } else if (result.realUsage) {
+    lines.push("Local usage: no matching local Claude/Codex sessions found");
+  }
+  lines.push("");
+  lines.push(color("Bottlenecks", "bold", useColor));
+  fit.bottlenecks.forEach((item) => {
+    lines.push(`- ${item.label}: ${item.level}`);
+    item.evidence.slice(0, 2).forEach((evidence) => lines.push(`  ${evidence}`));
+  });
+  lines.push("");
+  lines.push(color("Recommended Stack", "bold", useColor));
+  fit.recommendedStack.forEach((item) => {
+    lines.push(`${item.rank}. ${item.action}`);
+    lines.push(`   Run: ${item.command}`);
+    lines.push(`   Why: ${item.why}`);
+    lines.push(`   Category: ${item.category} (${item.examples.join(", ")})`);
+  });
+  lines.push("");
+  lines.push(color("Tool Fit", "bold", useColor));
+  fit.toolFit.forEach((item) => {
+    lines.push(`- ${item.category}: ${item.fit}`);
+    lines.push(`  Examples: ${item.examples.join(", ")}`);
+    lines.push(`  ${item.reason}`);
+  });
+  lines.push("");
+  lines.push("Notes:");
+  fit.caveats.forEach((caveat) => lines.push(`- ${caveat}`));
+  return lines.join("\n");
+}
+
 function evaluateCi(result, options = {}) {
   const minScore = Number(options.minScore || 80);
   const failures = [];
@@ -392,6 +433,7 @@ function writeReport(result) {
     evaluateCi,
     renderCiReport,
     renderMarkdownReport,
+    renderOptimizerFitTerminal,
     renderSimpleScanReport,
     renderTerminalReport,
     writeReport,

package/lib/prismo-dev/scan.js

@@ -786,6 +786,235 @@ function buildRecommendations({ hasClaudeIgnore, gitignorePatterns, exposedHighR
   return Array.from(new Set(recs));
 }
 
+function levelFromScore(score) {
+  if (score >= 70) return "High";
+  if (score >= 35) return "Medium";
+  return "Low";
+}
+
+function addEvidence(evidence, text) {
+  if (text && !evidence.includes(text)) evidence.push(text);
+}
+
+function countRepeatedSourceReads(realUsage) {
+  if (!realUsage || !Array.isArray(realUsage.sessions)) return 0;
+  const generatedPattern = /(^|\/)(node_modules|dist|build|coverage|\.next|__pycache__|logs|test-results|playwright-report)\//;
+  return realUsage.sessions.reduce((sum, session) => {
+    return sum + (session.repeatedPathMentions || []).filter((item) => {
+      const value = String(item.value || "");
+      if (!value || generatedPattern.test(value)) return false;
+      return /\.(js|jsx|ts|tsx|py|go|rs|java|kt|swift|rb|php|cs|svelte|vue|astro|md|json|toml|yaml|yml)$/i.test(value);
+    }).reduce((inner, item) => inner + Number(item.count || 0), 0);
+  }, 0);
+}
+
+function buildOptimizerFit(result) {
+  const bottlenecks = [];
+  const realUsage = result.realUsage;
+  const toolTokens = realUsage ? Number(realUsage.totals.toolTokens || 0) : 0;
+  const displayTokens = realUsage ? Number(realUsage.totals.displayTokens || 0) : 0;
+  const highRiskSessions = realUsage ? realUsage.sessions.filter((session) => session.contextRisk === "High").length : 0;
+  const repeatedSourceReads = countRepeatedSourceReads(realUsage);
+
+  const ignoreEvidence = [];
+  let ignoreScore = 0;
+  if (!result.hasClaudeIgnore) {
+    ignoreScore += 35;
+    addEvidence(ignoreEvidence, ".claudeignore is missing");
+  }
+  if (!result.hasCursorIgnore) {
+    ignoreScore += 20;
+    addEvidence(ignoreEvidence, ".cursorignore is missing");
+  }
+  if (result.exposedHighRiskDirs.length) {
+    ignoreScore += Math.min(35, result.exposedHighRiskDirs.length * 8);
+    addEvidence(ignoreEvidence, `${result.exposedHighRiskDirs.length} generated/cache directories are exposed`);
+  }
+  if ((result.sessionIgnoreSuggestions || []).length) {
+    ignoreScore += 25;
+    addEvidence(ignoreEvidence, `${result.sessionIgnoreSuggestions.length} ignore rules came from actual session leaks`);
+  }
+  bottlenecks.push({
+    id: "ignore-cleanup",
+    label: "Generated artifacts / ignore cleanup",
+    score: Math.min(100, ignoreScore),
+    level: levelFromScore(ignoreScore),
+    evidence: ignoreEvidence.length ? ignoreEvidence : ["No major ignore-file leak detected"],
+  });
+
+  const outputEvidence = [];
+  let outputScore = result.toolOutputRisk.level === "High" ? 70 : result.toolOutputRisk.level === "Medium" ? 45 : 10;
+  if (toolTokens >= 150000) outputScore += 25;
+  else if (toolTokens >= 50000) outputScore += 15;
+  if (result.toolOutputRisk.exposedNoisyFiles.length) addEvidence(outputEvidence, `${result.toolOutputRisk.exposedNoisyFiles.length} noisy files are exposed`);
+  if (result.toolOutputRisk.exposedNoisyDirectories.length) addEvidence(outputEvidence, `${result.toolOutputRisk.exposedNoisyDirectories.length} noisy directories are exposed`);
+  if (toolTokens) addEvidence(outputEvidence, `${formatTokenCount(toolTokens)} tool/output tokens found in local sessions`);
+  bottlenecks.push({
+    id: "output-sandboxing",
+    label: "Oversized command/tool output",
+    score: Math.min(100, outputScore),
+    level: levelFromScore(outputScore),
+    evidence: outputEvidence.length ? outputEvidence : ["No dominant command-output flood detected"],
+  });
+
+  const indexEvidence = [];
+  let indexScore = 0;
+  if (result.stats.sourceFiles >= 1000) indexScore += 35;
+  else if (result.stats.sourceFiles >= 250) indexScore += 20;
+  if (result.stats.totalFiles >= 5000) indexScore += 25;
+  else if (result.stats.totalFiles >= 1000) indexScore += 15;
+  if (repeatedSourceReads >= 50) indexScore += 35;
+  else if (repeatedSourceReads >= 12) indexScore += 20;
+  if (result.stats.sourceFiles >= 250) addEvidence(indexEvidence, `${result.stats.sourceFiles.toLocaleString()} source files`);
+  if (repeatedSourceReads) addEvidence(indexEvidence, `${repeatedSourceReads} repeated source-file mentions in local sessions`);
+  bottlenecks.push({
+    id: "code-indexing",
+    label: "Repeated source exploration",
+    score: Math.min(100, indexScore),
+    level: levelFromScore(indexScore),
+    evidence: indexEvidence.length ? indexEvidence : ["Repo/source exploration does not look like the main bottleneck"],
+  });
+
+  const instructionEvidence = [];
+  const instructionTokens = result.instructionFiles.reduce((sum, file) => sum + Math.max(0, (file.tokens || 0) - 500), 0);
+  let instructionScore = instructionTokens >= 3000 ? 80 : instructionTokens >= 1000 ? 55 : instructionTokens > 0 ? 30 : 0;
+  result.instructionFiles
+    .filter((file) => file.tokens > 500)
+    .slice(0, 3)
+    .forEach((file) => addEvidence(instructionEvidence, `${file.path} is ~${(file.tokens || 0).toLocaleString()} tokens`));
+  bottlenecks.push({
+    id: "instruction-trim",
+    label: "Persistent instruction bloat",
+    score: Math.min(100, instructionScore),
+    level: levelFromScore(instructionScore),
+    evidence: instructionEvidence.length ? instructionEvidence : ["Persistent instruction files look manageable"],
+  });
+
+  const sessionEvidence = [];
+  let sessionScore = 0;
+  if (displayTokens >= 2000000) sessionScore += 60;
+  else if (displayTokens >= 500000) sessionScore += 35;
+  if (highRiskSessions) sessionScore += Math.min(35, highRiskSessions * 18);
+  if (displayTokens) addEvidence(sessionEvidence, `${formatTokenCount(displayTokens)} tokens across recent local sessions`);
+  if (highRiskSessions) addEvidence(sessionEvidence, `${highRiskSessions} high-context-risk session${highRiskSessions === 1 ? "" : "s"}`);
+  bottlenecks.push({
+    id: "session-splitting",
+    label: "Long-session context buildup",
+    score: Math.min(100, sessionScore),
+    level: levelFromScore(sessionScore),
+    evidence: sessionEvidence.length ? sessionEvidence : ["No matching high-growth local sessions found"],
+  });
+
+  const mcpEvidence = [];
+  let mcpScore = result.optimizationStack.mcpServerTotal >= 10 ? 70 : result.optimizationStack.mcpServerTotal >= 5 ? 45 : 10;
+  if (result.optimizationStack.mcpServerTotal) addEvidence(mcpEvidence, `${result.optimizationStack.mcpServerTotal} MCP/tool servers detected`);
+  bottlenecks.push({
+    id: "tool-surface",
+    label: "Tool/MCP surface overhead",
+    score: Math.min(100, mcpScore),
+    level: levelFromScore(mcpScore),
+    evidence: mcpEvidence.length ? mcpEvidence : ["Tool surface does not look unusually large"],
+  });
+
+  const ranked = bottlenecks.sort((a, b) => b.score - a.score || a.label.localeCompare(b.label));
+  const primary = ranked[0];
+  const actionById = {
+    "ignore-cleanup": {
+      action: "Apply safe ignore/context fixes first.",
+      command: `${NPX_COMMAND} doctor --apply-suggestions --dry-run`,
+      category: "ignore cleanup",
+      examples: ["Prismo doctor", ".claudeignore", ".cursorignore"],
+    },
+    "output-sandboxing": {
+      action: "Sandbox noisy command output before adding more code-indexing tools.",
+      command: `${NPX_COMMAND} shield -- <noisy command>`,
+      category: "output sandboxing",
+      examples: ["Prismo shield", "context-mode", "RTK", "tokf", "distill"],
+    },
+    "code-indexing": {
+      action: "Use a code indexer if repeated source exploration keeps happening.",
+      command: `${NPX_COMMAND} context`,
+      category: "code indexing",
+      examples: ["codegraph", "jcodemunch", "codebase-memory-mcp", "sigmap"],
+    },
+    "instruction-trim": {
+      action: "Trim persistent instructions before adding runtime compression.",
+      command: `${NPX_COMMAND} doctor`,
+      category: "instruction quality",
+      examples: ["CLAUDE.md cleanup", "AGENTS.md cleanup", "caveman-style concise responses"],
+    },
+    "session-splitting": {
+      action: "Split long sessions and recover from context pressure while working.",
+      command: `${NPX_COMMAND} watch --auto`,
+      category: "session control",
+      examples: ["Prismo watch", "Prismo rescue", "fresh task sessions"],
+    },
+    "tool-surface": {
+      action: "Reduce unused MCP/tool surface for the current task.",
+      command: `${NPX_COMMAND} mcp doctor`,
+      category: "tool hygiene",
+      examples: ["disable unused MCP servers", "strict task-scoped tool config"],
+    },
+  };
+
+  const recommendedStack = ranked
+    .filter((item) => item.level !== "Low")
+    .slice(0, 4)
+    .map((item, index) => ({ rank: index + 1, bottleneck: item.id, ...actionById[item.id], why: item.evidence[0] }));
+
+  if (!recommendedStack.length) {
+    recommendedStack.push({
+      rank: 1,
+      bottleneck: "baseline",
+      action: "Keep the stack simple; no major optimizer fit signal was detected.",
+      command: `${NPX_COMMAND} watch --once`,
+      category: "baseline monitoring",
+      examples: ["Prismo watch", "Prismo cc timeline"],
+      why: "Repo scan did not find a dominant token-waste source.",
+    });
+  }
+
+  return {
+    schemaVersion: 1,
+    primaryBottleneck: primary.id,
+    summary: `${primary.label}: ${primary.level}`,
+    bottlenecks: ranked,
+    recommendedStack,
+    toolFit: [
+      {
+        category: "PrismoDev workflow",
+        fit: "High",
+        examples: ["doctor", "watch", "shield", "cc timeline"],
+        reason: "Use this first to diagnose repo/session waste and verify before stacking optimizers.",
+      },
+      {
+        category: "Output compression/sandboxing",
+        fit: ranked.find((item) => item.id === "output-sandboxing").level,
+        examples: ["Prismo shield", "context-mode", "RTK", "tokf", "distill", "headroom"],
+        reason: "Best when shell/test/log output is the dominant waste source.",
+      },
+      {
+        category: "Code indexing / AST graph",
+        fit: ranked.find((item) => item.id === "code-indexing").level,
+        examples: ["codegraph", "jcodemunch", "codebase-memory-mcp", "sigmap"],
+        reason: "Best when the agent repeatedly greps/reads source files to orient itself.",
+      },
+      {
+        category: "Repo packing",
+        fit: result.stats.sourceFiles && result.stats.sourceFiles <= 250 && result.toolOutputRisk.level === "Low" ? "Medium" : "Low",
+        examples: ["repomix", "Prismo context packs"],
+        reason: "Best for one-shot repo handoff, less ideal for long live coding sessions.",
+      },
+    ],
+    caveats: [
+      "Do not stack optimizers blindly; measure one real workflow before and after.",
+      "Payload reduction is not the same as workflow savings; repeated tool calls can erase compression wins.",
+      "Token savings are only useful if the agent still finds the right files and produces accepted changes.",
+    ],
+    nextCommands: recommendedStack.map((item) => item.command),
+  };
+}
+
 function scoreScan(issues, stats, context = {}) {
   const issuePenalty = issues.reduce((sum, issue) => sum + severityWeight(issue.severity), 0);
   const repoPenalty =
@@ -897,6 +1126,7 @@ function toJsonPayload(result) {
     optimizationStack: result.optimizationStack,
     toolOutputRisk: result.toolOutputRisk,
     operationalNoise: result.operationalNoise,
+    optimizerFit: result.optimizerFit,
     sessionIgnoreSuggestions: result.sessionIgnoreSuggestions || [],
     proxyTrackingReadiness: result.proxyTrackingReadiness,
     suggestedClaudeIgnore: result.recommendedClaudeIgnore,
@@ -1308,7 +1538,7 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
   });
   buildRealUsageRecommendations(realUsage).forEach((rec) => recommendations.push(rec));
 
-  return {
+  const scanResult = {
     root,
     score: score.score,
     risk: score.risk,
@@ -1344,6 +1574,8 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
     topTokenLeaks: getTopTokenLeaks(issues),
     generatedAt: new Date().toISOString(),
   };
+  scanResult.optimizerFit = buildOptimizerFit(scanResult);
+  return scanResult;
 }
 
   return {

package/lib/prismo-dev-scan.js

@@ -193,6 +193,7 @@ const {
   evaluateCi,
   renderCiReport,
   renderMarkdownReport,
+  renderOptimizerFitTerminal,
   renderSimpleScanReport,
   renderTerminalReport,
   writeReport,
@@ -305,7 +306,7 @@ Usage:
   prismo mcp [path]
   prismo mcp doctor [--json] [path]
   prismo setup [--json] [--proxy-url URL] [path]
-  prismo scan [--fix] [--ci] [--json] [--usage] [--simple] [--no-report] [path]
+  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--simple] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
   prismo context [scope] [--json] [path]
   prismo cc [list|last N|all] [--json] [--limit N] [path]
@@ -334,6 +335,7 @@ Options:
   --ci        Fail with exit code 1 when token-risk gates fail.
   --json      Output valid JSON only for CI or future dashboard ingestion.
   --usage     Include real local Codex/Claude Code session usage in scan diagnostics.
+  --optimizer-fit Recommend the right optimization path for this repo/session.
   --simple    Print a plain-English scan summary for first-time or non-technical users.
   --no-report Do not write .prismo/prismo-dev-report.md.
   --limit N   Number of recent local sessions to show.
@@ -373,18 +375,21 @@ function printCommandHelp(command) {
     scan: `PrismoDev
 
 Usage:
-  prismo scan [--fix] [--ci] [--json] [--usage] [--simple] [--no-report] [--limit N] [path]
+  prismo scan [--fix] [--ci] [--json] [--usage] [--optimizer-fit] [--simple] [--no-report] [--limit N] [path]
 
 Examples:
   prismo scan
   prismo scan --usage
+  prismo scan --optimizer-fit
   prismo scan --simple
   prismo scan --fix
   prismo scan --ci
   prismo scan --usage --json --no-report
+  prismo scan --optimizer-fit --json
 
 Notes:
   --usage reads local Codex/Claude Code logs when present.
+  --optimizer-fit explains whether ignore cleanup, output sandboxing, code indexing, repo packing, instruction trimming, or session splitting fits this repo best.
   --simple keeps the output short and does not write a report unless combined with --fix.
   --fix creates safe recommendation files and never overwrites CLAUDE.md or AGENTS.md.`,
     optimize: `Prismo Optimize
@@ -920,12 +925,13 @@ async function runCli(argv) {
   const noReport = rest.includes("--no-report");
   const json = rest.includes("--json");
   const simple = rest.includes("--simple");
+  const optimizerFit = rest.includes("--optimizer-fit");
   const ciMode = rest.includes("--ci");
-  const includeUsage = rest.includes("--usage");
+  const includeUsage = rest.includes("--usage") || optimizerFit;
   const limitIndex = rest.indexOf("--limit");
   const usageToolIndex = rest.indexOf("--usage-tool");
   const target = getPositionals(rest, new Set(["--limit", "--usage-tool"]))[0] || process.cwd();
-  const scanDone = printStep(includeUsage ? "Scanning repo and local usage" : "Scanning repo", json || simple);
+  const scanDone = printStep(includeUsage ? "Scanning repo and local usage" : "Scanning repo", json || simple || optimizerFit);
   const result = scanRepo(target, {
     includeUsage,
     usageLimit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
@@ -938,7 +944,7 @@ async function runCli(argv) {
     let report = null;
     if (fix) {
       fixActions = applyFixes(result);
-    } else if (!noReport) {
+    } else if (!noReport && !optimizerFit) {
       report = writeReport(result);
     }
     const payload = toJsonPayload(result);
@@ -946,13 +952,26 @@ async function runCli(argv) {
       payload.ci = evaluateCi(result);
       if (!payload.ci.passed) process.exitCode = 1;
     }
+    if (optimizerFit) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        scannedPath: result.root,
+        score: result.score,
+        riskLevel: result.risk,
+        optimizerFit: result.optimizerFit,
+        generatedAt: result.generatedAt,
+      }, null, 2));
+      return;
+    }
     if (fixActions.length) payload.fixActions = fixActions;
     if (report) payload.reportPath = report.reportPath;
     console.log(JSON.stringify(payload, null, 2));
     return;
   }
 
-  if (simple) {
+  if (optimizerFit) {
+    console.log(renderOptimizerFitTerminal(result));
+  } else if (simple) {
     console.log(renderSimpleScanReport(result));
   } else if (ciMode) {
     const ci = evaluateCi(result);
@@ -966,7 +985,7 @@ async function runCli(argv) {
     const actions = applyFixes(result);
     console.log("\nFix Mode:");
     actions.forEach((action) => console.log(`- ${action}`));
-  } else if (!noReport && !simple) {
+  } else if (!noReport && !simple && !optimizerFit) {
     const report = writeReport(result);
     if (report.backupPath) {
       console.log(`\nExisting report backed up to ${path.basename(report.backupPath)}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",