smart-context-mcp 1.2.0 → 1.3.0

package/README.md

@@ -62,7 +62,8 @@ Restart your AI client. Done.
 - ✅ Token savings: 85-90% on complex tasks
 
 Check actual usage:
-- `npm run report:metrics` - Tool-level savings
+- **Real-time feedback** - See usage immediately (enable with `export DEVCTX_SHOW_USAGE=true`)
+- `npm run report:metrics` - Tool-level savings + adoption analysis
 - `npm run report:workflows` - Workflow-level savings (requires `DEVCTX_WORKFLOW_TRACKING=true`)
 
 ## What it does
@@ -102,6 +103,134 @@ Installation generates rules that teach agents optimal workflows:
 
 Production usage: **14.5M tokens → 1.6M tokens** (89.87% reduction)
 
+## Verify It's Working
+
+### Real-Time Feedback (Auto-enabled for First 10 Calls)
+
+Feedback is **automatically enabled** for your first 10 tool calls (onboarding mode), then auto-disables.
+
+**To keep it enabled permanently:**
+```bash
+export DEVCTX_SHOW_USAGE=true
+```
+
+**To disable immediately:**
+```bash
+export DEVCTX_SHOW_USAGE=false
+```
+
+You'll see at the end of agent responses:
+
+```markdown
+---
+
+📊 **devctx usage this session:**
+- **smart_read**: 3 calls | ~45.0K tokens saved (file1.js, file2.js, file3.js)
+- **smart_search**: 1 call | ~12.0K tokens saved (query)
+
+**Total saved:** ~57.0K tokens
+
+*Onboarding mode: showing for 3 more tool calls. To keep: `export DEVCTX_SHOW_USAGE=true`*
+```
+
+**Why this is useful:**
+- ✅ Verify agent is following rules
+- ✅ See token savings in real-time
+- ✅ Debug adoption issues instantly
+- ✅ Validate forcing prompts worked
+
+### Historical Metrics
+
+```bash
+npm run report:metrics
+```
+
+Shows adoption analysis + token savings over time.
+
+### Decision Explanations (Optional)
+
+Understand **why** the agent chose devctx tools:
+
+```bash
+export DEVCTX_EXPLAIN=true
+```
+
+You'll see explanations like:
+
+```markdown
+🤖 **Decision explanations:**
+
+**smart_read** (read server.js (outline mode))
+- **Why:** File is large (2500 lines), outline mode extracts structure only
+- **Instead of:** Read (full file)
+- **Expected benefit:** ~45.0K tokens saved
+
+**smart_search** (search "bug" (intent: debug))
+- **Why:** Intent-aware search prioritizes relevant results
+- **Expected benefit:** Better result ranking
+```
+
+**When to use:**
+- Learning how devctx works
+- Debugging tool selection
+- Understanding best practices
+
+### Missed Opportunities Detection (Optional)
+
+Detect when devctx **should have been used but wasn't**:
+
+```bash
+export DEVCTX_DETECT_MISSED=true
+```
+
+You'll see warnings like:
+
+```markdown
+⚠️ **Missed devctx opportunities detected:**
+
+**Session stats:**
+- devctx operations: 2
+- Estimated total: 25
+- Adoption: 8%
+
+🟡 **low devctx adoption**
+- **Issue:** Low adoption (8%). Target: >50%
+- **Potential savings:** ~184.0K tokens
+```
+
+**Detects:**
+- No devctx usage in long sessions
+- Low adoption (<30%)
+- Usage dropped mid-session
+
+**Combine all features:**
+
+```bash
+export DEVCTX_SHOW_USAGE=true    # See what's used
+export DEVCTX_EXPLAIN=true       # Understand why
+export DEVCTX_DETECT_MISSED=true # Detect gaps
+```
+
+## MCP Prompts
+
+The MCP server provides **prompts** for automatic forcing:
+
+```
+/prompt use-devctx
+```
+
+**Available prompts:**
+- `use-devctx` - Ultra-short forcing prompt
+- `devctx-workflow` - Complete workflow template
+- `devctx-preflight` - Preflight checklist
+
+**Benefits:**
+- No manual typing
+- Centrally managed
+- No typos
+
+See [MCP Prompts Documentation](../../docs/mcp-prompts.md).
+
 ## Core Tools
 
 ### smart_read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/src/decision-explainer.js

@@ -0,0 +1,168 @@
+/**
+ * Decision explainer - tracks and explains why devctx tools were used or not used
+ * 
+ * Enable with environment variable: DEVCTX_EXPLAIN=true
+ * 
+ * Provides transparency into agent decision-making:
+ * - Why was smart_read used instead of Read?
+ * - Why was smart_search chosen?
+ * - What are the expected benefits?
+ */
+
+const sessionDecisions = {
+  decisions: [],
+  enabled: false,
+};
+
+/**
+ * Check if explanations are enabled
+ */
+export const isExplainEnabled = () => {
+  const envValue = process.env.DEVCTX_EXPLAIN?.toLowerCase();
+  const enabled = envValue === 'true' || envValue === '1' || envValue === 'yes';
+  sessionDecisions.enabled = enabled;
+  return enabled;
+};
+
+/**
+ * Record a decision with explanation
+ */
+export const recordDecision = ({
+  tool,
+  action,
+  reason,
+  alternative = null,
+  expectedBenefit = null,
+  context = null,
+}) => {
+  if (!isExplainEnabled()) return;
+  
+  sessionDecisions.decisions.push({
+    tool,
+    action,
+    reason,
+    alternative,
+    expectedBenefit,
+    context,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Get all decisions for current session
+ */
+export const getSessionDecisions = () => {
+  return sessionDecisions.decisions;
+};
+
+/**
+ * Format decisions as markdown for display
+ */
+export const formatDecisionExplanations = () => {
+  if (!isExplainEnabled()) return '';
+  
+  const decisions = getSessionDecisions();
+  if (decisions.length === 0) return '';
+  
+  const lines = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('🤖 **Decision explanations:**');
+  lines.push('');
+  
+  for (const decision of decisions) {
+    lines.push(`**${decision.tool}** (${decision.action})`);
+    lines.push(`- **Why:** ${decision.reason}`);
+    
+    if (decision.alternative) {
+      lines.push(`- **Instead of:** ${decision.alternative}`);
+    }
+    
+    if (decision.expectedBenefit) {
+      lines.push(`- **Expected benefit:** ${decision.expectedBenefit}`);
+    }
+    
+    if (decision.context) {
+      lines.push(`- **Context:** ${decision.context}`);
+    }
+    
+    lines.push('');
+  }
+  
+  lines.push('*To disable: `export DEVCTX_EXPLAIN=false`*');
+  
+  return lines.join('\n');
+};
+
+/**
+ * Reset session decisions (for testing or manual reset)
+ */
+export const resetSessionDecisions = () => {
+  sessionDecisions.decisions = [];
+};
+
+/**
+ * Common decision reasons (for consistency)
+ */
+export const DECISION_REASONS = {
+  // smart_read reasons
+  LARGE_FILE: 'File is large (>500 lines), outline mode extracts structure only',
+  SYMBOL_EXTRACTION: 'Extracting specific symbol, smart_read can locate and extract it efficiently',
+  TOKEN_BUDGET: 'Token budget constraint, cascading to more compressed mode',
+  MULTIPLE_SYMBOLS: 'Reading multiple symbols, smart_read can batch them',
+  
+  // smart_search reasons
+  MULTIPLE_FILES: 'Query spans 50+ files, smart_search ranks by relevance',
+  INTENT_AWARE: 'Intent-aware search prioritizes relevant results (debug/implementation/tests)',
+  INDEX_BOOST: 'Symbol index available, boosting relevant matches',
+  PATTERN_SEARCH: 'Complex pattern search, smart_search handles regex efficiently',
+  
+  // smart_context reasons
+  TASK_CONTEXT: 'Building complete context for task, smart_context orchestrates multiple reads',
+  RELATED_FILES: 'Need related files (callers, tests, types), smart_context finds them',
+  ONE_CALL: 'Single call to get all context, more efficient than multiple reads',
+  DIFF_ANALYSIS: 'Analyzing git diff, smart_context expands changed symbols',
+  
+  // smart_shell reasons
+  COMMAND_OUTPUT: 'Command output needs compression (git log, npm test, etc.)',
+  RELEVANT_LINES: 'Extracting relevant lines from command output',
+  SAFE_EXECUTION: 'Using allowlist-validated command execution',
+  
+  // smart_summary reasons
+  CHECKPOINT: 'Saving task checkpoint for session recovery',
+  RESUME: 'Recovering previous task context',
+  PERSISTENCE: 'Maintaining task state across agent restarts',
+  
+  // Native tool reasons
+  SIMPLE_TASK: 'Task is simple, native tool is more direct',
+  ALREADY_CACHED: 'Content already in context, no need for compression',
+  SINGLE_LINE: 'Reading single line, native Read is sufficient',
+  SMALL_FILE: 'File is small (<100 lines), compression not needed',
+  NO_INDEX: 'No symbol index available, native search is equivalent',
+};
+
+/**
+ * Common expected benefits (for consistency)
+ */
+export const EXPECTED_BENEFITS = {
+  TOKEN_SAVINGS: (tokens) => `~${formatTokens(tokens)} saved`,
+  FASTER_RESPONSE: 'Faster response due to less data to process',
+  BETTER_RANKING: 'Better result ranking, relevant items first',
+  COMPLETE_CONTEXT: 'Complete context in single call',
+  SESSION_RECOVERY: 'Can recover task state if agent restarts',
+  FOCUSED_RESULTS: 'Focused on relevant code only',
+};
+
+/**
+ * Format token count for display
+ */
+const formatTokens = (tokens) => {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M tokens`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K tokens`;
+  }
+  return `${tokens} tokens`;
+};

package/src/missed-opportunities.js

@@ -0,0 +1,255 @@
+/**
+ * Missed opportunities detector - identifies when devctx should have been used but wasn't
+ * 
+ * Analyzes session metrics to detect patterns where devctx would have helped.
+ * 
+ * Enable with environment variable: DEVCTX_DETECT_MISSED=true
+ * 
+ * Detection heuristics (based on session metrics):
+ * - Low devctx adoption in complex sessions (many operations, few devctx calls)
+ * - Sessions with 0 devctx usage but high operation count
+ * - Inferred complexity vs actual devctx usage
+ * 
+ * Note: We can't intercept native tool calls in real-time, so we analyze
+ * patterns from metrics after the fact.
+ */
+
+const sessionActivity = {
+  devctxOperations: 0,
+  totalOperations: 0, // Estimated from devctx calls + time-based heuristic
+  lastDevctxCall: 0,
+  sessionStart: Date.now(),
+  enabled: false,
+  warnings: [],
+};
+
+const DEVCTX_TOOLS = new Set([
+  'smart_read',
+  'smart_search',
+  'smart_context',
+  'smart_shell',
+  'smart_summary',
+  'smart_turn',
+  'smart_read_batch',
+  'build_index',
+]);
+
+/**
+ * Check if missed opportunity detection is enabled
+ */
+export const isMissedDetectionEnabled = () => {
+  const envValue = process.env.DEVCTX_DETECT_MISSED?.toLowerCase();
+  const enabled = envValue === 'true' || envValue === '1' || envValue === 'yes';
+  sessionActivity.enabled = enabled;
+  return enabled;
+};
+
+/**
+ * Record devctx tool usage
+ */
+export const recordDevctxOperation = () => {
+  if (!isMissedDetectionEnabled()) return;
+  
+  sessionActivity.devctxOperations += 1;
+  sessionActivity.totalOperations += 1;
+  sessionActivity.lastDevctxCall = Date.now();
+};
+
+/**
+ * Estimate total operations based on time and activity
+ * Heuristic: If no devctx calls for >2 minutes, likely agent is using native tools
+ */
+const estimateTotalOperations = () => {
+  const now = Date.now();
+  const sessionDuration = now - sessionActivity.sessionStart;
+  const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
+  
+  // If session is active (recent devctx calls), estimate conservatively
+  if (timeSinceLastDevctx < 2 * 60 * 1000) {
+    return sessionActivity.totalOperations;
+  }
+  
+  // If long gap without devctx, estimate agent is using native tools
+  // Heuristic: ~1 operation per 10 seconds of activity
+  const estimatedNativeOps = Math.floor(timeSinceLastDevctx / 10000);
+  return sessionActivity.totalOperations + estimatedNativeOps;
+};
+
+/**
+ * Analyze session and detect missed opportunities
+ */
+export const analyzeMissedOpportunities = () => {
+  if (!isMissedDetectionEnabled()) return null;
+  
+  const now = Date.now();
+  const sessionDuration = now - sessionActivity.sessionStart;
+  const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
+  const estimatedTotal = estimateTotalOperations();
+  
+  const opportunities = [];
+  
+  // Detection 1: Long session with no devctx usage
+  if (sessionDuration > 5 * 60 * 1000 && sessionActivity.devctxOperations === 0) {
+    opportunities.push({
+      type: 'no_devctx_usage',
+      severity: 'high',
+      reason: 'Session active for >5 minutes with 0 devctx calls. Agent may not be using devctx.',
+      suggestion: 'Use forcing prompt or check if MCP is active',
+      estimatedSavings: estimatedTotal * 10000, // Estimate ~10K tokens per operation
+    });
+  }
+  
+  // Detection 2: Low devctx adoption in active session
+  const devctxRatio = estimatedTotal > 0 ? sessionActivity.devctxOperations / estimatedTotal : 0;
+  if (estimatedTotal >= 10 && devctxRatio < 0.3) {
+    opportunities.push({
+      type: 'low_devctx_adoption',
+      severity: 'medium',
+      reason: `Low devctx adoption: ${sessionActivity.devctxOperations}/${estimatedTotal} operations (${Math.round(devctxRatio * 100)}%). Target: >50%.`,
+      suggestion: 'Agent may be using native tools. Consider forcing prompt.',
+      estimatedSavings: (estimatedTotal - sessionActivity.devctxOperations) * 8000,
+    });
+  }
+  
+  // Detection 3: Long gap without devctx (agent switched to native tools)
+  if (sessionActivity.devctxOperations > 0 && timeSinceLastDevctx > 3 * 60 * 1000) {
+    const minutesSince = Math.round(timeSinceLastDevctx / 60000);
+    opportunities.push({
+      type: 'devctx_usage_dropped',
+      severity: 'medium',
+      reason: `No devctx calls for ${minutesSince} minutes. Agent may have switched to native tools.`,
+      suggestion: 'Re-apply forcing prompt if task is still complex',
+      estimatedSavings: Math.floor(timeSinceLastDevctx / 10000) * 5000,
+    });
+  }
+  
+  // Detection 4: Session too short to analyze
+  if (sessionDuration < 60 * 1000 && opportunities.length === 0) {
+    return {
+      opportunities: [],
+      message: 'Session too short to analyze (<1 minute)',
+      devctxOperations: sessionActivity.devctxOperations,
+      estimatedTotal,
+    };
+  }
+  
+  return {
+    opportunities,
+    devctxOperations: sessionActivity.devctxOperations,
+    estimatedTotal,
+    devctxRatio: Math.round(devctxRatio * 100),
+    sessionDuration: Math.round(sessionDuration / 1000),
+    totalEstimatedSavings: opportunities.reduce((sum, opp) => sum + (opp.estimatedSavings || 0), 0),
+  };
+};
+
+/**
+ * Format missed opportunities as markdown
+ */
+export const formatMissedOpportunities = () => {
+  if (!isMissedDetectionEnabled()) return '';
+  
+  const analysis = analyzeMissedOpportunities();
+  if (!analysis) return '';
+  
+  // Don't show if session is too short or no opportunities
+  if (analysis.message || analysis.opportunities.length === 0) {
+    return '';
+  }
+  
+  const lines = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('⚠️ **Missed devctx opportunities detected:**');
+  lines.push('');
+  
+  // Show session stats
+  lines.push(`**Session stats:**`);
+  lines.push(`- Duration: ${analysis.sessionDuration}s`);
+  lines.push(`- devctx operations: ${analysis.devctxOperations}`);
+  lines.push(`- Estimated total operations: ${analysis.estimatedTotal}`);
+  lines.push(`- devctx adoption: ${analysis.devctxRatio}%`);
+  lines.push('');
+  
+  for (const opp of analysis.opportunities) {
+    const severityIcon = opp.severity === 'high' ? '🔴' : '🟡';
+    lines.push(`${severityIcon} **${opp.type.replace(/_/g, ' ')}**`);
+    lines.push(`- **Issue:** ${opp.reason}`);
+    lines.push(`- **Suggestion:** ${opp.suggestion}`);
+    
+    if (opp.estimatedSavings) {
+      lines.push(`- **Potential savings:** ~${formatTokens(opp.estimatedSavings)}`);
+    }
+    
+    lines.push('');
+  }
+  
+  if (analysis.totalEstimatedSavings > 0) {
+    lines.push(`**Total potential savings:** ~${formatTokens(analysis.totalEstimatedSavings)}`);
+    lines.push('');
+  }
+  
+  lines.push('**How to fix:**');
+  lines.push('1. Use forcing prompt: `Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)`');
+  lines.push('2. Check if index is built: `ls .devctx/index.json`');
+  lines.push('3. Verify MCP is active in Cursor settings');
+  lines.push('');
+  lines.push('*To disable: `export DEVCTX_DETECT_MISSED=false`*');
+  
+  return lines.join('\n');
+};
+
+/**
+ * Get session activity summary
+ */
+export const getSessionActivity = () => {
+  return {
+    devctxOperations: sessionActivity.devctxOperations,
+    totalOperations: sessionActivity.totalOperations,
+    estimatedTotal: estimateTotalOperations(),
+    sessionDuration: Date.now() - sessionActivity.sessionStart,
+    timeSinceLastDevctx: Date.now() - sessionActivity.lastDevctxCall,
+  };
+};
+
+/**
+ * Reset session activity (for testing or manual reset)
+ */
+export const resetSessionActivity = () => {
+  sessionActivity.devctxOperations = 0;
+  sessionActivity.totalOperations = 0;
+  sessionActivity.lastDevctxCall = 0;
+  sessionActivity.sessionStart = Date.now();
+  sessionActivity.warnings = [];
+};
+
+/**
+ * Testing helpers - expose internal state for test scenarios
+ */
+export const __testing__ = {
+  setSessionStart: (timestamp) => {
+    sessionActivity.sessionStart = timestamp;
+  },
+  setLastDevctxCall: (timestamp) => {
+    sessionActivity.lastDevctxCall = timestamp;
+  },
+  setTotalOperations: (count) => {
+    sessionActivity.totalOperations = count;
+  },
+  getSessionActivity: () => sessionActivity,
+};
+
+/**
+ * Format token count for display
+ */
+const formatTokens = (tokens) => {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M tokens`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K tokens`;
+  }
+  return `${tokens} tokens`;
+};
+

package/src/server.js

@@ -49,6 +49,72 @@ export const createDevctxServer = () => {
   // Enable streaming progress notifications
   setServerForStreaming(server);
 
+  // Register prompts
+  server.prompt(
+    'use-devctx',
+    'Force the agent to use devctx tools for the current task. Use this prompt at the start of your message to ensure devctx is used instead of native tools.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)',
+          },
+        },
+      ],
+    })
+  );
+
+  server.prompt(
+    'devctx-workflow',
+    'Complete devctx workflow template with all recommended steps. Includes session start, context building, file reading, and session end.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Follow this devctx workflow:
+
+1. smart_turn(start) - Start session and recover previous context
+2. smart_context(task) - Build complete context for the task
+3. smart_search(query) - Search for specific patterns if needed
+4. smart_read(file) - Read files with appropriate mode (outline/signatures/symbol)
+5. smart_turn(end) - Save checkpoint for next session
+
+Use devctx tools instead of native Read/Grep/Shell when possible.`,
+          },
+        },
+      ],
+    })
+  );
+
+  server.prompt(
+    'devctx-preflight',
+    'Preflight checklist before starting work. Ensures index is built and session is initialized.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Preflight checklist:
+
+1. build_index(incremental=true) - Build/update symbol index
+2. smart_turn(start) - Initialize session and recover context
+3. Proceed with your task using devctx tools
+
+This ensures optimal performance and context recovery.`,
+          },
+        },
+      ],
+    })
+  );
+
   server.tool(
     'smart_read',
     'Read a file with token-efficient modes. outline/signatures: compact structure (~90% savings). range: specific line range with line numbers. symbol: extract function/class/method by name (string or array for batch). full: file content capped at 12k chars. maxTokens: token budget — auto-selects the most detailed mode that fits (full -> outline -> signatures -> truncated). context=true (symbol mode only): includes callers, tests, and referenced types from the dependency graph; returns graphCoverage (imports/tests: full|partial|none) so the agent knows how reliable the cross-file context is. Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',

package/src/tools/smart-context.js

@@ -11,6 +11,9 @@ import { resolveSafePath } from '../utils/fs.js';
 import { countTokens } from '../tokenCounter.js';
 import { persistMetrics } from '../metrics.js';
 import { predictContextFiles, recordContextAccess } from '../context-patterns.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 import { 
   getDetailedDiff, 
   analyzeChangeImpact, 
@@ -1219,15 +1222,44 @@ export const smartContext = async ({
   const contentItems = context.filter((item) => typeof item.content === 'string' && item.content.length > 0).length;
   const primaryItem = context.find((item) => item.role === 'primary');
 
+  const savedTokens = Math.max(0, totalRawTokens - totalCompressedTokens);
+  
   await persistMetrics({
     tool: 'smart_context',
     target: `${root} :: ${task}`,
     rawTokens: totalRawTokens,
     compressedTokens: totalCompressedTokens,
-    savedTokens: Math.max(0, totalRawTokens - totalCompressedTokens),
+    savedTokens,
     savingsPct,
     timestamp: new Date().toISOString(),
   });
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_context',
+    savedTokens,
+    target: task,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  let reason = DECISION_REASONS.TASK_CONTEXT;
+  if (diff) {
+    reason = DECISION_REASONS.DIFF_ANALYSIS;
+  } else if (context.some(c => c.role === 'caller' || c.role === 'test')) {
+    reason = DECISION_REASONS.RELATED_FILES;
+  }
+  
+  recordDecision({
+    tool: 'smart_context',
+    action: `build context for "${task}"`,
+    reason,
+    alternative: 'Multiple smart_read + smart_search calls',
+    expectedBenefit: `${EXPECTED_BENEFITS.TOKEN_SAVINGS(savedTokens)}, ${EXPECTED_BENEFITS.COMPLETE_CONTEXT}`,
+    context: `${context.length} files, ${totalCompressedTokens} tokens (${savingsPct}% compression)`,
+  });
 
   if (prefetch && context.length > 0) {
     try {

package/src/tools/smart-read.js

@@ -9,6 +9,9 @@ import { isDockerfile, readTextFile } from '../utils/fs.js';
 import { projectRoot } from '../utils/paths.js';
 import { truncate } from '../utils/text.js';
 import { countTokens } from '../tokenCounter.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCb);
 import { summarizeGo, summarizeRust, summarizeJava, summarizeShell, summarizeTerraform, summarizeDockerfile, summarizeSql, extractGoSymbol, extractRustSymbol, extractJavaSymbol, summarizeCsharp, extractCsharpSymbol, summarizeKotlin, extractKotlinSymbol, summarizePhp, extractPhpSymbol, summarizeSwift, extractSwiftSymbol } from './smart-read/additional-languages.js';
@@ -453,6 +456,38 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_read',
+    savedTokens: metrics.savedTokens,
+    target: path.relative(projectRoot, fullPath),
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  const lineCount = content.split('\n').length;
+  let reason = DECISION_REASONS.LARGE_FILE;
+  let expectedBenefit = EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens);
+  
+  if (mode === 'symbol') {
+    reason = DECISION_REASONS.SYMBOL_EXTRACTION;
+  } else if (validBudget && effectiveMode !== mode) {
+    reason = DECISION_REASONS.TOKEN_BUDGET;
+  } else if (lineCount < 100) {
+    reason = `File is small (${lineCount} lines), but using ${effectiveMode} mode for consistency`;
+  }
+  
+  recordDecision({
+    tool: 'smart_read',
+    action: `read ${path.relative(projectRoot, fullPath)} (${effectiveMode} mode)`,
+    reason,
+    alternative: 'Read (full file)',
+    expectedBenefit,
+    context: `${lineCount} lines, ${metrics.rawTokens} tokens → ${metrics.compressedTokens} tokens`,
+  });
 
   const confidence = { parser, truncated, cached: cacheHit && !contextResult };
   if (contextResult) confidence.graphCoverage = contextResult.graphCoverage;

package/src/tools/smart-search.js

@@ -8,6 +8,9 @@ import { loadIndex, queryIndex, queryRelated } from '../index.js';
 import { projectRoot } from '../utils/paths.js';
 import { isBinaryBuffer, isDockerfile, resolveSafePath } from '../utils/fs.js';
 import { truncate } from '../utils/text.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCallback);
 const supportedGlobs = [
@@ -381,6 +384,34 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_search',
+    savedTokens: metrics.savedTokens,
+    target: query,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  let reason = DECISION_REASONS.MULTIPLE_FILES;
+  if (validIntent) {
+    reason = DECISION_REASONS.INTENT_AWARE;
+  }
+  if (indexHits && indexHits.size > 0) {
+    reason = DECISION_REASONS.INDEX_BOOST;
+  }
+  
+  recordDecision({
+    tool: 'smart_search',
+    action: `search "${query}"${validIntent ? ` (intent: ${validIntent})` : ''}`,
+    reason,
+    alternative: 'Grep (unranked results)',
+    expectedBenefit: `${EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens)}, ${EXPECTED_BENEFITS.BETTER_RANKING}`,
+    context: `${dedupedMatches.length} matches in ${groups.length} files, ranked by relevance`,
+  });
 
   let retrievalConfidence = 'high';
   if (provenance) {

package/src/tools/smart-shell.js

@@ -4,6 +4,9 @@ import { rgPath } from '@vscode/ripgrep';
 import { buildMetrics, persistMetrics } from '../metrics.js';
 import { projectRoot } from '../utils/paths.js';
 import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
@@ -221,6 +224,32 @@ export const smartShell = async ({ command }) => {
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_shell',
+    savedTokens: metrics.savedTokens,
+    target: command,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  const outputLines = rawText.split('\n').length;
+  let reason = DECISION_REASONS.COMMAND_OUTPUT;
+  if (shouldPrioritizeRelevant && relevant) {
+    reason = DECISION_REASONS.RELEVANT_LINES;
+  }
+  
+  recordDecision({
+    tool: 'smart_shell',
+    action: `execute "${command}"`,
+    reason,
+    alternative: 'Shell (uncompressed output)',
+    expectedBenefit: EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens),
+    context: `${outputLines} lines → ${compressedText.split('\n').length} lines (relevant only)`,
+  });
 
   const result = {
     command,

package/src/tools/smart-summary.js

@@ -1,6 +1,9 @@
 import { countTokens } from '../tokenCounter.js';
 import { persistMetrics } from '../metrics.js';
 import { enforceRepoSafety, getRepoSafety } from '../repo-safety.js';
+import { recordToolUsage } from '../usage-feedback.js';
+import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
+import { recordDevctxOperation } from '../missed-opportunities.js';
 import {
   ACTIVE_SESSION_SCOPE,
   SQLITE_SCHEMA_VERSION,
@@ -1212,6 +1215,23 @@ export const smartSummary = async ({
           ...summaryMetrics,
           latencyMs: Date.now() - startTime,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: summaryMetrics.savedTokens || 0,
+          target: targetSessionId,
+        });
+        
+        recordDevctxOperation();
+        
+        recordDecision({
+          tool: 'smart_summary',
+          action: `get checkpoint "${targetSessionId}"`,
+          reason: DECISION_REASONS.RESUME,
+          alternative: 'Start from scratch (lose context)',
+          expectedBenefit: EXPECTED_BENEFITS.SESSION_RECOVERY,
+          context: `Recovered ${compressed.goal ? 'goal' : 'state'}, ${compressed.status || 'unknown'} status`,
+        });
       }
 
       return addRepoSafety({
@@ -1356,14 +1376,21 @@ export const smartSummary = async ({
         const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(currentSession, maxTokens);
         const rawTokens = countTokens(JSON.stringify(currentSession));
 
+        const metrics = buildSummaryMetrics(rawTokens, tokens);
         persistMetrics({
           tool: 'smart_summary',
           action,
           sessionId: targetSessionId,
-          ...buildSummaryMetrics(rawTokens, tokens),
+          ...metrics,
           latencyMs: Date.now() - startTime,
           skipped: true,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: metrics.savedTokens || 0,
+          target: targetSessionId,
+        });
 
         return addRepoSafety({
           action,
@@ -1386,15 +1413,24 @@ export const smartSummary = async ({
         const { compressed, tokens, truncated, omitted, compressionLevel } = compressSummary(currentSession, maxTokens);
         const rawTokens = countTokens(JSON.stringify(currentSession));
 
+        const metrics2 = buildSummaryMetrics(rawTokens, tokens);
         persistMetrics({
           tool: 'smart_summary',
           action,
           sessionId: targetSessionId,
-          ...buildSummaryMetrics(rawTokens, tokens),
+          ...metrics2,
           latencyMs: Date.now() - startTime,
           skipped: true,
           checkpointEvent: checkpointDecision.event,
         });
+        
+        recordToolUsage({
+          tool: 'smart_summary',
+          savedTokens: metrics2.savedTokens || 0,
+          target: targetSessionId,
+        });
+        
+        recordDevctxOperation();
 
         return addRepoSafety({
           action,
@@ -1455,6 +1491,14 @@ export const smartSummary = async ({
         latencyMs: Date.now() - startTime,
         ...(action === 'checkpoint' ? { checkpointEvent: checkpointDecision.event } : {}),
       });
+      
+      recordToolUsage({
+        tool: 'smart_summary',
+        savedTokens: summaryMetrics.savedTokens || 0,
+        target: targetSessionId,
+      });
+      
+      recordDevctxOperation();
 
       return addRepoSafety({
         action,

package/src/usage-feedback.js

@@ -0,0 +1,179 @@
+/**
+ * Usage feedback system - tracks devctx tool usage in current session
+ * and provides visible feedback to users about what tools were used and tokens saved.
+ * 
+ * Enable with environment variable: DEVCTX_SHOW_USAGE=true
+ * 
+ * Auto-enabled for first 10 tool calls (onboarding mode), then auto-disables.
+ * User can explicitly enable/disable at any time.
+ */
+
+const sessionUsage = {
+  tools: new Map(), // toolName -> { count, savedTokens }
+  totalSavedTokens: 0,
+  enabled: false,
+  totalToolCalls: 0,
+  onboardingMode: true,
+  ONBOARDING_THRESHOLD: 10, // Auto-disable after 10 tool calls
+};
+
+/**
+ * Check if usage feedback is enabled
+ * 
+ * Priority:
+ * 1. Explicit env var (DEVCTX_SHOW_USAGE=true/false)
+ * 2. Onboarding mode (first 10 tool calls)
+ * 3. Default: disabled
+ */
+export const isFeedbackEnabled = () => {
+  const envValue = process.env.DEVCTX_SHOW_USAGE?.toLowerCase();
+  
+  // Explicit enable
+  if (envValue === 'true' || envValue === '1' || envValue === 'yes') {
+    sessionUsage.enabled = true;
+    sessionUsage.onboardingMode = false;
+    return true;
+  }
+  
+  // Explicit disable
+  if (envValue === 'false' || envValue === '0' || envValue === 'no') {
+    sessionUsage.enabled = false;
+    sessionUsage.onboardingMode = false;
+    return false;
+  }
+  
+  // Onboarding mode: auto-enable for first N tool calls
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls < sessionUsage.ONBOARDING_THRESHOLD) {
+    sessionUsage.enabled = true;
+    return true;
+  }
+  
+  // After onboarding threshold, auto-disable
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls >= sessionUsage.ONBOARDING_THRESHOLD) {
+    sessionUsage.enabled = false;
+    sessionUsage.onboardingMode = false;
+  }
+  
+  return sessionUsage.enabled;
+};
+
+/**
+ * Record tool usage for feedback
+ */
+export const recordToolUsage = ({ tool, savedTokens = 0, target = null }) => {
+  // Increment total tool calls (for onboarding mode)
+  sessionUsage.totalToolCalls += 1;
+  
+  if (!isFeedbackEnabled()) return;
+  
+  const current = sessionUsage.tools.get(tool) || { count: 0, savedTokens: 0, targets: [] };
+  current.count += 1;
+  current.savedTokens += savedTokens;
+  if (target) current.targets.push(target);
+  
+  sessionUsage.tools.set(tool, current);
+  sessionUsage.totalSavedTokens += savedTokens;
+};
+
+/**
+ * Get current session usage stats
+ */
+export const getSessionUsage = () => {
+  return {
+    tools: Array.from(sessionUsage.tools.entries()).map(([tool, stats]) => ({
+      tool,
+      count: stats.count,
+      savedTokens: stats.savedTokens,
+      targets: stats.targets.slice(-3), // Last 3 targets only
+    })),
+    totalSavedTokens: sessionUsage.totalSavedTokens,
+  };
+};
+
+/**
+ * Format usage feedback as markdown
+ */
+export const formatUsageFeedback = () => {
+  if (!isFeedbackEnabled()) return '';
+  
+  const usage = getSessionUsage();
+  if (usage.tools.length === 0) return '';
+  
+  const lines = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('📊 **devctx usage this session:**');
+  
+  // Sort by count descending
+  const sorted = usage.tools.sort((a, b) => b.count - a.count);
+  
+  for (const { tool, count, savedTokens, targets } of sorted) {
+    const countStr = count === 1 ? '1 call' : `${count} calls`;
+    const tokensStr = savedTokens > 0 ? ` | ~${formatTokens(savedTokens)} saved` : '';
+    
+    if (targets.length > 0) {
+      const targetsPreview = targets.length === 1 
+        ? ` (${truncateTarget(targets[0])})`
+        : ` (${targets.length} files)`;
+      lines.push(`- **${tool}**: ${countStr}${tokensStr}${targetsPreview}`);
+    } else {
+      lines.push(`- **${tool}**: ${countStr}${tokensStr}`);
+    }
+  }
+  
+  if (usage.totalSavedTokens > 0) {
+    lines.push('');
+    lines.push(`**Total saved:** ~${formatTokens(usage.totalSavedTokens)}`);
+  }
+  
+  lines.push('');
+  
+  // Show onboarding message if in onboarding mode
+  if (sessionUsage.onboardingMode && sessionUsage.totalToolCalls < sessionUsage.ONBOARDING_THRESHOLD) {
+    const remaining = sessionUsage.ONBOARDING_THRESHOLD - sessionUsage.totalToolCalls;
+    lines.push(`*Onboarding mode: showing for ${remaining} more tool calls. To keep: \`export DEVCTX_SHOW_USAGE=true\`*`);
+  } else {
+    lines.push('*To disable this message: `export DEVCTX_SHOW_USAGE=false`*');
+  }
+  
+  return lines.join('\n');
+};
+
+/**
+ * Reset session usage (for testing or manual reset)
+ */
+export const resetSessionUsage = () => {
+  sessionUsage.tools.clear();
+  sessionUsage.totalSavedTokens = 0;
+  sessionUsage.totalToolCalls = 0;
+  sessionUsage.onboardingMode = true;
+};
+
+/**
+ * Format token count for display
+ */
+const formatTokens = (tokens) => {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M tokens`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K tokens`;
+  }
+  return `${tokens} tokens`;
+};
+
+/**
+ * Truncate target path for display
+ */
+const truncateTarget = (target) => {
+  if (!target) return '';
+  if (target.length <= 40) return target;
+  
+  // Try to show filename
+  const parts = target.split('/');
+  const filename = parts[parts.length - 1];
+  if (filename.length <= 40) return `.../${filename}`;
+  
+  return target.slice(0, 37) + '...';
+};