getprismo 0.1.14 → 0.1.15

package/README.md

@@ -182,6 +182,15 @@ npx getprismo shield search "auth expected 200"
 npx getprismo shield search "AUTH_FAILURE" --json
 ```
 
+when `watch` detects tool-output floods or repeated command loops, it now recommends this flow directly:
+
+```text
+Shield Plan
+Run: npx getprismo shield -- <noisy command>
+Then: npx getprismo shield search "<error text>"
+MCP: prismo_shield_run -> prismo_shield_search
+```
+
 this is intentionally not magic interception yet. it is a safe local-first primitive you can tell agents to use for noisy commands.
 
 ---
@@ -800,3 +809,8 @@ npx getprismo mcp --help
 npx getprismo cc --help
 npx getprismo scan --help
 ```
+
+More docs:
+
+- [MCP setup and tools](docs/mcp.md)
+- [Live demo flow](docs/live-demo.md)

package/docs/live-demo.md

@@ -0,0 +1,115 @@
+# PrismoDev Live Demo
+
+Use this flow to show the full product loop on a real repo.
+
+## 1. Before Session: Doctor
+
+```bash
+npx getprismo doctor
+```
+
+Shows:
+
+- before/after repo score
+- missing `.claudeignore` / `.cursorignore`
+- generated artifacts exposed to AI context
+- compact `.prismo/` context packs
+- recommended next starting context
+
+## 2. During Session: Watch
+
+```bash
+npx getprismo watch --once
+```
+
+Shows:
+
+- context pressure
+- session size
+- recent context growth
+- repeated file reads
+- generated artifact leaks
+- possible loops
+- shield recommendation when command output is flooding context
+
+If watch sees noisy output, the important part is:
+
+```text
+Shield Plan
+Run: npx getprismo shield -- <noisy command>
+Then: npx getprismo shield search "<error text>"
+MCP: prismo_shield_run -> prismo_shield_search
+```
+
+## 3. Noisy Commands: Shield
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield search "AUTH_FAILURE"
+npx getprismo shield last
+```
+
+Shows:
+
+- compact command summary
+- useful error lines
+- full output stored locally
+- searchable SQLite FTS index when `sqlite3` is available
+
+Full output stays in:
+
+```text
+.prismo/shield/runs/
+```
+
+## 4. Agent-Native Mode: MCP
+
+```bash
+npx getprismo mcp /path/to/repo
+```
+
+Demo prompt:
+
+```text
+Use Prismo MCP to run the failing test through shield. Search the stored output for the root error. Do not paste the full test log into the chat.
+```
+
+Expected MCP tool flow:
+
+1. `prismo_shield_run`
+2. `prismo_shield_search`
+3. `prismo_context_pack` if the agent needs scoped repo context
+
+## 5. After Session: Timeline
+
+```bash
+npx getprismo cc timeline
+```
+
+Shows:
+
+- generated artifacts that entered context
+- repeated file/path mentions
+- repeated command/tool patterns
+- suggested cleanup action
+
+## Screenshot Commands
+
+For a quick terminal screenshot:
+
+```bash
+npx getprismo doctor
+```
+
+For the proactive story:
+
+```bash
+npx getprismo watch --once
+```
+
+For the MCP/shield story:
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield search "error"
+```

package/docs/mcp.md

@@ -0,0 +1,76 @@
+# PrismoDev MCP
+
+PrismoDev can run as a local MCP server so compatible coding agents can inspect token waste, run noisy commands through shield, search stored output, and request scoped context without pasting huge logs into chat.
+
+## Start
+
+```bash
+npx getprismo mcp /path/to/your/repo
+```
+
+## Generic MCP Config
+
+```json
+{
+  "mcpServers": {
+    "prismodev": {
+      "command": "npx",
+      "args": ["-y", "getprismo", "mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+For local development from this repo:
+
+```json
+{
+  "mcpServers": {
+    "prismodev": {
+      "command": "node",
+      "args": ["/path/to/prismodev/bin/prismo.js", "mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `prismo_scan`: scan repo context/token waste
+- `prismo_doctor_dry_run`: preview doctor payoff without writing files
+- `prismo_watch_snapshot`: inspect live context pressure
+- `prismo_shield_run`: run a noisy command and store full output locally
+- `prismo_shield_search`: search stored shield output
+- `prismo_shield_last`: list recent shielded command runs
+- `prismo_context_pack`: generate or preview scoped context packs
+- `prismo_firewall`: create a scoped context policy for a task
+- `prismo_cc_timeline`: inspect Claude Code session postmortems
+
+## Best Workflow
+
+Ask your agent:
+
+```text
+Run the failing test command through Prismo shield, then search the stored output for the real error. Do not paste the full log into chat.
+```
+
+The agent should call:
+
+1. `prismo_shield_run`
+2. `prismo_shield_search`
+
+This keeps full stdout/stderr in `.prismo/shield/runs/` and only brings the useful failure snippet back into the model context.
+
+## Watch Integration
+
+When `npx getprismo watch` detects a tool-output flood or repeated command loop, it now prints a Shield Plan:
+
+```text
+Shield Plan
+Tool output is flooding context; shield the command so full logs stay local.
+Run: npx getprismo shield -- <noisy command>
+Then: npx getprismo shield search "<error text>"
+MCP: prismo_shield_run -> prismo_shield_search
+```
+
+That is the intended live-session recovery path.

package/lib/prismo-dev/usage-watch.js

@@ -947,7 +947,7 @@ function getTokenBudgetStatus(activeSession, tokenBudget) {
 
 function getRecommendedWatchAction(activeSession, warnings) {
   if (!activeSession) return `${NPX_COMMAND} setup`;
-  if (activeSession.loopSuspicion) return "Pause the loop, summarize the failure once, then start a fresh scoped session.";
+  if (activeSession.estimatedToolTokens >= 150000 || activeSession.loopSuspicion) return `${NPX_COMMAND} shield -- <noisy command>`;
   if ((activeSession.generatedArtifacts || []).length || getActionableRepeatedPaths(activeSession, 1).length) return `${NPX_COMMAND} doctor`;
   if (activeSession.recentContextGrowth >= 250000) return "Start a fresh coding-agent session with a scoped Prismo context prompt.";
   if (warnings.some((warning) => warning.includes("Tool/output"))) return `${NPX_COMMAND} context`;
@@ -956,6 +956,41 @@ function getRecommendedWatchAction(activeSession, warnings) {
   return `${NPX_COMMAND} scan --usage`;
 }
 
+function buildShieldPlan(activeSession, liveAction) {
+  if (!activeSession || !liveAction) return null;
+  const shieldCauses = new Set(["tool-output-flood", "possible-loop"]);
+  const hasRepeatedCommand = Boolean(activeSession.repeatedCommands?.[0]);
+  const highToolOutput = activeSession.estimatedToolTokens >= 150000;
+  if (!shieldCauses.has(liveAction.cause) && !hasRepeatedCommand && !highToolOutput) return null;
+
+  const repeatedCommand = activeSession.repeatedCommands?.[0]?.value || null;
+  const cliCommand = repeatedCommand
+    ? `${NPX_COMMAND} shield -- ${repeatedCommand}`
+    : `${NPX_COMMAND} shield -- <noisy command>`;
+  const searchHint = liveAction.cause === "possible-loop"
+    ? "Search the stored output for the stable error text before rerunning the command."
+    : "Search the stored output for the failure token, filename, or exception instead of loading the full log.";
+
+  return {
+    reason: liveAction.cause === "possible-loop"
+      ? "Repeated command/output loop detected; shield the command and search stored output before reruns."
+      : "Tool output is flooding context; shield the command so full logs stay local.",
+    command: cliCommand,
+    commandTemplate: `${NPX_COMMAND} shield -- <command>`,
+    searchCommand: `${NPX_COMMAND} shield search "<error text>"`,
+    mcp: {
+      runTool: "prismo_shield_run",
+      searchTool: "prismo_shield_search",
+      workflow: "Call prismo_shield_run with the noisy command, then prismo_shield_search for the relevant error text.",
+    },
+    next: [
+      repeatedCommand ? `Run the command through shield: ${cliCommand}` : `Run the noisy command through shield: ${cliCommand}`,
+      searchHint,
+      "Give the agent the compact shield summary first; inspect full stdout/stderr only if needed.",
+    ],
+  };
+}
+
 function buildLiveAction(activeSession, warnings, budgetStatus = null) {
   if (!activeSession) {
     return {
@@ -1103,6 +1138,7 @@ function buildLiveSessionView(summary) {
   const actionableRepeatedPaths = activeSession ? getActionableRepeatedPaths(activeSession, 5) : [];
   const generatedArtifactGroups = activeSession ? summarizeGeneratedArtifacts(activeSession.generatedArtifacts || [], 5) : [];
   const liveAction = buildLiveAction(activeSession, warnings, budgetStatus);
+  const shieldPlan = buildShieldPlan(activeSession, liveAction);
   return {
     activeSession: activeSession
       ? {
@@ -1137,7 +1173,10 @@ function buildLiveSessionView(summary) {
     highestRisk: summary.sessions.reduce((risk, session) => (getRiskRank(session.contextRisk) > getRiskRank(risk) ? session.contextRisk : risk), "Low"),
     budget: budgetStatus,
     warnings,
-    liveAction,
+    liveAction: {
+      ...liveAction,
+      shieldPlan,
+    },
     recommendedAction: getRecommendedWatchAction(activeSession, warnings),
     nextCommands: Array.from(new Set([
       `${NPX_COMMAND} doctor`,
@@ -1316,6 +1355,14 @@ function renderWatchTerminal(summary) {
   lines.push(live.liveAction.summary);
   live.liveAction.now.slice(0, 4).forEach((step, index) => lines.push(`${index + 1}. ${step}`));
   if (live.liveAction.rescueAvailable) lines.push(`Rescue: ${live.liveAction.rescueCommand}`);
+  if (live.liveAction.shieldPlan) {
+    lines.push("");
+    lines.push("Shield Plan");
+    lines.push(live.liveAction.shieldPlan.reason);
+    lines.push(`Run: ${live.liveAction.shieldPlan.command}`);
+    lines.push(`Then: ${live.liveAction.shieldPlan.searchCommand}`);
+    lines.push(`MCP: ${live.liveAction.shieldPlan.mcp.runTool} -> ${live.liveAction.shieldPlan.mcp.searchTool}`);
+  }
   lines.push("");
   if (active.actionableRepeatedPaths?.length || active.generatedArtifactGroups?.length || active.repeatedCommands.length) {
     lines.push("Signals");
@@ -1366,6 +1413,13 @@ function renderRescuePrompt(summary) {
   lines.push("");
   lines.push("Do this now:");
   live.liveAction.now.forEach((step, index) => lines.push(`${index + 1}. ${step}`));
+  if (live.liveAction.shieldPlan) {
+    lines.push("");
+    lines.push("For noisy commands, use Prismo shield instead of loading full output into this chat:");
+    lines.push(`- CLI: ${live.liveAction.shieldPlan.command}`);
+    lines.push(`- Search stored output: ${live.liveAction.shieldPlan.searchCommand}`);
+    lines.push(`- MCP workflow: ${live.liveAction.shieldPlan.mcp.workflow}`);
+  }
   lines.push("");
   lines.push("Before reading or editing anything else, summarize:");
   lines.push("- files changed so far");
@@ -1405,6 +1459,11 @@ function renderLiveGuardrails(summary) {
   lines.push("## Effective Immediately");
   lines.push("");
   live.liveAction.now.forEach((step) => lines.push(`- ${step}`));
+  if (live.liveAction.shieldPlan) {
+    lines.push(`- Run noisy commands through Prismo shield: \`${live.liveAction.shieldPlan.command}\`.`);
+    lines.push(`- Search stored command output with: \`${live.liveAction.shieldPlan.searchCommand}\`.`);
+    lines.push(`- If MCP tools are available, use \`${live.liveAction.shieldPlan.mcp.runTool}\` then \`${live.liveAction.shieldPlan.mcp.searchTool}\`.`);
+  }
   lines.push("- Keep command output short; prefer filtered errors, small ranges, and summaries over full logs.");
   lines.push("- Do not read generated artifacts, lockfiles, caches, build output, coverage, or logs unless explicitly required.");
   lines.push("- Before broad exploration, summarize the current task, changed files, current failure, and next smallest useful file/test.");
@@ -1477,6 +1536,10 @@ function renderContextThrottle(summary) {
     live.liveAction.now.slice(0, 4).forEach((step) => lines.push(`- ${step}`));
     lines.push("- Keep the next tool call narrow enough to summarize in one screen.");
   }
+  if (live.liveAction.shieldPlan) {
+    lines.push(`- Run noisy commands through shield: \`${live.liveAction.shieldPlan.command}\`.`);
+    lines.push(`- Search shield output instead of reloading full logs: \`${live.liveAction.shieldPlan.searchCommand}\`.`);
+  }
   if (active?.actionableRepeatedPaths?.length) {
     lines.push("");
     lines.push("## Blocked Re-Reads");
@@ -1547,6 +1610,7 @@ function buildWatchEvent(summary) {
     toolOutputTokens: active.estimatedToolTokens || 0,
     budget,
     warnings: live.warnings || [],
+    shieldPlan: live.liveAction.shieldPlan || null,
     repeatedFiles: repeated.slice(0, 5),
     artifactGroups: artifacts.slice(0, 5),
     signature: signatureParts.join("::"),
@@ -1621,6 +1685,11 @@ function renderWatchReport(summary) {
   lines.push(`- Cause: ${live.liveAction.cause} (${live.liveAction.confidence} confidence)`);
   lines.push(`- ${live.liveAction.summary}`);
   live.liveAction.now.forEach((step) => lines.push(`- ${step}`));
+  if (live.liveAction.shieldPlan) {
+    lines.push(`- Shield noisy command output: \`${live.liveAction.shieldPlan.command}\``);
+    lines.push(`- Search shielded output: \`${live.liveAction.shieldPlan.searchCommand}\``);
+    lines.push(`- MCP workflow: \`${live.liveAction.shieldPlan.mcp.runTool}\` -> \`${live.liveAction.shieldPlan.mcp.searchTool}\``);
+  }
   if (summary.guardrailsPath) {
     lines.push(`- Guardrails: ${summary.guardrailsPath}`);
     lines.push(`- Rescue prompt: ${summary.rescuePath}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",
@@ -29,7 +29,7 @@
   "files": [
     "bin/",
     "lib/",
-    "docs/prismodev-user-testing.md",
+    "docs/",
     "README.md",
     "LICENSE",
     "NOTICE"