getprismo 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,11 @@
-# Prismo Dev Tools
+# PrismoDev
 
 Prismo helps developers find and reduce token waste in AI coding workflows. It runs locally, supports Codex and Claude Code, and does not require API keys.
 
 ```bash
-npx getprismo dev
+npx getprismo scan --usage
+npx getprismo setup
+npx getprismo watch
 ```
 
 ## What It Does
@@ -17,20 +19,29 @@ npx getprismo dev
 ## Quick Start
 
 ```bash
-npx getprismo demo
-npx getprismo dev
+npx getprismo scan --usage
+npx getprismo setup
+npx getprismo watch --once
 ```
 
-The guided `dev` command:
+Use this flow to see value immediately:
+
+1. `scan --usage` finds repo/context risks and reads local Codex/Claude Code usage logs when available.
+2. `setup` shows which tracking modes are possible, including Prismo proxy readiness.
+3. `watch --once` shows the current live local session view with warnings and next action.
 
-1. Scans the repo and local coding-agent usage.
-2. Generates optimized context files in `.prismo/`.
-3. Prints a paste-ready prompt for your next AI coding session.
+For a guided scan + context generation flow, run:
+
+```bash
+npx getprismo dev
+```
 
 ## Common Commands
 
 ```bash
 npx getprismo scan --usage
+npx getprismo setup
+npx getprismo watch
 npx getprismo scan --fix
 npx getprismo optimize
 npx getprismo context frontend
@@ -41,7 +52,7 @@ npx getprismo usage claude
 ## Example Output
 
 ```text
-Prismo Dev Scan
+PrismoDev
 
 Score: 72/100  |  Risk: Medium  |  Token leaks: 5
 Estimated avoidable waste: 20-40%
@@ -59,6 +70,27 @@ Then: npx getprismo optimize
 Then: npx getprismo context frontend
 ```
 
+## Setup And Live Watch
+
+```bash
+npx getprismo setup
+```
+
+Setup is read-only. It detects Claude Code, Codex, Cursor, local logs, MCP/tool config, and whether the Prismo proxy is reachable for exact API tracking.
+
+```bash
+npx getprismo watch
+```
+
+Watch is the local live session view. It shows active session tokens, context risk, tool/output token spikes, largest context sources, top tools, warnings, and the next recommended action.
+
+For machine-readable output:
+
+```bash
+npx getprismo setup --json
+npx getprismo watch --once --json
+```
+
 ## Local Usage Tracking
 
 Prismo can show real token usage when local tool logs expose token fields.
@@ -105,6 +137,8 @@ Existing reports and suggestion files are backed up before replacement.
 ```bash
 npx getprismo --help
 npx getprismo scan --help
+npx getprismo setup --help
+npx getprismo watch --help
 npx getprismo optimize --help
 npx getprismo usage --help
 ```

package/lib/prismo-dev-scan.js

@@ -1,4 +1,6 @@
 const fs = require("fs");
+const http = require("http");
+const https = require("https");
 const os = require("os");
 const path = require("path");
 
@@ -129,6 +131,7 @@ const DEFAULT_CLAUDEIGNORE = [
 ];
 
 const NPX_COMMAND = "npx getprismo";
+const DEFAULT_PRISMO_PROXY_URL = process.env.PRISMO_PROXY_URL || "http://localhost:8000";
 
 function shouldUseColor() {
   return process.stdout.isTTY && !process.env.NO_COLOR;
@@ -391,6 +394,270 @@ function scanCodexConfig(root) {
   return { files: found, mcpServers };
 }
 
+function commandExists(command) {
+  const pathEntries = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  const names = process.platform === "win32" ? [command, `${command}.cmd`, `${command}.exe`, `${command}.ps1`] : [command];
+  return pathEntries.some((entry) => names.some((name) => fs.existsSync(path.join(entry, name))));
+}
+
+function pathExistsAny(paths) {
+  return paths.some((candidate) => fs.existsSync(candidate));
+}
+
+function detectOptimizationStack(root, claudeConfig, codexConfig) {
+  const projectClaudePlugin = fs.existsSync(path.join(root, ".claude-plugin")) || fs.existsSync(path.join(root, ".claude", "settings.json"));
+  const projectMana = fs.existsSync(path.join(root, ".mana-mcp.json")) || fs.existsSync(path.join(os.homedir(), ".mana"));
+  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 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" },
+  };
+
+  return {
+    tools,
+    claudeHooks: claudeConfig.hooks,
+    claudeMcpServers: claudeConfig.mcpServers,
+    codexMcpServers: codexConfig.mcpServers,
+    claudePluginDetected: projectClaudePlugin,
+    mcpServerTotal: claudeConfig.mcpServers + codexConfig.mcpServers,
+    detectedTools: Object.entries(tools).filter(([, value]) => value.detected).map(([name]) => name),
+  };
+}
+
+function detectAgentReadiness(root, claudeConfig, codexConfig, realUsage) {
+  const claudeHome = process.env.PRISMO_CLAUDE_HOME || path.join(os.homedir(), ".claude");
+  const codexHome = process.env.PRISMO_CODEX_HOME || path.join(os.homedir(), ".codex");
+  const cursorPaths = [
+    path.join(root, ".cursor"),
+    path.join(root, ".cursorrules"),
+    path.join(os.homedir(), ".cursor"),
+    path.join(os.homedir(), ".config", "Cursor"),
+  ];
+  const usageSources = new Set(realUsage && realUsage.sources ? realUsage.sources : []);
+
+  const claudeSessionFiles = getClaudeSessionFiles(root);
+  const codexSessionFiles = getCodexSessionFiles();
+
+  return {
+    claudeCode: {
+      detected: claudeConfig.files.length > 0 || fs.existsSync(claudeHome) || claudeSessionFiles.length > 0,
+      configFiles: claudeConfig.files,
+      localLogsFound: claudeSessionFiles.length > 0 || usageSources.has("claude-code"),
+      mcpServers: claudeConfig.mcpServers,
+      hooks: claudeConfig.hooks,
+      exactProxyTracking: "limited-for-subscription-mode",
+      recommendedMode: "local-log-and-repo-scan",
+    },
+    codex: {
+      detected: codexConfig.files.length > 0 || fs.existsSync(codexHome) || codexSessionFiles.length > 0,
+      configFiles: codexConfig.files,
+      localLogsFound: codexSessionFiles.length > 0 || usageSources.has("codex"),
+      mcpServers: codexConfig.mcpServers,
+      exactProxyTracking: "available-when-using-api-key-base-url-mode",
+      recommendedMode: "prismo-proxy-for-api-mode-or-local-log-watch",
+    },
+    cursor: {
+      detected: pathExistsAny(cursorPaths),
+      configFiles: cursorPaths.filter((candidate) => fs.existsSync(candidate)),
+      localLogsFound: false,
+      exactProxyTracking: "available-only-if-configured-for-openai-compatible-base-url",
+      recommendedMode: "repo-scan-and-prismo-proxy-when-supported",
+    },
+    localUsageLogsAvailable: Boolean((realUsage && realUsage.sessions.length) || claudeSessionFiles.length || codexSessionFiles.length),
+    exactProxyTrackingAvailable: true,
+    notes: [
+      "Exact tracking is available when a tool sends OpenAI/Anthropic API traffic through Prismo.",
+      "Subscription coding-agent sessions usually require local-log visibility unless the tool supports a custom base URL.",
+    ],
+  };
+}
+
+function detectToolOutputRisk({ exposedLargeFiles, exposedHighRiskDirs, highRiskDirs }) {
+  const noisyDirs = highRiskDirs.filter((dir) => ["coverage", "test-results", "playwright-report", "logs", "dist", "build", ".next"].some((name) => dir.path.split("/").includes(name)));
+  const exposedNoisyDirs = exposedHighRiskDirs.filter((dir) => noisyDirs.some((candidate) => candidate.path === dir.path));
+  const noisyFiles = exposedLargeFiles.filter((file) => ["log", "json", "minified", "lock/generated"].includes(file.kind) || /\.(log|json|ndjson|out|trace|har)$/i.test(file.path));
+  const estimatedExposureTokens = estimateTokens(noisyFiles.reduce((sum, file) => sum + file.size, 0));
+  let level = "Low";
+  if (exposedNoisyDirs.length >= 3 || noisyFiles.length >= 3 || estimatedExposureTokens >= 250000) level = "High";
+  else if (exposedNoisyDirs.length || noisyFiles.length || estimatedExposureTokens >= 50000) level = "Medium";
+
+  return {
+    level,
+    exposedNoisyDirectories: exposedNoisyDirs.map((dir) => dir.path),
+    noisyDirectoriesDetected: noisyDirs.map((dir) => ({ path: dir.path, exposed: dir.exposed })),
+    exposedNoisyFiles: noisyFiles.map((file) => ({
+      path: file.path,
+      kind: file.kind,
+      sizeBytes: file.size,
+      estimatedTokensIfRead: estimateTokens(file.size),
+    })),
+    estimatedExposureTokens,
+    summary:
+      level === "High"
+        ? "Large logs, test reports, build output, or generated files are exposed to coding-agent reads."
+        : level === "Medium"
+          ? "Some noisy tool-output artifacts are present and may enter context during broad exploration."
+          : "No major exposed tool-output artifacts detected.",
+  };
+}
+
+function buildProxyTrackingReadiness({ codexConfig, claudeConfig, realUsage }) {
+  return {
+    exactApiTracking: {
+      available: true,
+      description: "Available for apps and coding tools that send OpenAI or Anthropic API traffic through the Prismo base URL.",
+    },
+    codingAgentBaseUrlMode: {
+      codex: codexConfig.files.length ? "possible-if-using-api-key-mode" : "not-detected",
+      claudeCode: "limited-for-subscription-sessions",
+      cursor: "possible-if-configured-for-openai-compatible-provider",
+    },
+    localEstimateTracking: {
+      available: true,
+      logsFound: Boolean(realUsage && realUsage.sessions.length),
+      description: "Available for subscription coding tools when local Codex/Claude Code logs exist; accuracy depends on token fields exposed by those tools.",
+    },
+    unsupported: [
+      "Exact billing for hidden subscription sessions without provider traffic, API keys, or local token fields.",
+      "Prompt interception or tool rewriting is not enabled by PrismoDev Scan.",
+    ],
+  };
+}
+
+function checkUrlReachable(url, timeoutMs = 650) {
+  return new Promise((resolve) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      resolve({ url, reachable: false, error: "invalid-url" });
+      return;
+    }
+    const client = parsed.protocol === "https:" ? https : http;
+    const request = client.request(
+      {
+        method: "GET",
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.pathname === "/" ? "/health" : parsed.pathname,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        response.resume();
+        resolve({ url, reachable: response.statusCode >= 200 && response.statusCode < 500, statusCode: response.statusCode });
+      }
+    );
+    request.on("timeout", () => {
+      request.destroy();
+      resolve({ url, reachable: false, error: "timeout" });
+    });
+    request.on("error", (error) => {
+      resolve({ url, reachable: false, error: error.code || error.message });
+    });
+    request.end();
+  });
+}
+
+async function runSetup(rootDir = process.cwd(), options = {}) {
+  const scan = scanRepo(rootDir, { includeUsage: true, usageLimit: options.limit || 3 });
+  const proxyUrl = options.proxyUrl || DEFAULT_PRISMO_PROXY_URL;
+  const proxy = options.skipProxyCheck
+    ? { url: proxyUrl, reachable: false, skipped: true }
+    : await checkUrlReachable(proxyUrl, options.timeoutMs || 650);
+
+  const modes = [
+    {
+      id: "local-log-tracking",
+      label: "Local log tracking",
+      status: scan.agentReadiness.localUsageLogsAvailable ? "available" : "limited",
+      description: "Reads local Codex/Claude Code session logs when present. Good for subscription coding tools when exact proxy traffic is unavailable.",
+    },
+    {
+      id: "exact-api-proxy",
+      label: "Exact API proxy tracking",
+      status: proxy.reachable ? "available" : "proxy-not-running",
+      description: "Exact tokens, costs, routing, budgets, and analytics when app or coding-tool traffic uses the Prismo OpenAI/Anthropic base URL.",
+    },
+    {
+      id: "codex-base-url",
+      label: "Codex API/base-url mode",
+      status: scan.agentReadiness.codex.detected ? "possible" : "not-detected",
+      description: "Use Prismo for exact tracking when Codex is running with API-key/base-url compatible traffic.",
+    },
+    {
+      id: "claude-subscription",
+      label: "Claude subscription sessions",
+      status: scan.agentReadiness.claudeCode.detected ? "local-estimates-only" : "not-detected",
+      description: "Claude Code subscription traffic is not exact unless it can be routed through Prismo; use local logs and repo diagnostics otherwise.",
+    },
+  ];
+
+  const recommended = [];
+  recommended.push(`${NPX_COMMAND} watch`);
+  if (!scan.hasClaudeIgnore) recommended.push(`${NPX_COMMAND} scan --fix`);
+  recommended.push(`${NPX_COMMAND} optimize`);
+  if (proxy.reachable) {
+    recommended.push(`OPENAI_BASE_URL=${proxyUrl.replace(/\/$/, "")}/v1 codex`);
+  } else {
+    recommended.push("Start the Prismo proxy, then route API-mode tools through its OpenAI/Anthropic base URL.");
+  }
+
+  return {
+    scannedPath: scan.root,
+    generatedAt: new Date().toISOString(),
+    prismoProxy: proxy,
+    detected: {
+      claudeCode: scan.agentReadiness.claudeCode,
+      codex: scan.agentReadiness.codex,
+      cursor: scan.agentReadiness.cursor,
+      optimizationStack: scan.optimizationStack,
+      localUsageLogsAvailable: scan.agentReadiness.localUsageLogsAvailable,
+    },
+    trackingModes: modes,
+    recommendedCommands: Array.from(new Set(recommended)).slice(0, 5),
+    caveats: [
+      "Prismo can track exact usage only when traffic flows through the Prismo proxy.",
+      "Subscription coding tools may expose local logs, but those are local visibility signals rather than provider billing records.",
+      "Setup is read-only and does not modify Claude, Codex, Cursor, MCP, shell, or Prismo config.",
+    ],
+  };
+}
+
+function renderSetupTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("PrismoDev Setup", "bold"));
+  lines.push("");
+  lines.push(`Repo: ${result.scannedPath}`);
+  lines.push(`Prismo proxy: ${result.prismoProxy.reachable ? "running" : "not reachable"} (${result.prismoProxy.url})`);
+  if (result.prismoProxy.statusCode) lines.push(`Proxy status: HTTP ${result.prismoProxy.statusCode}`);
+  lines.push("");
+  lines.push("Detected:");
+  lines.push(`- Claude Code: ${result.detected.claudeCode.detected ? "detected" : "not detected"}; logs: ${result.detected.claudeCode.localLogsFound ? "found" : "not found"}; MCP: ${result.detected.claudeCode.mcpServers}; hooks: ${result.detected.claudeCode.hooks}`);
+  lines.push(`- Codex: ${result.detected.codex.detected ? "detected" : "not detected"}; logs: ${result.detected.codex.localLogsFound ? "found" : "not found"}; MCP: ${result.detected.codex.mcpServers}`);
+  lines.push(`- Cursor: ${result.detected.cursor.detected ? "detected" : "not detected"}`);
+  const detectedTools = result.detected.optimizationStack.detectedTools;
+  lines.push(`- Optimization tools: ${detectedTools.length ? detectedTools.join(", ") : "none detected"}`);
+  lines.push("");
+  lines.push("Tracking Modes:");
+  result.trackingModes.forEach((mode, index) => {
+    lines.push(`${index + 1}. ${mode.label}: ${mode.status}`);
+    lines.push(`   ${mode.description}`);
+  });
+  lines.push("");
+  lines.push("Recommended:");
+  result.recommendedCommands.forEach((command, index) => lines.push(`${index + 1}. ${command}`));
+  lines.push("");
+  lines.push("Notes:");
+  result.caveats.forEach((caveat) => lines.push(`- ${caveat}`));
+  return lines.join("\n");
+}
+
 function classifyLargeFiles(files) {
   return files
     .filter((file) => file.kind !== "binary" && file.size >= 500 * 1024)
@@ -433,7 +700,7 @@ function estimateMcpImpact(count) {
 }
 
 function severityWeight(severity) {
-  return severity === "critical" ? 22 : severity === "high" ? 14 : severity === "medium" ? 8 : 4;
+  return severity === "critical" ? 10 : severity === "high" ? 6 : severity === "medium" ? 4 : 2;
 }
 
 function severityRank(severity) {
@@ -451,7 +718,7 @@ function addIssue(issues, severity, category, title, description, recommendation
   });
 }
 
-function buildRecommendations({ hasClaudeIgnore, gitignorePatterns, exposedHighRiskDirs, largeFiles, instructionFiles, claudeConfig }) {
+function buildRecommendations({ hasClaudeIgnore, gitignorePatterns, exposedHighRiskDirs, largeFiles, instructionFiles, claudeConfig, toolOutputRisk, agentReadiness }) {
   const recs = [];
   if (!hasClaudeIgnore) {
     recs.push("Create .claudeignore with generated/cache folders and large artifacts excluded.");
@@ -465,6 +732,9 @@ function buildRecommendations({ hasClaudeIgnore, gitignorePatterns, exposedHighR
   if (largeFiles.some((file) => !file.ignored)) {
     recs.push("Avoid loading large logs, JSON dumps, coverage reports, and minified assets into coding-agent context.");
   }
+  if (toolOutputRisk && toolOutputRisk.level !== "Low") {
+    recs.push("Use command-output filtering or narrower shell commands for noisy tests, logs, diffs, and generated reports.");
+  }
   if (instructionFiles.some((file) => file.isClaude && file.tokens > 500)) {
     recs.push("Trim CLAUDE.md to project rules only; move long implementation notes into docs referenced on demand.");
   }
@@ -473,17 +743,24 @@ function buildRecommendations({ hasClaudeIgnore, gitignorePatterns, exposedHighR
   }
   recs.push("Start fresh sessions for unrelated tasks and compact long sessions when context growth accelerates.");
   recs.push("Use cheaper/faster models for mechanical edits, formatting, and low-risk refactors.");
+  if (agentReadiness && (agentReadiness.codex.detected || agentReadiness.claudeCode.detected)) {
+    recs.push("Run `npx getprismo watch` for local coding-session visibility while working.");
+  }
+  recs.push("Route API-mode coding tools through Prismo when they support custom OpenAI/Anthropic base URLs for exact cost tracking.");
   return Array.from(new Set(recs));
 }
 
-function scoreScan(issues, stats) {
-  let score = 100;
-  for (const issue of issues) {
-    score -= severityWeight(issue.severity);
-  }
-  if (stats.totalFiles > 2500) score -= 8;
-  if (stats.exposedLargeFiles > 10) score -= 8;
-  if (stats.exposedHighRiskDirs > 4) score -= 8;
+function scoreScan(issues, stats, context = {}) {
+  const issuePenalty = issues.reduce((sum, issue) => sum + severityWeight(issue.severity), 0);
+  const repoPenalty =
+    (stats.totalFiles > 2500 ? 4 : 0) +
+    (stats.exposedLargeFiles > 10 ? 4 : 0) +
+    (stats.exposedHighRiskDirs > 4 ? 4 : 0);
+  const toolOutputPenalty = context.toolOutputRisk && context.toolOutputRisk.level === "High" ? 8 : context.toolOutputRisk && context.toolOutputRisk.level === "Medium" ? 4 : 0;
+  const readinessCredit = context.agentReadiness && context.agentReadiness.localUsageLogsAvailable ? 3 : 0;
+  const proxyCredit = context.proxyTrackingReadiness && context.proxyTrackingReadiness.exactApiTracking.available ? 2 : 0;
+
+  let score = 100 - issuePenalty - repoPenalty - toolOutputPenalty + readinessCredit + proxyCredit;
   score = Math.max(0, Math.min(100, score));
 
   const risk = score >= 80 ? "Low" : score >= 55 ? "Medium" : "High";
@@ -516,6 +793,8 @@ function toJsonPayload(result) {
     score: result.score,
     riskLevel: result.risk,
     estimatedAvoidableWasteRange: result.avoidableWaste,
+    detectedFrameworks: result.frameworks,
+    stats: result.stats,
     issues: result.issues,
     recommendations: result.recommendations,
     largeFiles: result.largeFiles.map((file) => ({
@@ -551,6 +830,10 @@ function toJsonPayload(result) {
       hasCodexDirectory: fs.existsSync(path.join(result.root, ".codex")),
       hasOpenAiDirectory: fs.existsSync(path.join(result.root, ".openai")),
     },
+    agentReadiness: result.agentReadiness,
+    optimizationStack: result.optimizationStack,
+    toolOutputRisk: result.toolOutputRisk,
+    proxyTrackingReadiness: result.proxyTrackingReadiness,
     suggestedClaudeIgnore: result.recommendedClaudeIgnore,
     nextCommands: getNextCommands(result),
     generatedAt: result.generatedAt,
@@ -570,7 +853,7 @@ function addRealUsageIssues(issues, usage) {
   if (total >= 1000000) {
     addIssue(
       issues,
-      total >= 5000000 ? "critical" : "high",
+      total >= 10000000 ? "high" : "medium",
       "repo_size",
       `Recent local AI sessions used ${formatTokenCount(total)} tokens`,
       exact ? "Prismo found exact token counts in local Codex/Claude Code session logs." : "Prismo estimated usage from local session text because exact token fields were unavailable.",
@@ -644,6 +927,7 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
   const combinedIgnorePatterns = Array.from(new Set([...gitignorePatterns, ...claudeIgnorePatterns]));
 
   const { files, highRiskDirs } = walkRepo(root, combinedIgnorePatterns);
+  const frameworks = detectFrameworks(root, { files });
   const instructionFiles = scanInstructionFiles(root);
   const largeFiles = classifyLargeFiles(files);
   const exposedLargeFiles = largeFiles.filter((file) => !file.ignored);
@@ -704,7 +988,7 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
   if (!hasClaudeIgnore) {
     addIssue(
       issues,
-      exposedHighRiskDirs.length || exposedLargeFiles.length ? "critical" : "high",
+      exposedHighRiskDirs.length > 5 && exposedLargeFiles.length > 3 ? "critical" : "high",
       "ignore_file",
       ".claudeignore not found",
       "Claude Code-style workflows may expose generated files, caches, and logs unless they are ignored.",
@@ -801,6 +1085,36 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
 
   const realUsage = options.includeUsage ? getUsageSummary({ tool: options.usageTool || "all", cwd: root, limit: options.usageLimit || 5 }) : null;
   addRealUsageIssues(issues, realUsage);
+  const optimizationStack = detectOptimizationStack(root, claudeConfig, codexConfig);
+  const agentReadiness = detectAgentReadiness(root, claudeConfig, codexConfig, realUsage);
+  const toolOutputRisk = detectToolOutputRisk({ exposedLargeFiles, exposedHighRiskDirs, highRiskDirs });
+  const proxyTrackingReadiness = buildProxyTrackingReadiness({ codexConfig, claudeConfig, realUsage });
+
+  if (toolOutputRisk.level !== "Low") {
+    addIssue(
+      issues,
+      toolOutputRisk.level === "High" ? "high" : "medium",
+      "large_file",
+      `Tool output risk is ${toolOutputRisk.level}`,
+      toolOutputRisk.summary,
+      "Use narrower commands, summarize logs, and ignore generated test/build output before loading it into coding agents.",
+      toolOutputRisk.estimatedExposureTokens
+        ? `Likely avoidable token exposure: up to ~${toolOutputRisk.estimatedExposureTokens.toLocaleString()} tokens from exposed noisy artifacts.`
+        : "Potential savings estimate: prevents noisy command/file output from becoming recurring context."
+    );
+  }
+
+  if (optimizationStack.mcpServerTotal >= 8) {
+    addIssue(
+      issues,
+      "medium",
+      "mcp_tooling",
+      `${optimizationStack.mcpServerTotal} total MCP/tool servers detected`,
+      "Large tool surfaces can increase tool-choice overhead across Claude Code and Codex-style workflows.",
+      "Disable MCP servers not needed for the current repo or current task.",
+      estimateMcpImpact(optimizationStack.mcpServerTotal)
+    );
+  }
 
   const sourceFiles = files.filter((file) => file.kind === "source").length;
   const stats = {
@@ -834,7 +1148,7 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
       "Likely avoidable token exposure: large repos make repeated discovery more expensive."
     );
   }
-  const score = scoreScan(issues, stats);
+  const score = scoreScan(issues, stats, { toolOutputRisk, agentReadiness, proxyTrackingReadiness });
   const largeFileSuggestions = exposedLargeFiles
     .filter((file) => file.size >= 1024 * 1024 || ["log", "json", "minified", "lock/generated"].includes(file.kind))
     .map((file) => file.path);
@@ -850,6 +1164,8 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
     largeFiles,
     instructionFiles,
     claudeConfig,
+    toolOutputRisk,
+    agentReadiness,
   });
   buildRealUsageRecommendations(realUsage).forEach((rec) => recommendations.push(rec));
 
@@ -861,6 +1177,11 @@ function scanRepo(rootDir = process.cwd(), options = {}) {
     issues,
     recommendations,
     realUsage,
+    agentReadiness,
+    optimizationStack,
+    toolOutputRisk,
+    proxyTrackingReadiness,
+    frameworks,
     files,
     instructionFiles,
     largeFiles,
@@ -886,7 +1207,7 @@ function renderTerminalReport(result, options = {}) {
   const riskTone = result.risk === "High" ? "red" : result.risk === "Medium" ? "yellow" : "green";
   const lines = [];
   lines.push("");
-  lines.push(color("Prismo Dev Scan", "bold", useColor));
+  lines.push(color("PrismoDev", "bold", useColor));
   lines.push("");
   lines.push(`Score: ${color(`${result.score}/100`, riskTone, useColor)}  |  Risk: ${color(result.risk, riskTone, useColor)}  |  Token leaks: ${result.issues.length}`);
   lines.push(`Estimated avoidable waste: ${result.avoidableWaste}`);
@@ -917,6 +1238,31 @@ function renderTerminalReport(result, options = {}) {
     lines.push("- Real local usage: no matching local Codex/Claude Code sessions found for this repo");
   }
   lines.push("");
+  lines.push(color("Coding Agent Readiness", "bold", useColor));
+  lines.push(`- Claude Code: ${result.agentReadiness.claudeCode.detected ? "detected" : "not detected"}; logs: ${result.agentReadiness.claudeCode.localLogsFound ? "found" : "not found"}; MCP: ${result.agentReadiness.claudeCode.mcpServers}; hooks: ${result.agentReadiness.claudeCode.hooks}`);
+  lines.push(`- Codex: ${result.agentReadiness.codex.detected ? "detected" : "not detected"}; logs: ${result.agentReadiness.codex.localLogsFound ? "found" : "not found"}; MCP: ${result.agentReadiness.codex.mcpServers}`);
+  lines.push(`- Cursor: ${result.agentReadiness.cursor.detected ? "detected" : "not detected"}`);
+  lines.push("");
+  lines.push(color("Optimization Stack", "bold", useColor));
+  const stack = result.optimizationStack;
+  lines.push(`- RTK: ${stack.tools.rtk.detected ? "detected" : "not detected"}`);
+  lines.push(`- Headroom: ${stack.tools.headroom.detected ? "detected" : "not detected"}`);
+  lines.push(`- Distill: ${stack.tools.distill.detected ? "detected" : "not detected"}`);
+  lines.push(`- Mana: ${stack.tools.mana.detected ? "detected" : "not detected"}`);
+  lines.push(`- Claude hooks: ${stack.claudeHooks}; MCP servers: ${stack.mcpServerTotal}`);
+  lines.push("");
+  lines.push(color("Tool Output Risk", "bold", useColor));
+  lines.push(`- Level: ${result.toolOutputRisk.level}`);
+  lines.push(`- ${result.toolOutputRisk.summary}`);
+  if (result.toolOutputRisk.exposedNoisyDirectories.length) lines.push(`- Exposed noisy dirs: ${result.toolOutputRisk.exposedNoisyDirectories.slice(0, 6).join(", ")}`);
+  if (result.toolOutputRisk.exposedNoisyFiles.length) lines.push(`- Exposed noisy files: ${result.toolOutputRisk.exposedNoisyFiles.slice(0, 4).map((file) => file.path).join(", ")}`);
+  lines.push("");
+  lines.push(color("Prismo Proxy Tracking", "bold", useColor));
+  lines.push("- Exact API tracking: available when traffic uses the Prismo OpenAI/Anthropic base URL");
+  lines.push(`- Codex API/base-url mode: ${result.proxyTrackingReadiness.codingAgentBaseUrlMode.codex}`);
+  lines.push(`- Claude Code subscription mode: ${result.proxyTrackingReadiness.codingAgentBaseUrlMode.claudeCode}`);
+  lines.push("- Subscription sessions: local-log visibility when available, not guaranteed billing accuracy");
+  lines.push("");
   lines.push(color("Issues", "bold", useColor));
   if (!result.issues.length) {
     lines.push("- [ok] No major token-waste risks detected.");
@@ -943,7 +1289,7 @@ function renderTerminalReport(result, options = {}) {
 
 function renderMarkdownReport(result) {
   const lines = [];
-  lines.push("# Prismo Dev Scan Report");
+  lines.push("# PrismoDev Report");
   lines.push("");
   lines.push("## Executive Summary");
   lines.push("");
@@ -977,6 +1323,49 @@ function renderMarkdownReport(result) {
   lines.push(`- Token-bloat directories: ${result.stats.highRiskDirs}`);
   lines.push(`- Exposed token-bloat directories: ${result.stats.exposedHighRiskDirs}`);
   lines.push("");
+  lines.push("## Coding Agent Readiness");
+  lines.push("");
+  lines.push(`- Claude Code detected: ${result.agentReadiness.claudeCode.detected ? "yes" : "no"}`);
+  lines.push(`  - Local logs found: ${result.agentReadiness.claudeCode.localLogsFound ? "yes" : "no"}`);
+  lines.push(`  - MCP servers: ${result.agentReadiness.claudeCode.mcpServers}; hooks: ${result.agentReadiness.claudeCode.hooks}`);
+  lines.push(`  - Exact proxy tracking: ${result.agentReadiness.claudeCode.exactProxyTracking}`);
+  lines.push(`- Codex detected: ${result.agentReadiness.codex.detected ? "yes" : "no"}`);
+  lines.push(`  - Local logs found: ${result.agentReadiness.codex.localLogsFound ? "yes" : "no"}`);
+  lines.push(`  - MCP servers: ${result.agentReadiness.codex.mcpServers}`);
+  lines.push(`  - Exact proxy tracking: ${result.agentReadiness.codex.exactProxyTracking}`);
+  lines.push(`- Cursor detected: ${result.agentReadiness.cursor.detected ? "yes" : "no"}`);
+  lines.push(`  - Exact proxy tracking: ${result.agentReadiness.cursor.exactProxyTracking}`);
+  lines.push("");
+  lines.push("## Optimization Stack");
+  lines.push("");
+  lines.push(`- RTK: ${result.optimizationStack.tools.rtk.detected ? "detected" : "not detected"}`);
+  lines.push(`- Headroom: ${result.optimizationStack.tools.headroom.detected ? "detected" : "not detected"}`);
+  lines.push(`- Distill: ${result.optimizationStack.tools.distill.detected ? "detected" : "not detected"}`);
+  lines.push(`- Mana: ${result.optimizationStack.tools.mana.detected ? "detected" : "not detected"}`);
+  lines.push(`- Claude hooks: ${result.optimizationStack.claudeHooks}`);
+  lines.push(`- Total MCP/tool servers: ${result.optimizationStack.mcpServerTotal}`);
+  lines.push("");
+  lines.push("## Tool Output Risk");
+  lines.push("");
+  lines.push(`- Level: ${result.toolOutputRisk.level}`);
+  lines.push(`- ${result.toolOutputRisk.summary}`);
+  if (result.toolOutputRisk.exposedNoisyDirectories.length) {
+    lines.push(`- Exposed noisy directories: ${result.toolOutputRisk.exposedNoisyDirectories.map((dir) => `\`${dir}/\``).join(", ")}`);
+  }
+  if (result.toolOutputRisk.exposedNoisyFiles.length) {
+    result.toolOutputRisk.exposedNoisyFiles.slice(0, 20).forEach((file) => {
+      lines.push(`- \`${file.path}\` - ${formatBytes(file.sizeBytes)} - ~${file.estimatedTokensIfRead.toLocaleString()} tokens if read`);
+    });
+  }
+  lines.push("");
+  lines.push("## Prismo Proxy Tracking Readiness");
+  lines.push("");
+  lines.push("- Exact API tracking: available when app/tool traffic uses the Prismo OpenAI/Anthropic base URL.");
+  lines.push(`- Codex API/base-url mode: ${result.proxyTrackingReadiness.codingAgentBaseUrlMode.codex}.`);
+  lines.push(`- Claude Code subscription mode: ${result.proxyTrackingReadiness.codingAgentBaseUrlMode.claudeCode}.`);
+  lines.push("- Local estimate tracking: available from local Codex/Claude Code logs when those logs exist.");
+  lines.push("- Unsupported: exact billing for hidden subscription sessions without provider traffic, API keys, or local token fields.");
+  lines.push("");
   if (result.realUsage) {
     lines.push("## Real Local Usage");
     lines.push("");
@@ -1058,7 +1447,7 @@ function renderMarkdownReport(result) {
   lines.push("");
   lines.push("## Disclaimer");
   lines.push("");
-  lines.push("Prismo Dev Scan is a fast local scanner. It does not connect to Anthropic, OpenAI, Claude Code, Codex, Cursor, or billing accounts. Token and savings estimates are heuristic and should be treated as directional diagnostics only.");
+  lines.push("PrismoDev is a fast local scanner. It does not connect to Anthropic, OpenAI, Claude Code, Codex, Cursor, or billing accounts. Token and savings estimates are heuristic and should be treated as directional diagnostics only.");
   lines.push("");
   return lines.join("\n");
 }
@@ -1821,7 +2210,11 @@ function analyzeSessionFile(filePath, tool) {
 
   session.turns = Math.max(session.userMessages, session.assistantMessages);
   session.estimatedTotalTokens = session.estimatedInputTokens + session.estimatedOutputTokens + session.estimatedToolTokens;
-  session.displayTokens = session.exactAvailable ? session.exactTotalTokens : session.estimatedTotalTokens;
+  session.exactActiveTokens = session.exactAvailable
+    ? Math.max(session.exactInputTokens - session.exactCacheReadTokens, 0) + session.exactOutputTokens + (session.exactCacheCreationTokens || 0)
+    : 0;
+  session.contextTokens = session.exactAvailable ? session.exactTotalTokens : session.estimatedTotalTokens;
+  session.displayTokens = session.exactAvailable ? session.exactActiveTokens : session.estimatedTotalTokens;
   session.confidence = session.exactAvailable ? "exact-local-log" : "estimated-local-log";
   session.contextRisk = getSessionRisk(session.displayTokens, session.estimatedToolTokens);
   session.largestTextBlobs = session.largestTextBlobs.sort((a, b) => b.tokens - a.tokens).slice(0, 5);
@@ -1835,15 +2228,27 @@ function getCodexSessionFiles() {
 
 function getClaudeSessionFiles(cwd = process.cwd()) {
   const claudeHome = process.env.PRISMO_CLAUDE_HOME || path.join(os.homedir(), ".claude");
-  const safeProject = cwd.replace(/[\/\\:]/g, "-").replace(/^-/, "-");
-  const projectDir = path.join(claudeHome, "projects", safeProject);
-  return listFilesRecursive(projectDir, (file) => file.endsWith(".jsonl"), 200);
+  const candidates = [cwd];
+  try {
+    candidates.push(fs.realpathSync(cwd));
+  } catch {
+    // Keep the original cwd candidate when realpath is unavailable.
+  }
+  const files = [];
+  for (const candidate of Array.from(new Set(candidates))) {
+    const safeProject = candidate.replace(/[\/\\:]/g, "-").replace(/^-/, "-");
+    const projectDir = path.join(claudeHome, "projects", safeProject);
+    files.push(...listFilesRecursive(projectDir, (file) => file.endsWith(".jsonl"), 200));
+  }
+  return Array.from(new Set(files));
 }
 
 function sameResolvedPath(a, b) {
   if (!a || !b) return false;
   try {
-    return path.resolve(a) === path.resolve(b);
+    const resolvedA = fs.existsSync(a) ? fs.realpathSync(a) : path.resolve(a);
+    const resolvedB = fs.existsSync(b) ? fs.realpathSync(b) : path.resolve(b);
+    return resolvedA === resolvedB;
   } catch {
     return false;
   }
@@ -1871,20 +2276,23 @@ function getUsageSummary(options = {}) {
   const totals = selected.reduce(
     (acc, session) => {
       acc.displayTokens += session.displayTokens || 0;
+      acc.contextTokens += session.contextTokens || 0;
       acc.estimatedTokens += session.estimatedTotalTokens || 0;
       acc.exactTokens += session.exactAvailable ? session.exactTotalTokens : 0;
       acc.toolTokens += session.estimatedToolTokens || 0;
       acc.sessions += 1;
       return acc;
     },
-    { sessions: 0, displayTokens: 0, estimatedTokens: 0, exactTokens: 0, toolTokens: 0 }
+    { sessions: 0, displayTokens: 0, contextTokens: 0, estimatedTokens: 0, exactTokens: 0, toolTokens: 0 }
   );
+  const sources = Array.from(new Set(selected.map((session) => session.tool).filter(Boolean)));
   return {
     generatedAt: new Date().toISOString(),
     scannedPath: cwd,
     tool,
     confidence: selected.every((session) => session.exactAvailable) && selected.length ? "exact-local-log" : "mixed-or-estimated",
     totals,
+    sources,
     sessions: selected,
   };
 }
@@ -1914,6 +2322,91 @@ function formatTokenCount(value) {
   return String(Math.round(n));
 }
 
+function getRiskRank(risk) {
+  return { High: 3, Medium: 2, Low: 1 }[risk] || 0;
+}
+
+function getTopToolNames(session, limit = 4) {
+  return Object.entries(session && session.toolNames ? session.toolNames : {})
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([name, count]) => ({ name, count }));
+}
+
+function buildLiveWarnings(activeSession, summary) {
+  const warnings = [];
+  if (!activeSession) {
+    warnings.push("No active local session detected for this repo yet.");
+    return warnings;
+  }
+  if (activeSession.contextRisk === "High") {
+    warnings.push("Context risk is high; consider starting a fresh session at the next task boundary.");
+  } else if (activeSession.contextRisk === "Medium") {
+    warnings.push("Context risk is rising; keep reads and shell output narrow.");
+  }
+  if (activeSession.estimatedToolTokens >= 150000) {
+    warnings.push("Tool/output tokens are dominating this session; summarize logs and test output before loading more.");
+  } else if (activeSession.estimatedToolTokens >= 50000) {
+    warnings.push("Tool/output tokens are elevated; prefer targeted commands and smaller file reads.");
+  }
+  if (activeSession.turns >= 30) {
+    warnings.push("Long session detected; split unrelated follow-up work into a new session.");
+  }
+  if (!activeSession.exactAvailable) {
+    warnings.push("Exact token fields were not found; usage is estimated from local session text.");
+  }
+  if (summary.totals.displayTokens >= 1000000) {
+    warnings.push("Recent local usage is above 1M tokens; prioritize the largest session for cleanup.");
+  }
+  return Array.from(new Set(warnings)).slice(0, 5);
+}
+
+function getRecommendedWatchAction(activeSession, warnings) {
+  if (!activeSession) return `${NPX_COMMAND} setup`;
+  if (warnings.some((warning) => warning.includes("Tool/output"))) return `${NPX_COMMAND} context`;
+  if (activeSession.contextRisk === "High") return "Start a fresh coding-agent session before the next unrelated task.";
+  if (activeSession.turns >= 20) return `${NPX_COMMAND} optimize`;
+  return `${NPX_COMMAND} scan --usage`;
+}
+
+function buildLiveSessionView(summary) {
+  const activeSession = summary.sessions[0] || null;
+  const warnings = buildLiveWarnings(activeSession, summary);
+  const topTools = getTopToolNames(activeSession);
+  const largestTextBlobs = activeSession ? activeSession.largestTextBlobs || [] : [];
+  return {
+    activeSession: activeSession
+      ? {
+          tool: activeSession.tool,
+          sessionId: activeSession.sessionId,
+          title: activeSession.title,
+          model: activeSession.model,
+          cwd: activeSession.cwd,
+          updatedAt: activeSession.updatedAt,
+          tokens: activeSession.displayTokens,
+          contextTokens: activeSession.contextTokens,
+          exactAvailable: activeSession.exactAvailable,
+          confidence: activeSession.confidence,
+          contextRisk: activeSession.contextRisk,
+          turns: activeSession.turns,
+          toolCalls: activeSession.toolCalls,
+          toolResults: activeSession.toolResults,
+          estimatedToolTokens: activeSession.estimatedToolTokens,
+          topTools,
+          largestTextBlobs,
+        }
+      : null,
+    highestRisk: summary.sessions.reduce((risk, session) => (getRiskRank(session.contextRisk) > getRiskRank(risk) ? session.contextRisk : risk), "Low"),
+    warnings,
+    recommendedAction: getRecommendedWatchAction(activeSession, warnings),
+    nextCommands: Array.from(new Set([
+      `${NPX_COMMAND} context`,
+      `${NPX_COMMAND} optimize`,
+      `${NPX_COMMAND} scan --usage`,
+    ])).slice(0, 3),
+  };
+}
+
 function renderUsageTerminal(summary, title = "Prismo Usage") {
   const lines = [];
   lines.push("");
@@ -1942,16 +2435,67 @@ function renderUsageTerminal(summary, title = "Prismo Usage") {
   return lines.join("\n");
 }
 
+function renderWatchTerminal(summary) {
+  const live = summary.live || buildLiveSessionView(summary);
+  const active = live.activeSession;
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Watch", "bold"));
+  lines.push("");
+  if (!active) {
+    lines.push("Active Session");
+    lines.push("- No local Codex/Claude Code session detected for this repo yet.");
+    lines.push("");
+    lines.push("Next Action");
+    lines.push(`Run: ${live.recommendedAction}`);
+    lines.push("");
+    lines.push("Tip: start Codex or Claude Code in this repo, then keep this watch open.");
+    return lines.join("\n");
+  }
+  lines.push("Active Session");
+  lines.push(`Source: ${active.tool}`);
+  lines.push(`Tokens: ${formatTokenCount(active.tokens)} (${active.confidence})`);
+  if (active.contextTokens && active.contextTokens !== active.tokens) lines.push(`Context tokens observed: ${formatTokenCount(active.contextTokens)}`);
+  lines.push(`Context Risk: ${active.contextRisk}`);
+  lines.push(`Tool/output tokens: ${formatTokenCount(active.estimatedToolTokens)}`);
+  lines.push(`Turns: ${active.turns}  |  Tool calls: ${active.toolCalls}`);
+  if (active.model) lines.push(`Model: ${active.model}`);
+  if (active.updatedAt) lines.push(`Updated: ${active.updatedAt}`);
+  lines.push("");
+  lines.push("Live Warnings");
+  live.warnings.forEach((warning) => lines.push(`- ${warning}`));
+  lines.push("");
+  if (active.largestTextBlobs.length) {
+    lines.push("Largest Context Sources");
+    active.largestTextBlobs.slice(0, 4).forEach((blob) => lines.push(`- ${blob.label}: ~${blob.tokens.toLocaleString()} tokens`));
+    lines.push("");
+  }
+  if (active.topTools.length) {
+    lines.push("Top Tools");
+    active.topTools.forEach((tool) => lines.push(`- ${tool.name}: ${tool.count}`));
+    lines.push("");
+  }
+  lines.push("Next Action");
+  lines.push(`Run: ${live.recommendedAction}`);
+  lines.push("");
+  lines.push("Useful Commands");
+  live.nextCommands.forEach((command) => lines.push(`- ${command}`));
+  lines.push("");
+  lines.push("Local estimates come from available coding-agent session logs; exact billing requires traffic routed through Prismo.");
+  return lines.join("\n");
+}
+
 async function watchUsage(options = {}) {
   const intervalMs = options.intervalMs || 3000;
   const iterations = options.once ? 1 : Number.POSITIVE_INFINITY;
   for (let i = 0; i < iterations; i += 1) {
     const summary = getUsageSummary(options);
+    summary.live = buildLiveSessionView(summary);
     if (options.json) {
       console.log(JSON.stringify(summary, null, 2));
     } else {
       console.clear();
-      console.log(renderUsageTerminal(summary, "Prismo Watch"));
+      console.log(renderWatchTerminal(summary));
       console.log(`\nRefreshing every ${Math.round(intervalMs / 1000)}s. Press Ctrl+C to stop.`);
     }
     if (i + 1 >= iterations) break;
@@ -2078,6 +2622,34 @@ function createDemoResult() {
       sessions: [{}, {}, {}],
     },
     stats: { totalFiles: 842, sourceFiles: 318, largeFiles: 4, exposedLargeFiles: 2, highRiskDirs: 7, exposedHighRiskDirs: 3 },
+    agentReadiness: {
+      claudeCode: { detected: true, localLogsFound: true, mcpServers: 4, hooks: 2, exactProxyTracking: "limited-for-subscription-mode" },
+      codex: { detected: true, localLogsFound: true, mcpServers: 1, exactProxyTracking: "available-when-using-api-key-base-url-mode" },
+      cursor: { detected: false, exactProxyTracking: "available-only-if-configured-for-openai-compatible-base-url" },
+      localUsageLogsAvailable: true,
+    },
+    optimizationStack: {
+      tools: {
+        rtk: { detected: false },
+        headroom: { detected: false },
+        distill: { detected: false },
+        mana: { detected: false },
+      },
+      claudeHooks: 2,
+      mcpServerTotal: 5,
+    },
+    toolOutputRisk: {
+      level: "High",
+      summary: "Large logs, test reports, build output, or generated files are exposed to coding-agent reads.",
+      exposedNoisyDirectories: ["logs", "coverage"],
+      exposedNoisyFiles: [{ path: "logs/debug-output.json" }],
+    },
+    proxyTrackingReadiness: {
+      codingAgentBaseUrlMode: {
+        codex: "possible-if-using-api-key-mode",
+        claudeCode: "limited-for-subscription-sessions",
+      },
+    },
     topTokenLeaks: getTopTokenLeaks(issues),
     hasClaudeIgnore: false,
     repoDetected: true,
@@ -2101,10 +2673,11 @@ function runDevFlow(rootDir = process.cwd(), options = {}) {
   const scanDone = printStep("Scanning repo and local usage", options.json);
   const scan = scanRepo(root, { includeUsage: true, usageLimit: options.limit || 3 });
   scanDone();
+  const initialContext = createOptimizeContext(root);
+  const scope = initialContext.frameworks.some((name) => ["Next.js", "React", "Vite"].includes(name)) ? "frontend" : null;
   const optimizeDone = printStep("Generating compact context files", options.json);
-  const optimize = runOptimize(root);
+  const optimize = runOptimize(root, { scope });
   optimizeDone();
-  const scope = optimize.frameworks.some((name) => ["Next.js", "React", "Vite"].includes(name)) ? "frontend" : null;
   const ctx = createOptimizeContext(root, scope);
   const prompt = renderContextCommand(ctx, scope);
   return {
@@ -2119,7 +2692,7 @@ function runDevFlow(rootDir = process.cwd(), options = {}) {
 function renderDevTerminal(result) {
   const lines = [];
   lines.push("");
-  lines.push(color("Prismo Dev", "bold"));
+  lines.push(color("PrismoDev", "bold"));
   lines.push("");
   lines.push(`Score: ${result.scan.score}/100  |  Risk: ${result.scan.risk}  |  Token leaks: ${result.scan.issues.length}`);
   if (result.scan.realUsage && result.scan.realUsage.sessions.length) {
@@ -2182,6 +2755,7 @@ function printHelp() {
 
 Usage:
   prismo dev [path]
+  prismo setup [--json] [--proxy-url URL] [path]
   prismo scan [--fix] [--json] [--usage] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
   prismo context [scope] [--json] [path]
@@ -2191,12 +2765,13 @@ Usage:
 
 Commands:
   dev         Guided flow: scan, optimize, and print a paste-ready context prompt.
-  scan        Run Prismo Dev Scan for Claude Code, Codex, Cursor, and AI coding workflows.
+  scan        Run PrismoDev for Claude Code, Codex, Cursor, and AI coding workflows.
   optimize    Generate lightweight AI-readable project context files in .prismo/.
   context     Print a copy-pasteable compact context prompt for AI coding tools.
   usage       Read local Codex/Claude Code session logs and summarize token usage.
   watch       Refresh local session usage in the terminal.
   demo        Show sample output without needing a messy repo.
+  setup       Detect coding tools, tracking modes, local logs, and Prismo proxy readiness.
 
 Options:
   --fix       Safely create .claudeignore if missing and generate the report.
@@ -2205,6 +2780,7 @@ Options:
   --no-report Do not write prismo-dev-report.md.
   --limit N   Number of recent local sessions to show.
   --interval N Refresh interval in seconds for watch mode.
+  --proxy-url URL Prismo proxy URL to check during setup.
   --once      Run watch mode once, useful for tests and scripts.
   --help      Show this help.
 `);
@@ -2212,7 +2788,7 @@ Options:
 
 function printCommandHelp(command) {
   const help = {
-    scan: `Prismo Scan
+    scan: `PrismoDev
 
 Usage:
   prismo scan [--fix] [--json] [--usage] [--no-report] [--limit N] [path]
@@ -2265,7 +2841,7 @@ Usage:
 Examples:
   prismo watch codex
   prismo watch claude --once --json`,
-    dev: `Prismo Dev
+    dev: `PrismoDev
 
 Usage:
   prismo dev [--json] [--limit N] [path]
@@ -2274,12 +2850,25 @@ Flow:
   1. Scan repo and local usage.
   2. Generate .prismo/ optimized context files.
   3. Print a paste-ready prompt.`,
+    setup: `PrismoDev Setup
+
+Usage:
+  prismo setup [--json] [--proxy-url URL] [--limit N] [path]
+
+Examples:
+  prismo setup
+  prismo setup --json
+  prismo setup --proxy-url http://localhost:8000
+
+Output:
+  Detects Claude Code, Codex, Cursor, local logs, optimization stack, and Prismo proxy readiness.
+  This command is read-only and does not modify coding-tool config.`,
     demo: `Prismo Demo
 
 Usage:
   prismo demo
 
-Shows sample Prismo Dev Scan output without reading local files.`,
+Shows sample PrismoDev output without reading local files.`,
   };
   console.log(help[command] || "Unknown command. Try: prismo --help");
 }
@@ -2294,8 +2883,8 @@ async function runCli(argv) {
     printCommandHelp(command);
     return;
   }
-  if (!["dev", "scan", "optimize", "context", "usage", "watch", "demo"].includes(command)) {
-    throw new Error(`Unknown command: ${command}. Try: prismo dev, prismo scan, prismo optimize, prismo context, or prismo usage`);
+  if (!["dev", "setup", "scan", "optimize", "context", "usage", "watch", "demo"].includes(command)) {
+    throw new Error(`Unknown command: ${command}. Try: prismo dev, prismo setup, prismo scan, prismo optimize, prismo context, or prismo usage`);
   }
 
   if (command === "demo") {
@@ -2329,6 +2918,24 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "setup") {
+    const json = rest.includes("--json");
+    const limitIndex = rest.indexOf("--limit");
+    const proxyIndex = rest.indexOf("--proxy-url");
+    const target = getPositionals(rest, new Set(["--limit", "--proxy-url"]))[0] || process.cwd();
+    const result = await runSetup(target, {
+      limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 3),
+      proxyUrl: proxyIndex >= 0 ? rest[proxyIndex + 1] : DEFAULT_PRISMO_PROXY_URL,
+      skipProxyCheck: rest.includes("--skip-proxy-check"),
+    });
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(renderSetupTerminal(result));
+    return;
+  }
+
   if (command === "usage" || command === "watch") {
     const json = rest.includes("--json");
     const knownTools = new Set(["codex", "claude", "all"]);
@@ -2455,7 +3062,9 @@ module.exports = {
   estimateTokens,
   renderMarkdownReport,
   renderUsageTerminal,
+  renderWatchTerminal,
   renderTerminalReport,
+  runSetup,
   runOptimize,
   runCli,
   scanRepo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "UNLICENSED",
   "publishConfig": {