getprismo 0.1.20 → 0.1.22

package/README.md

@@ -146,6 +146,69 @@ 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.
+
+For the short version:
+
+```bash
+npx getprismo scan --report-card
+```
+
+That prints the simplest decision:
+
+```text
+PrismoDev Report Card
+
+Biggest waste: Generated artifacts / ignore cleanup: High
+Start with: npx getprismo doctor --apply-suggestions --dry-run
+Then: npx getprismo shield -- <noisy command>
+Code index needed: not yet
+Round-trip risk: Low
+```
+
+To benchmark a noisy command:
+
+```bash
+npx getprismo benchmark -- npm test
+npx getprismo benchmark session
+```
+
+`benchmark -- <command>` measures raw command output tokens versus the compact shield summary. `benchmark session` summarizes recent local Claude/Codex sessions, including round-trip context signals like tool calls, repeated commands, repeated source reads, and MCP/tool surface.
+
+---
+
 ## new: context shield
 
 if you know a command may dump huge output, run it through prismo:
@@ -543,6 +606,9 @@ 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 --report-card` | shortest decision-layer summary |
+| `benchmark` | measure command-output reduction or recent session round-trip context |
 | `scan --simple` | plain-english summary |
 | `scan --fix` | create safe fix files |
 | `scan --ci` | fail CI when token-risk gates fail |

package/lib/prismo-dev/benchmark.js

@@ -0,0 +1,122 @@
+module.exports = function createBenchmark(deps) {
+  const {
+    NPX_COMMAND,
+    estimateTokens,
+    formatTokenCount,
+    getUsageSummary,
+    runShield,
+    scanRepo,
+    color,
+  } = deps;
+
+function estimateSummaryTokens(shieldResult) {
+  const lines = shieldResult.output && Array.isArray(shieldResult.output.interestingLines)
+    ? shieldResult.output.interestingLines.join("\n")
+    : "";
+  return estimateTokens([
+    `Command: ${shieldResult.command}`,
+    `Exit: ${shieldResult.exitCode}`,
+    `Duration: ${shieldResult.durationMs}ms`,
+    lines,
+  ].join("\n"));
+}
+
+function runBenchmark(rootDir = process.cwd(), commandArgs = [], options = {}) {
+  if (options.sessionOnly || !commandArgs.length) {
+    const scan = scanRepo(rootDir, { includeUsage: true, usageLimit: options.limit || 5 });
+    const usage = getUsageSummary({ cwd: scan.root, limit: options.limit || 5, tool: "all" });
+    const fit = scan.optimizerFit;
+    return {
+      schemaVersion: 1,
+      mode: "session",
+      scannedPath: scan.root,
+      score: scan.score,
+      riskLevel: scan.risk,
+      sessions: usage.sessions.length,
+      tokens: usage.totals,
+      roundTripContext: fit.roundTripContext,
+      optimizerFit: fit.summary,
+      recommendedStack: fit.recommendedStack,
+      next: [`${NPX_COMMAND} scan --optimizer-fit`, `${NPX_COMMAND} watch --once`, `${NPX_COMMAND} cc timeline`],
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  const shield = runShield(rootDir, commandArgs);
+  const rawTokens = shield.output.estimatedTokens || 0;
+  const summaryTokens = estimateSummaryTokens(shield);
+  const reductionPercent = rawTokens > 0 ? Math.max(0, Math.round(((rawTokens - summaryTokens) / rawTokens) * 100)) : 0;
+  return {
+    schemaVersion: 1,
+    mode: "command",
+    scannedPath: shield.cwd,
+    command: shield.command,
+    exitCode: shield.exitCode,
+    durationMs: shield.durationMs,
+    rawOutput: {
+      bytes: shield.output.totalBytes,
+      estimatedTokens: rawTokens,
+    },
+    shieldedSummary: {
+      estimatedTokens: summaryTokens,
+      interestingLines: shield.output.interestingLines,
+    },
+    estimatedTokenReductionPercent: reductionPercent,
+    stored: shield.stored,
+    next: [
+      "Give the shield summary to the agent first.",
+      `${NPX_COMMAND} shield search "<error text>"`,
+      `${NPX_COMMAND} scan --optimizer-fit`,
+    ],
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function renderBenchmarkTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Benchmark", "bold"));
+  lines.push("");
+  if (result.mode === "session") {
+    lines.push(`Mode: session`);
+    lines.push(`Score: ${result.score}/100 (${result.riskLevel} risk)`);
+    lines.push(`Sessions: ${result.sessions}`);
+    lines.push(`Tokens: ${formatTokenCount(result.tokens.displayTokens || 0)} (${result.tokens.exactTokens ? "exact-local-log" : "estimated/local"})`);
+    lines.push(`Optimizer fit: ${result.optimizerFit}`);
+    lines.push("");
+    lines.push("Round-Trip Context:");
+    lines.push(`- Level: ${result.roundTripContext.level}`);
+    lines.push(`- Tool calls: ${result.roundTripContext.toolCalls}`);
+    lines.push(`- Repeated commands: ${result.roundTripContext.repeatedCommandMentions}`);
+    lines.push(`- Repeated source reads: ${result.roundTripContext.repeatedSourceReads}`);
+    lines.push("");
+    lines.push("Next:");
+    result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+    return lines.join("\n");
+  }
+
+  lines.push(`Mode: command`);
+  lines.push(`Command: ${result.command}`);
+  lines.push(`Exit: ${result.exitCode}`);
+  lines.push(`Duration: ${result.durationMs}ms`);
+  lines.push(`Raw output: ${result.rawOutput.bytes.toLocaleString()} bytes (~${result.rawOutput.estimatedTokens.toLocaleString()} tokens)`);
+  lines.push(`Shield summary: ~${result.shieldedSummary.estimatedTokens.toLocaleString()} tokens`);
+  lines.push(`Estimated reduction: ${result.estimatedTokenReductionPercent}%`);
+  lines.push("");
+  lines.push("Stored Output:");
+  lines.push(`- ${result.stored.stdout}`);
+  lines.push(`- ${result.stored.stderr}`);
+  lines.push("");
+  lines.push("Useful Lines:");
+  result.shieldedSummary.interestingLines.slice(0, 12).forEach((line) => lines.push(`- ${line}`));
+  lines.push("");
+  lines.push("Next:");
+  result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+  return lines.join("\n");
+}
+
+  return {
+    renderBenchmarkTerminal,
+    runBenchmark,
+  };
+};

package/lib/prismo-dev/report.js

@@ -105,6 +105,83 @@ 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(color("Round-Trip Context", "bold", useColor));
+  lines.push(`- Level: ${fit.roundTripContext.level}`);
+  lines.push(`- Tool calls: ${fit.roundTripContext.toolCalls}`);
+  lines.push(`- Repeated command mentions: ${fit.roundTripContext.repeatedCommandMentions}`);
+  lines.push(`- Repeated source reads: ${fit.roundTripContext.repeatedSourceReads}`);
+  lines.push(`- MCP/tool servers: ${fit.roundTripContext.mcpServers}`);
+  lines.push(`- ${fit.roundTripContext.recommendation}`);
+  lines.push("");
+  lines.push("Notes:");
+  fit.caveats.forEach((caveat) => lines.push(`- ${caveat}`));
+  return lines.join("\n");
+}
+
+function renderReportCardTerminal(result, options = {}) {
+  const useColor = options.color !== false;
+  const fit = result.optimizerFit;
+  const top = fit.recommendedStack[0];
+  const second = fit.recommendedStack[1];
+  const lines = [];
+  lines.push("");
+  lines.push(color("PrismoDev Report Card", "bold", useColor));
+  lines.push("");
+  lines.push(`Score: ${result.score}/100 (${result.risk} risk)`);
+  lines.push(`Biggest waste: ${fit.summary}`);
+  lines.push("");
+  if (top) lines.push(`Start with: ${top.command}`);
+  if (second) lines.push(`Then: ${second.command}`);
+  lines.push("");
+  const codeIndex = fit.bottlenecks.find((item) => item.id === "code-indexing");
+  const output = fit.bottlenecks.find((item) => item.id === "output-sandboxing");
+  const ignore = fit.bottlenecks.find((item) => item.id === "ignore-cleanup");
+  lines.push(`Code index needed: ${codeIndex && codeIndex.level === "High" ? "yes" : codeIndex && codeIndex.level === "Medium" ? "maybe" : "not yet"}`);
+  lines.push(`Output sandbox needed: ${output && output.level !== "Low" ? "yes" : "not yet"}`);
+  lines.push(`Ignore cleanup needed: ${ignore && ignore.level !== "Low" ? "yes" : "not urgent"}`);
+  lines.push(`Round-trip risk: ${fit.roundTripContext.level}`);
+  lines.push("");
+  lines.push("Why:");
+  fit.bottlenecks.slice(0, 3).forEach((item) => lines.push(`- ${item.label}: ${item.evidence[0]}`));
+  return lines.join("\n");
+}
+
 function evaluateCi(result, options = {}) {
   const minScore = Number(options.minScore || 80);
   const failures = [];
@@ -392,6 +469,8 @@ function writeReport(result) {
     evaluateCi,
     renderCiReport,
     renderMarkdownReport,
+    renderOptimizerFitTerminal,
+    renderReportCardTerminal,
     renderSimpleScanReport,
     renderTerminalReport,
     writeReport,

package/lib/prismo-dev/scan.js

@@ -390,12 +390,21 @@ function detectOptimizationStack(root, claudeConfig, codexConfig) {
   const projectHeadroom = fs.existsSync(path.join(root, ".headroom")) || fs.existsSync(path.join(os.homedir(), ".headroom"));
   const projectDistill = fs.existsSync(path.join(os.homedir(), ".config", "distill")) || commandExists("distill");
   const projectRtk = fs.existsSync(path.join(root, ".rtk")) || commandExists("rtk");
+  const packageText = readIfText(path.join(root, "package.json"), 512 * 1024) || "";
+  const readmeText = readIfText(path.join(root, "README.md"), 512 * 1024) || "";
+  const projectText = `${packageText}\n${readmeText}`.toLowerCase();
+  const hasText = (pattern) => pattern.test(projectText);
 
   const tools = {
     rtk: { detected: projectRtk, source: projectRtk ? "binary-or-project-config" : "not-detected" },
     headroom: { detected: projectHeadroom || commandExists("headroom"), source: projectHeadroom ? "local-config" : commandExists("headroom") ? "binary" : "not-detected" },
     distill: { detected: projectDistill, source: projectDistill ? "binary-or-user-config" : "not-detected" },
     mana: { detected: projectMana || commandExists("mana"), source: projectMana ? "local-config" : commandExists("mana") ? "binary" : "not-detected" },
+    contextMode: { detected: commandExists("context-mode") || hasText(/context-mode/), source: commandExists("context-mode") ? "binary" : hasText(/context-mode/) ? "project-reference" : "not-detected" },
+    leanCtx: { detected: commandExists("lean-ctx") || hasText(/lean-ctx|lean ctx/), source: commandExists("lean-ctx") ? "binary" : hasText(/lean-ctx|lean ctx/) ? "project-reference" : "not-detected" },
+    repomix: { detected: commandExists("repomix") || hasText(/repomix/), source: commandExists("repomix") ? "binary" : hasText(/repomix/) ? "project-reference" : "not-detected" },
+    codegraph: { detected: commandExists("codegraph") || hasText(/codegraph|codebase-memory-mcp|jcodemunch|sigmap/), source: commandExists("codegraph") ? "binary" : hasText(/codegraph|codebase-memory-mcp|jcodemunch|sigmap/) ? "project-reference" : "not-detected" },
+    tokf: { detected: commandExists("tokf") || hasText(/tokf/), source: commandExists("tokf") ? "binary" : hasText(/tokf/) ? "project-reference" : "not-detected" },
   };
 
   return {
@@ -786,6 +795,253 @@ 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`);
+  const totalToolCalls = realUsage ? realUsage.sessions.reduce((sum, session) => sum + Number(session.toolCalls || 0), 0) : 0;
+  const repeatedCommands = realUsage ? realUsage.sessions.reduce((sum, session) => sum + (session.repeatedCommands || []).reduce((inner, item) => inner + Number(item.count || 0), 0), 0) : 0;
+  if (totalToolCalls >= 500) mcpScore += 30;
+  else if (totalToolCalls >= 100) mcpScore += 15;
+  if (repeatedCommands >= 20) mcpScore += 20;
+  if (totalToolCalls) addEvidence(mcpEvidence, `${totalToolCalls} tool calls in recent local sessions`);
+  if (repeatedCommands) addEvidence(mcpEvidence, `${repeatedCommands} repeated command/tool mentions`);
+  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.",
+      },
+    ],
+    roundTripContext: {
+      level: levelFromScore(Math.max(mcpScore, repeatedSourceReads >= 50 ? 60 : repeatedSourceReads >= 12 ? 35 : 0)),
+      toolCalls: totalToolCalls,
+      repeatedCommandMentions: repeatedCommands,
+      repeatedSourceReads,
+      mcpServers: result.optimizationStack.mcpServerTotal,
+      summary: totalToolCalls || repeatedCommands || repeatedSourceReads || result.optimizationStack.mcpServerTotal
+        ? "Round-trip context risk includes tool calls, repeated commands, repeated source reads, and MCP/tool surface."
+        : "No strong round-trip context signal found in local logs.",
+      recommendation: "Measure workflow-level savings, not only compressed payload size. Fewer tool round trips can beat smaller individual responses.",
+    },
+    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 +1153,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 +1565,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 +1601,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,8 @@ const {
   evaluateCi,
   renderCiReport,
   renderMarkdownReport,
+  renderOptimizerFitTerminal,
+  renderReportCardTerminal,
   renderSimpleScanReport,
   renderTerminalReport,
   writeReport,
@@ -284,6 +286,19 @@ const {
   color,
 });
 
+const {
+  renderBenchmarkTerminal,
+  runBenchmark,
+} = require("./prismo-dev/benchmark")({
+  NPX_COMMAND,
+  estimateTokens,
+  formatTokenCount,
+  getUsageSummary,
+  runShield,
+  scanRepo: (...args) => scanRepo(...args),
+  color,
+});
+
 const {
   renderMcpDoctorTerminal,
   runMcpDoctor,
@@ -299,13 +314,14 @@ Usage:
   prismo init [--json] [--dry-run] [path]
   prismo doctor [--json] [--dry-run] [--apply-ignores-only] [--apply-suggestions] [--no-context-packs] [--limit N] [path]
   prismo firewall [task] [--json] [--dry-run] [path]
+  prismo benchmark [session] [--json] [--limit N] [path] [-- <command ...>]
   prismo shield [--json] [path] -- <command ...>
   prismo shield last [--json] [--limit N] [path]
   prismo shield search <query> [--json] [--limit N] [path]
   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] [--report-card] [--simple] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
   prismo context [scope] [--json] [path]
   prismo cc [list|last N|all] [--json] [--limit N] [path]
@@ -318,6 +334,7 @@ Commands:
   init        Add local PrismoDev helper docs and npm scripts when package.json exists.
   doctor      Diagnose, safely optimize, re-scan, and show before/after payoff.
   firewall    Generate allowed/blocked context policy files for an AI coding task.
+  benchmark   Measure command-output savings or recent session round-trip context.
   shield      Run a noisy command, store full output locally, and return a compact summary.
   mcp         Start a local MCP server exposing Prismo tools over stdio.
   scan        Run PrismoDev for Claude Code, Codex, Cursor, and AI coding workflows.
@@ -334,6 +351,8 @@ 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.
+  --report-card Print a short plain-English optimization report card.
   --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 +392,23 @@ 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] [--report-card] [--simple] [--no-report] [--limit N] [path]
 
 Examples:
   prismo scan
   prismo scan --usage
+  prismo scan --optimizer-fit
+  prismo scan --report-card
   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.
+  --report-card prints the shortest decision-layer summary.
   --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
@@ -603,8 +627,8 @@ async function runCli(argv) {
     printCommandHelp(command);
     return;
   }
-  if (!["dev", "init", "doctor", "firewall", "shield", "mcp", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
-    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo shield, prismo mcp, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
+  if (!["dev", "init", "doctor", "firewall", "benchmark", "shield", "mcp", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
+    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo benchmark, prismo shield, prismo mcp, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
   }
 
   if (command === "demo") {
@@ -687,6 +711,25 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "benchmark") {
+    const json = rest.includes("--json");
+    const limitIndex = rest.indexOf("--limit");
+    const separatorIndex = rest.indexOf("--");
+    const beforeSeparator = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
+    const commandArgs = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
+    const positional = getPositionals(beforeSeparator, new Set(["--limit"]));
+    const sessionOnly = positional[0] === "session" || commandArgs.length === 0;
+    const target = positional[0] === "session" ? positional[1] || process.cwd() : positional[0] || process.cwd();
+    const result = runBenchmark(target, commandArgs, {
+      sessionOnly,
+      limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
+    });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(renderBenchmarkTerminal(result));
+    if (result.mode === "command") process.exitCode = result.exitCode;
+    return;
+  }
+
   if (command === "shield") {
     const json = rest.includes("--json");
     const limitIndex = rest.indexOf("--limit");
@@ -920,12 +963,14 @@ 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 reportCard = rest.includes("--report-card");
   const ciMode = rest.includes("--ci");
-  const includeUsage = rest.includes("--usage");
+  const includeUsage = rest.includes("--usage") || optimizerFit || reportCard;
   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 || reportCard);
   const result = scanRepo(target, {
     includeUsage,
     usageLimit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
@@ -938,7 +983,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 +991,34 @@ async function runCli(argv) {
       payload.ci = evaluateCi(result);
       if (!payload.ci.passed) process.exitCode = 1;
     }
+    if (optimizerFit || reportCard) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        scannedPath: result.root,
+        score: result.score,
+        riskLevel: result.risk,
+        optimizerFit: result.optimizerFit,
+        reportCard: reportCard ? {
+          biggestWaste: result.optimizerFit.summary,
+          startWith: result.optimizerFit.recommendedStack[0]?.command || null,
+          then: result.optimizerFit.recommendedStack[1]?.command || null,
+          roundTripRisk: result.optimizerFit.roundTripContext.level,
+        } : undefined,
+        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 (reportCard) {
+    console.log(renderReportCardTerminal(result));
+  } else if (optimizerFit) {
+    console.log(renderOptimizerFitTerminal(result));
+  } else if (simple) {
     console.log(renderSimpleScanReport(result));
   } else if (ciMode) {
     const ci = evaluateCi(result);
@@ -966,7 +1032,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 && !reportCard) {
     const report = writeReport(result);
     if (report.backupPath) {
       console.log(`\nExisting report backed up to ${path.basename(report.backupPath)}.`);
@@ -987,10 +1053,13 @@ module.exports = {
   renderWatchTerminal,
   renderWatchReport,
   renderTerminalReport,
+  renderOptimizerFitTerminal,
+  renderReportCardTerminal,
   renderDoctorTerminal,
   renderInitTerminal,
   runSetup,
   runOptimize,
+  runBenchmark,
   runDoctor,
   runInit,
   runCli,

package/package.json

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