{
  "markdown": "# smart-context-mcp\n\nMCP server that reduces AI agent token usage by up to 90% through intelligent context compression (measured on this project).\n\n[![npm version](https://img.shields.io/npm/v/smart-context-mcp.svg)](https://www.npmjs.com/package/smart-context-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## What it is\n\nAn MCP (Model Context Protocol) server that provides specialized tools for reading, searching, and managing code context efficiently. Instead of loading full files or returning massive search results, it compresses information while preserving what matters for the task.\n\n**Real metrics from production use:**\n- ~7M tokens → ~800K tokens (approximately 89% reduction)\n- 1,500+ operations tracked across development\n- Compression ratios: 3x to 46x depending on tool\n- Context overhead is tracked separately so reports can show gross and net savings\n\n**Workflow-level savings:**\n- Debugging: ~85-90% token reduction\n- Code Review: ~85-90% token reduction\n- Refactoring: ~85-90% token reduction\n- Testing: ~85-90% token reduction\n- Architecture: ~85-90% token reduction\n\n**Real adoption in non-trivial tasks:**\n- Approximately 70-75% of complex tasks use devctx tools\n- Most used: `smart_read` (850+ uses), `smart_search` (280+ uses), `smart_shell` (220+ uses)\n- Primary reasons for non-usage: task too simple, no index built, native tools preferred\n\nSee [Workflow Metrics](./docs/workflow-metrics.md) and [Adoption Metrics](./docs/adoption-metrics-design.md) for details.\n\n## Latest Release: `1.20.0`\n\nMinor release. Same 20 tools, but several gain new parameters and response fields. SQLite schema bumps 7 → 8 (new `read_cache` table; auto-migrates on first run). Global memory DB schema bumps 1 → 2 (new `noise_hints` table). **Zero new runtime dependencies.**\n\n- **Shared `tokenBudget` across tools.** `smart_read`, `smart_read_batch`, `smart_context`, `smart_turn` (`start` + `end`) and `smart_resume` now accept `tokenBudget: number | { id?, maxTokens, shared? }`. When `shared:true` (or `id` set), the budget is reused across calls inside the same task — so a multi-step agent flow can stay under a hard token ceiling without per-call bookkeeping. Responses include `taskBudget`, `remainingBudget`, and `budgetDetails` (`scope`, `actions`, degraded mode) when the budget actually changed the output.\n- **`smart_search` search modes.** New `mode: 'needle' | 'balanced' | 'semantic'` (default `balanced`). `needle` = literal exact only (no regex / no term expansion) — kills noise on debug queries. `balanced` = exact + regex + term expansion. `semantic` = exact-first plus the local semantic block only when exact signal is weak. The previous `semantic: true` flag remains as a legacy alias for `mode: 'semantic'`. Default `maxFiles` tightened 15 → 5. New `maxTokens` caps the whole response and compacts intelligently (matches first, then diagnostics, then semantic block). Per-file ranking is now inspectable via `matchedBy`, `boostSource`, `scoreBreakdown`, `whyRanked`. Response also returns `hasMore` / `totalFiles` / `nextSuggestedMaxFiles` and actionable `suggestions` when the query is too broad or empty.\n- **`smart_read` persistent cache + budget-aware `full` degradation.** New SQLite `read_cache` table keyed by `(filePath, mode, selector, content_hash)`. Second read of an unchanged file is virtually free. Mode `full` is now an **explicit last resort**: if a `tokenBudget`/`maxTokens` is set, it degrades to lighter modes first (outline → signatures → truncated) and reports the real mode used in `fullMode` + `budgetDetails`. New `clearReadCachePersistent` + GC integration in `runStorageMaintenance`.\n- **`smart_turn` simple-task skip heuristic.** When the prompt is short (≤ 40 chars after normalization), classified as a simple task, and no session/task is pinned, `smart_turn(start)` now returns `skipSmartTurn: true` with `recommendedPath.mode='simple_task_skip'` instead of paying the full orchestration cost. Saves continuity-resolution overhead on trivial prompts. `minimal` verbosity additionally compacts summary/refreshedContext to the fields agents actually consume.\n- **`global_memory` noise hints.** Per-project, scrubbed noise telemetry persisted to `~/.devctx/global.db` (`noise_hints` table). New actions `noise_stats` and `noise_reset` (full or via `query`). Lets `smart_search` learn which queries the agent already discovered to be noisy in a given repo and adjust ranking, without ever leaking content.\n- **KPI baseline infrastructure.** New scripts `evals/kpi-baseline.js` + `evals/kpi-utils.js` aggregate `harness.js` and `realworld-eval.js` runs into a single JSON snapshot with **top-5 precision, recall, reread task/call rate, and per-task-size buckets (short / long)**. Persists `kpi-baseline-latest.json` for regression detection across releases. New test suite `tests/eval-kpis.test.js`.\n\n### Highlights from `1.19.0` (still current)\n\nFive-step quality jump executed as sequential commits with full dogfooding. MCP grows from **18 → 20 tools**, +68 tests, **zero new dependencies**, suite green at 882/883 (1 skipped).\n\n- **`smart_playbook` (new tool).** Declarative composite workflows that run multiple `smart_*` tools in a single MCP call. Five built-in playbooks ship with the package: `preflight-merge` (review + affected tests + checkpoint), `debug-flake` (last failure + curated debug context + affected), `refactor-safe` (curated context + affected + checkpoint), `doc-sync` (ADR search + docs context), `ramp-up` (status + doctor + ADR overview). Project-level overrides via `.devctx/playbooks/*.{yaml,json}` with `{{args.X}}` interpolation, `when` / `label` / `stopOnFail` / `dryRun`. Tool allowlist restricted to `smart_*`. Zero deps: built-in minimal YAML parser.\n- **Reactive FS watcher for the index.** `fs.watch` (native, recursive, debounced 600ms + batch flush every 2s) keeps the symbol index hot between calls. Filters `.git`, `node_modules`, `.devctx`, `dist`, `build`, lockfiles, `.min.*`, `.map`, `.snap`, and non-indexable extensions. Stats surface in `smart_status` (`enabled`, `flushes`, `eventsObserved`, `filesReindexed`, `filesRemoved`, `errors`, `lastFlushAt`, `pending`). Opt-out via `DEVCTX_WATCH_INDEX=false`. Wired to MCP shutdown for clean close + final flush.\n- **Richer Python / Go parsers + pluggable parser registry.** Python now captures decorators (`decorators: [\"dataclass\", ...]`), `async def` (kinds `async-function` / `async-method`), `TypeAlias` and `TypeVar` / `NewType` / `ParamSpec` / `TypeVarTuple` as `kind=\"type\"`, and respects class indent for accurate scope. Go now captures methods with receiver type as `parent`, interfaces as `kind=\"interface\"`, top-level `const` / `var`. `src/parsers/registry.js` exposes `registerParser` / `getParser` so future tree-sitter parsers can plug in without touching `index.js`. `INDEX_VERSION` bumped 6 → 7 (auto-reindex).\n- **Local semantic re-rank on `smart_search`.** Opt-in `semantic: true` (with `semanticLimit`) returns a `semantic: { embedder, symbols[], files[] }` block ranked by hashing/TF-IDF embeddings (256-dim, FNV-1a buckets, L2-normalized, cosine similarity, <5ms). Default behavior unchanged. Pluggable embedder interface (`id`, `dimensions`, `embed`, `similarity`) ready to swap in ONNX/transformers without touching callers.\n- **`global_memory` (new tool, opt-in).** Cross-project memory persisted to `~/.devctx/global.db` (override via `DEVCTX_GLOBAL_DB`, gated by `DEVCTX_GLOBAL_MEMORY=true`). Stores canonical decisions, recurring patterns, playbook drafts, and notes across repos. Content scrubbed for likely API keys / bearer tokens / JWT / PEM private keys / AWS / OpenAI / GitHub / Slack / Google API / DB URLs / emails / home paths before persistence. Project paths stored as FNV-1a hash, not raw path. Recall uses the local hashing/TF-IDF embedder for semantic ranking.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for the full v1.20.0 + v1.19.0 entries.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for full release history.\n\n## When to Use (and When Not To)\n\n**Use devctx when:**\n- You're exploring an unfamiliar codebase\n- The task spans multiple sessions (checkpoints save context)\n- You need to understand how files relate to each other (graph/imports)\n- The context is too large to manage manually\n- You're doing complex multi-file refactors or debugging across layers\n\n**Skip devctx when:**\n- You already know exactly which files to touch\n- It's a single-file or surgical change (2-3 edits max)\n- You have the full mental map from a recent exploration\n- Native tools (Grep, Read, StrReplace) are more direct for the task\n\n**Honest verdict from real users:**\n\n> \"The MCP shines in long, multi-session tasks or when you don't know the codebase. For contained refactors where you already know what to touch, native tools are just as fast or faster. The real value was `smart_read(outline)` for the initial analysis and checkpoints to not lose the thread between sessions.\"\n\nThe 90% token savings are real, but they require the right task type to materialize.\n\n---\n\n## Why it exists\n\nAI agents waste tokens in three ways:\n\n1. **Reading full files** when they only need structure or specific functions\n2. **Massive search results** with hundreds of irrelevant matches\n3. **Repeating context** across conversation turns\n\nThis MCP solves all three by providing tools that return compressed, ranked, and cached context.\n\n---\n\n## 🚨 Agent Ignored devctx? → Paste This Next\n\n<table>\n<tr>\n<td width=\"100%\" bgcolor=\"#FFF3CD\">\n\n### 📋 Official Prompt (Copy & Paste)\n\n```\nUse smart-context-mcp for this task.\nStart with smart_turn(start), then use smart_context or smart_search before reading full files.\nEnd with smart_turn(end) if you make progress.\n```\n\n### ⚡ Ultra-Short Version\n\n```\nUse devctx: smart_turn(start) → smart_context → smart_turn(end)\n```\n\n</td>\n</tr>\n</table>\n\n**When to use:** Agent read large files with `Read`, used `Grep` repeatedly, or you see no devctx tools in a complex task.\n\n**Why this happens:** Task seemed simple, no index built, native tools appeared more direct, or rules weren't strong enough.\n\n---\n\n## Quick Start: Which Client Should I Use?\n\n### 🎯 Best Default: Cursor\n\n**Use if:** You work in Cursor IDE and want the best balance of guidance and flexibility.\n\n**Workflow:**\n```\n1. Install MCP → rules auto-load\n2. Start task → agent reads .cursorrules\n3. Agent decides when to use devctx\n4. Use /prompt commands to force usage if needed\n```\n\n**Automaticity:** Medium by default. Medium-High if you use the assisted launcher `./.devctx/bin/cursor-devctx` for task-runner workflows.\n\n---\n\n### 🔄 Best Continuity: Claude Desktop\n\n**Use if:** You want highest session continuity with automatic context recovery.\n\n**Workflow:**\n```\n1. Install MCP + hooks\n2. Start task → hook auto-triggers smart_turn(start)\n3. Work with devctx tools\n4. End task → hook auto-triggers smart_turn(end)\n```\n\n**Automaticity:** High (with hooks) - Can auto-trigger `smart_turn` on session start/end.\n\n---\n\n### 💻 Best Terminal: Codex CLI / Qwen Code\n\n**Use if:** You prefer terminal-based workflows or scripting.\n\n**Workflow:**\n```\n1. Install MCP\n2. Rules embedded in prompts\n3. Agent reads rules, decides when to use\n4. Explicit instructions work best\n```\n\n**Automaticity:** Low-Medium - Rules are visible but require explicit prompting.\n\n---\n\n### 📊 Quick Comparison\n\n| Client | Automaticity | Best For |\n|--------|--------------|----------|\n| **Cursor** | Medium | Complex IDE tasks |\n| **Claude Desktop** | High (hooks) | Session continuity |\n| **Codex CLI** | Low-Medium | Terminal workflows |\n| **Qwen Code** | Low-Medium | Alternative to Cursor |\n\n**Important:** Agent always decides whether to use devctx. Rules increase probability, but don't guarantee it.\n\n**If you want a more repeatable path:** use the task runner or the assisted launcher instead of relying on rules alone. See [Task Runner Workflows](./docs/task-runner.md).\n\n**📖 Full setup:** [Client Compatibility](./docs/client-compatibility.md)\n\n---\n\n## 🚀 How to Invoke the MCP\n\n**Key point:** The MCP doesn't intercept prompts automatically. You need to tell the agent to use it.\n\n### 1️⃣ Use MCP Prompts (Easiest - Cursor only)\n\n```\n/prompt use-devctx\n\n[Your task here]\n```\n\n**Other prompts:**\n- `/prompt devctx-workflow` - Full workflow\n- `/prompt devctx-preflight` - Build index + start session\n\n### 2️⃣ Explicit Instruction (Any client)\n\n```\nUse smart_turn(start) to recover context, then [your task]\n```\n\nFor a more guided CLI path:\n\n```bash\nsmart-context-task task --prompt \"your task\"\nsmart-context-task implement --prompt \"your task\"\nsmart-context-task continue --session-id <session-id>\nsmart-context-task doctor\n```\n\n### 3️⃣ Automatic via Rules (Not guaranteed)\n\nAgent *should* use devctx for complex tasks if rules are active:\n- Cursor: `.cursorrules`\n- Claude Desktop: `CLAUDE.md`\n- Others: `AGENTS.md`\n\n**But:** Agent decides based on task complexity.\n\n### ⚡ Quick Reference\n\n| Scenario | Command |\n|----------|---------|\n| Start new task | `/prompt devctx-workflow` |\n| Guided terminal workflow | `smart-context-task task --prompt \"...\"` |\n| Guided implementation | `smart-context-task implement --prompt \"...\"` |\n| Continue previous task | `smart_turn(start) and continue` |\n| Continue via runner | `smart-context-task continue --session-id <id>` |\n| Force MCP usage | `/prompt use-devctx` |\n| First time in project | `/prompt devctx-preflight` |\n| Trust automatic rules | Just describe your task normally |\n\n---\n\n\n## Recommended Workflow\n\n### ✅ Setup Checklist (First Time in Project)\n\nBefore starting complex tasks, ensure:\n\n```bash\n# 1. MCP is installed\nnpm list -g smart-context-mcp  # or check your MCP client\n\n# 2. Build the index (IMPORTANT)\nnpm run build-index\n# or tell the agent: \"Run build_index tool\"\n\n# 3. Rules are active\n# - Cursor: .cursorrules exists\n# - Claude Desktop: CLAUDE.md exists\n# - Other clients: AGENTS.md exists\n\n# 4. Start with smart_turn\n# Tell the agent: \"Use smart_turn(start) to begin\"\n```\n\n**Copy-paste to agent (first time):**\n```\nRun build_index, then use smart_turn(start) to begin this task.\n```\n\n---\n\n### ⚠️ Why Index Matters\n\n**Without index:**\n- ❌ `smart_search` returns unranked results\n- ❌ `smart_context` can't build optimal context\n- ❌ Agent may prefer native tools → no savings\n\n**With index:**\n- ✅ `smart_search` ranks by relevance\n- ✅ `smart_context` includes related files\n- ✅ 90% token savings enabled\n\n**When to rebuild:**\n- ✅ First time in project\n- ✅ After major refactors (file moves, renames)\n- ✅ After adding many new files\n- ❌ Not needed every session (index persists in `.devctx/`)\n\n---\n\n### The Entry Point: `smart_turn(start)`\n\nFor **non-trivial tasks** (debugging, review, refactor, testing, architecture), the optimal flow is:\n\n```\n0. build_index (if first time in project)\n   ↓ enables search ranking and context quality\n   \n1. smart_turn(start, userPrompt, ensureSession=true)\n   ↓ recovers previous context, classifies task, checks repo safety\n   \n2. smart_context(...) or smart_search(intent=...)\n   ↓ builds context or finds relevant code\n   \n3. smart_read(mode=outline|signatures|symbol)\n   ↓ reads compressed, cascades to full only if needed\n   \n4. [work: make changes, analyze, review]\n   \n5. smart_shell('npm test')\n   ↓ verifies changes safely\n   \n6. smart_turn(end, event=milestone|blocker|task_complete)\n   ↓ checkpoints progress for recovery\n```\n\n**Why start with `smart_turn`?**\n- ✅ Recovers previous task checkpoint (goal, status, decisions)\n- ✅ Classifies task continuation vs new task\n- ✅ Provides repo safety check\n- ✅ Enables task recovery if interrupted\n- ✅ Tracks metrics for optimization\n\n**When to skip `smart_turn`:**\n- ❌ Trivial tasks (read single file, simple search)\n- ❌ One-off questions (no continuity needed)\n- ❌ Quick diagnostics (no session context)\n\n### The Product Entry Point: `smart-context-task`\n\nIf you want the same lifecycle packaged into named workflows, use the task runner:\n\n```bash\nsmart-context-task task --prompt \"inspect the auth flow and continue the bugfix\"\nsmart-context-task implement --prompt \"add a token guard to loginHandler\"\nsmart-context-task review --prompt \"review the latest diff\"\nsmart-context-task doctor\n```\n\nThis layer runs the same `smart_turn(start)` / context / checkpoint flow, but adds:\n\n- workflow-specific preflight (`smart_context` or `smart_search`)\n- continuity-aware prompt guidance\n- blocked-state routing to `smart_doctor`\n- measured `task_runner` quality signals\n\nFor the full command set and client-specific usage, see [Task Runner Workflows](./docs/task-runner.md).\n\n---\n\n## How it Works in Practice\n\n### The Reality\n\nThis MCP **does not intercept** your prompts magically. Here's what actually happens:\n\n1. **You write a prompt:** \"Fix the login bug\"\n2. **Agent reads rules:** Sees debugging workflow suggestion\n3. **Agent decides:** \"This is a debugging task, I'll start with `smart_turn(start)`\"\n4. **Agent calls:** `smart_turn({ phase: 'start', userPrompt: '...', ensureSession: true })`\n5. **MCP returns:** Previous task checkpoint (if exists) + repo safety check\n6. **Agent continues:** Calls `smart_search(intent=debug)` for error location\n7. **Agent reads:** Calls `smart_read(mode=symbol)` for specific function\n8. **Agent fixes bug:** Makes changes\n9. **Agent verifies:** Calls `smart_shell('npm test')`\n10. **Agent checkpoints:** Calls `smart_turn(end)` to persist progress\n\n**Key points:**\n- ✅ Agent **chooses** to use devctx tools (not forced)\n- ✅ Rules **guide** the agent (not enforce)\n- ✅ `smart_turn(start)` is **recommended entry point** for non-trivial tasks\n- ✅ Agent can skip workflow for trivial tasks\n- ✅ You control nothing directly—the agent decides\n\n### What You Get\n\n**Tools (20):** Efficient alternatives to built-in operations\n- `smart_read` / `smart_read_batch` - Compressed file reading (outline, signatures, symbol, explain)\n- `smart_search` - Intent-aware code search with ranking, ADR filtering, and opt-in semantic re-rank\n- `smart_context` - One-call context builder with graph + `paths: { from, to }` traversal\n- `smart_test` - Affected tests via graph + sandboxed runner + persisted `last_failure`\n- `smart_review` - Code review preflight: diff + callers + heuristic findings\n- `smart_playbook` - Declarative composite workflows (5 built-in: preflight-merge, debug-flake, refactor-safe, doc-sync, ramp-up)\n- `smart_shell` - Safe diagnostic commands (TAP/git-log/diff compression)\n- `smart_turn` / `smart_resume` - Session persistence + `nextActions[]` machine-readable plan\n- `smart_summary` / `smart_status` / `smart_doctor` / `smart_metrics` / `smart_edit`\n- `global_memory` - Opt-in cross-project memory in `~/.devctx/global.db` (scrubbed, semantic recall)\n- `build_index` / `warm_cache` / `git_blame` / `cross_project`\n\n**Rules (5 profiles):** Task-specific workflows\n- Debugging: Error-first, symbol-focused\n- Code Review: Diff-aware, API-focused\n- Refactoring: Graph-aware, test-verified\n- Testing: Coverage-aware, TDD-friendly\n- Architecture: Index-first, minimal-detail\n\n**Storage (`.devctx/`):** Local context database\n- `index.json` - Symbol index (functions, classes, imports, ADRs, sections) — `INDEX_VERSION 7`\n- `state.sqlite` - Sessions, metrics, patterns, task handoffs, test failures, explain cache (Node 22+, `node:sqlite`)\n- `metrics.jsonl` - Opt-in legacy file, only when `DEVCTX_METRICS_FILE=path.jsonl` is set\n- `~/.devctx/global.db` - Cross-project memory (opt-in via `DEVCTX_GLOBAL_MEMORY=true`)\n\n### Persistent Task Context (When Supported)\n\n**What gets persisted:**\n- Task checkpoints (goal, status, decisions, blockers)\n- File access patterns (for prediction)\n- Token metrics (for optimization)\n- Session summaries (~100 tokens compressed)\n\n**When it's consulted:**\n- Agent calls `smart_turn(start)` - Recovers task checkpoint\n- Agent calls `smart_context` - Uses patterns for prediction\n- Agent calls `smart_summary` - Gets task summary\n\n**What is NOT persisted:**\n- ❌ Full conversation transcript\n- ❌ Complete message history\n- ❌ Agent reasoning or thoughts\n- ❌ User prompts verbatim\n\n**Limitations:**\n- Only works if agent calls `smart_turn` (not automatic)\n- Only persists within project (`.devctx/` is local)\n- Only recovers if session ID matches (manual or auto)\n- Client must support MCP (Cursor, Codex, Claude Desktop, Qwen)\n\n**Honest truth:** Task context persistence is **opt-in** via agent behavior, not **automatic** via client interception.\n\n### What This Means for You\n\n**Best case scenario:**\n- Agent follows rules consistently\n- Uses devctx tools for 50-80% of operations\n- Token usage drops 85-90% (proven, measured)\n- Responses often faster due to less data to process (inferred from token savings)\n\n**Typical scenario:**\n- Agent uses devctx tools for complex tasks\n- Uses built-in tools for simple tasks\n- Token usage drops 60-80%\n- Noticeable improvement in efficiency\n\n**Worst case scenario:**\n- Agent ignores rules (rare but possible)\n- Uses built-in tools exclusively\n- Token usage unchanged\n- No harm done (MCP is passive)\n\n**You can check:** `npm run report:metrics` shows actual tool usage and measured `smart_turn` quality signals.\n\n### What \"Better Context\" Means\n\n**What we improve:**\n- ✅ Context relevance (right files for the task)\n- ✅ Signal-to-noise ratio (less boilerplate, more signal)\n- ✅ Context efficiency (more relevant info in less space)\n- ✅ Response speed (less data to process)\n\n**What we don't guarantee:**\n- ❌ Agent will always be correct\n- ❌ Responses will be perfect\n- ❌ Tasks will always succeed\n- ❌ Responses will be \"more accurate\" (accuracy depends on agent, not just context)\n\n**The benefit:** Agents work with better input, but output quality still depends on agent capability and task complexity.\n\n**Honest claim:** We provide **better context** (more relevant, less noise), which **can help** agents respond more efficiently in complex tasks when the workflow is followed. \n\n**What's proven:** 90% token savings (measured across 3,666 operations).  \n**What's inferred:** Quality improvement (better input → potentially better output, but not explicitly measured).  \n**What we don't control:** Agent correctness, task success, response accuracy.\n\n---\n\n## Workflow Examples\n\n### Debugging\n\n```javascript\n// 1. Start session\nsmart_turn({ \n  phase: 'start', \n  userPrompt: 'TypeError: Cannot read property \"user\" of undefined',\n  ensureSession: true \n})\n// → Recovers: \"Last worked on auth system, checked validateToken()\"\n\n// 2. Find error\nsmart_search({ \n  query: 'TypeError user undefined',\n  intent: 'debug'\n})\n// → Returns: src/auth.js (error handling), src/routes/login.js (recent change)\n\n// 3. Read structure\nsmart_read({ \n  filePath: 'src/routes/login.js',\n  mode: 'signatures'\n})\n// → Returns: loginHandler, validateCredentials, generateToken\n\n// 4. Extract failing function\nsmart_read({ \n  filePath: 'src/routes/login.js',\n  mode: 'symbol',\n  symbol: 'loginHandler'\n})\n// → Returns: Full function code (250 tokens vs 5K for full file)\n\n// 5. Reproduce error\nsmart_shell({ command: 'npm test -- login.test.js' })\n// → Returns: Test failure output\n\n// [Fix bug]\n\n// 6. Verify fix\nsmart_shell({ command: 'npm test -- login.test.js' })\n// → Returns: Tests pass\n\n// 7. Checkpoint\nsmart_turn({ \n  phase: 'end',\n  event: 'milestone',\n  summary: 'Fixed TypeError in loginHandler - null check added',\n  nextStep: 'Consider adding integration tests'\n})\n```\n\n**Token usage:** 150K → 15K (90% savings)\n\n---\n\n### Code Review\n\n```javascript\n// 1. Start session\nsmart_turn({ \n  phase: 'start',\n  userPrompt: 'Review PR #123 - Add JWT refresh token support',\n  ensureSession: true\n})\n\n// 2. Get changed files context\nsmart_context({ \n  diff: true,\n  detail: 'balanced'\n})\n// → Returns: Changed files with graph, prioritizes API surface\n\n// 3. Review API surface\nsmart_read({ \n  filePath: 'src/auth.js',\n  mode: 'signatures'\n})\n// → Returns: Exported functions only\n\n// 4. Check implementation\nsmart_read({ \n  filePath: 'src/auth.js',\n  mode: 'symbol',\n  symbol: 'refreshToken'\n})\n\n// 5. Check authorship\ngit_blame({ \n  mode: 'symbol',\n  filePath: 'src/auth.js'\n})\n// → Returns: Who wrote each function\n\n// 6. Verify tests\nsmart_shell({ command: 'npm test' })\n\n// 7. Checkpoint\nsmart_turn({ \n  phase: 'end',\n  event: 'milestone',\n  summary: 'PR #123 approved - JWT refresh implemented correctly',\n  nextStep: 'Monitor production metrics after deploy'\n})\n```\n\n**Token usage:** 200K → 25K (87% savings)\n\n---\n\n### Refactoring\n\n```javascript\n// 1. Start session\nsmart_turn({ \n  phase: 'start',\n  userPrompt: 'Extract authentication logic into separate service',\n  ensureSession: true\n})\n\n// 2. Build dependency graph\nsmart_context({ \n  entryFile: 'src/routes/login.js',\n  detail: 'balanced'\n})\n// → Returns: Dependencies, imports, exports\n\n// 3. Understand current structure\nsmart_read({ \n  filePath: 'src/routes/login.js',\n  mode: 'signatures'\n})\n\n// 4. Extract target function\nsmart_read({ \n  filePath: 'src/routes/login.js',\n  mode: 'symbol',\n  symbol: 'validateCredentials'\n})\n\n// 5. Check authorship\ngit_blame({ \n  mode: 'symbol',\n  filePath: 'src/routes/login.js'\n})\n\n// [Refactor: create src/services/auth.js, move logic]\n\n// 6. Verify tests still pass\nsmart_shell({ command: 'npm test' })\n\n// 7. Checkpoint\nsmart_turn({ \n  phase: 'end',\n  event: 'milestone',\n  summary: 'Extracted auth logic to AuthService - tests pass',\n  nextStep: 'Update other routes to use AuthService'\n})\n```\n\n**Token usage:** 180K → 20K (89% savings)\n\n---\n\n### Testing\n\n```javascript\n// 1. Start session\nsmart_turn({ \n  phase: 'start',\n  userPrompt: 'Write tests for validateToken function',\n  ensureSession: true\n})\n\n// 2. Find existing test patterns\nsmart_search({ \n  query: 'validateToken test',\n  intent: 'tests'\n})\n// → Returns: Existing test files, test patterns\n\n// 3. Read function to test\nsmart_read({ \n  filePath: 'src/auth.js',\n  mode: 'symbol',\n  symbol: 'validateToken'\n})\n\n// 4. Understand dependencies\nsmart_context({ \n  entryFile: 'src/auth.js',\n  detail: 'minimal'\n})\n// → Returns: Dependencies (jwt, bcrypt, db)\n\n// [Write test]\n\n// 5. Run tests\nsmart_shell({ command: 'npm test -- auth.test.js' })\n\n// 6. Checkpoint\nsmart_turn({ \n  phase: 'end',\n  event: 'milestone',\n  summary: 'Added 5 tests for validateToken - all pass',\n  nextStep: 'Add edge case tests for expired tokens'\n})\n```\n\n**Token usage:** 120K → 12K (90% savings)\n\n---\n\n### Architecture Exploration\n\n```javascript\n// 1. Start session\nsmart_turn({ \n  phase: 'start',\n  userPrompt: 'Understand how authentication works in this codebase',\n  ensureSession: true\n})\n\n// 2. Get high-level overview\nsmart_context({ \n  detail: 'minimal'\n})\n// → Returns: Project structure, key modules\n\n// 3. Find auth-related code\nsmart_search({ \n  query: 'authentication authorization',\n  intent: 'explore'\n})\n// → Returns: Ranked files by relevance\n\n// 4. Review API surface\nsmart_read({ \n  filePath: 'src/auth.js',\n  mode: 'signatures'\n})\n// → Returns: Exported functions only\n\n// 5. Check cross-project patterns (if monorepo)\ncross_project({ \n  mode: 'search',\n  query: 'AuthService'\n})\n// → Returns: Similar auth patterns in other projects\n\n// 6. Checkpoint\nsmart_turn({ \n  phase: 'end',\n  event: 'milestone',\n  summary: 'Auth uses JWT with 1h expiry, refresh tokens in Redis',\n  nextStep: 'Document auth flow in architecture.md'\n})\n```\n\n**Token usage:** 300K → 30K (90% savings)\n\n---\n\n## Core Tools\n\nThese are the essential tools you should understand first:\n\n### smart_read\n\nRead files in compressed modes instead of loading full content.\n\n```javascript\n// Outline mode: structure only (~90% savings)\n{ filePath: 'src/server.js', mode: 'outline' }\n\n// Signatures mode: exported API only\n{ filePath: 'src/api.js', mode: 'signatures' }\n\n// Symbol mode: extract specific function/class\n{ filePath: 'src/auth.js', mode: 'symbol', symbol: 'validateToken' }\n```\n\n**Modes:** `outline`, `signatures`, `symbol`, `range`, `full`\n\n**When to use:** Any time you need to understand file structure without reading everything.\n\n---\n\n### smart_search\n\nIntent-aware code search with ranked, deduplicated results and index boosting.\n\n```javascript\n// Find where a symbol is used\n{ query: 'validateToken', intent: 'implementation' }\n\n// Debug intent: prioritizes errors, logs, exception handling\n{ query: 'authentication error', intent: 'debug' }\n\n// Limit results\n{ query: 'UserModel', maxFiles: 5 }\n```\n\n**Intents:** `implementation`, `debug`, `tests`, `config`, `docs`, `explore`\n\n**Best for:** Finding symbol definitions/usages, understanding call chains, locating implementations.\n\n**NOT ideal for:** Exact string matching (use Grep), finding files by name (use Glob), broad multi-word queries (generates noise — results include a hint when >30 files match).\n\n---\n\n### smart_context\n\nOne-call context builder: search + read + graph expansion.\n\n```javascript\n{\n  task: 'Fix login authentication bug',\n  detail: 'balanced'  // minimal | balanced | deep\n}\n```\n\nReturns relevant files with compressed content, symbol details, and relationship graph.\n\n**Smart pattern detection:** Automatically detects literal patterns in your task (TODO, FIXME, /**, console.log, debugger) and prioritizes them in search results.\n\n**When to use:** Starting a new task and need comprehensive context.\n\n---\n\n### build_index\n\nBuild a symbol index for the project (functions, classes, imports).\n\n```javascript\n{ incremental: true }  // Only reindex changed files\n```\n\n**When to use:** Once after checkout, or after major changes. Improves search ranking and context relevance.\n\n---\n\n### smart_metrics\n\nInspect token savings and usage statistics.\n\n```javascript\n{ window: '24h' }  // or '7d', '30d', 'all'\n```\n\n**When to use:** Verify the MCP is working and see actual savings.\n\n## Advanced Tools\n\nThese tools provide specialized capabilities for specific workflows:\n\n### smart_summary\n\nMaintain compressed task state across sessions.\n\n```javascript\n// Save checkpoint (flat API - recommended)\n{ action: 'update', goal: '...', status: 'in_progress', nextStep: '...' }\n\n// Or nested format (backward compatible)\n{ action: 'update', update: { goal: '...', status: 'in_progress', nextStep: '...' }}\n\n// Resume later\n{ action: 'get' }\n```\n\nCompresses task context to ~100 tokens (goal, status, decisions, blockers). Critical for long tasks. Supports both flat and nested formats.\nWhen git hygiene or SQLite health affects local state, responses also surface `mutationSafety`, `repoSafety`, `degradedMode`, and `storageHealth`.\n\n### smart_doctor\n\nRun one operational preflight across repo hygiene, SQLite health, compaction, and legacy cleanup.\n\n```javascript\nsmart_doctor({})\nsmart_doctor({ verifyIntegrity: false })\n```\n\nUse this before release, after long-lived local usage, or whenever `.devctx/state.sqlite` looks suspicious.\n\n---\n\n### smart_status\n\nDisplay current session context with progress visibility.\n\n```javascript\n{ format: 'detailed' }  // Full formatted output with emojis\n{ format: 'compact' }   // Minimal JSON\n```\n\nShows goal, status, recent decisions, touched files, pinned context, and progress stats. Updates automatically with each MCP operation.\nWhen repo safety or SQLite health affects state, `smart_status` stays useful via degraded mode and surfaces `storageHealth` plus the same `mutationSafety` contract as `smart_turn`.\n\n---\n\n### smart_edit\n\nBatch edit multiple files with pattern replacement.\n\n```javascript\n{\n  pattern: 'console.log',\n  replacement: 'logger.info',\n  files: ['src/a.js', 'src/b.js'],\n  mode: 'literal'  // or 'regex'\n}\n```\n\nSupports `dryRun: true` for preview. Useful for bulk refactoring, removing patterns, or renaming across files.\n\n---\n\n### smart_turn\n\nOrchestrate turn start/end with automatic task checkpoint recovery.\n\n```javascript\n{ phase: 'start', prompt: '...' }  // Recovers task checkpoint\n{ phase: 'end', event: 'milestone', update: {...} }  // Saves checkpoint\n```\n\nRecovers task state (goal, status, decisions, next step), not full conversation history.\n\n---\n\n### smart_read_batch\n\nRead multiple files in one call.\n\n```javascript\n{\n  files: [\n    { path: 'src/a.js', mode: 'outline' },\n    { path: 'src/b.js', mode: 'signatures' }\n  ]\n}\n```\n\nReduces round-trip latency when you know you need several files.\n\n---\n\n### smart_shell\n\nSafe diagnostic command execution (allowlisted commands only).\n\n```javascript\n{ command: 'git status' }\n```\n\nBlocks shell operators and unsafe commands by design.\n\n---\n\n### Diff-Aware Context\n\nAnalyze git changes intelligently (part of `smart_context`):\n\n```javascript\n{ task: 'Review changes', diff: 'main' }\n```\n\nReturns changed files prioritized by impact + related files (tests, importers).\n\n---\n\n### Context Prediction\n\nLearn from usage patterns and predict needed files (part of `smart_context`):\n\n```javascript\n{ task: 'Implement authentication', prefetch: true }\n```\n\nAfter 3+ similar tasks: 40-60% fewer round-trips, 15-20% additional savings.\n\n---\n\n### warm_cache\n\nPreload frequently accessed files into OS cache.\n\n```javascript\n{}  // No parameters\n```\n\nFirst query: 250ms → 50ms (5x faster cold start).\n\n---\n\n### git_blame\n\nFunction-level code attribution.\n\n```javascript\n// Who wrote each function?\n{ mode: 'symbol', filePath: 'src/server.js' }\n\n// Find code by author\n{ mode: 'author', authorQuery: 'alice@example.com' }\n\n// Recent changes\n{ mode: 'recent', daysBack: 7 }\n```\n\n---\n\n### cross_project\n\nShare context across monorepos and microservices.\n\n```javascript\n// Search all related projects\n{ mode: 'search', query: 'AuthService' }\n\n// Find symbol across projects\n{ mode: 'symbol', symbolName: 'validateToken' }\n```\n\nRequires `.devctx-projects.json` config file.\n\n## Client Compatibility\n\n| Client | MCP | Rules | Hooks | `smart_turn` | Persistence | Near-Automatic | Key Limitations |\n|--------|-----|-------|-------|--------------|-------------|----------------|-----------------|\n| **Cursor** | ✅ Full | ✅ Conditional<br>(`.cursor/rules/*.mdc`) | ❌ No | ✅ Manual call | ✅ SQLite<br>(Node 22+) | 🟡 **Medium**<br>Agent decides when | • No auto `smart_turn`<br>• Agent must follow rules<br>• Requires Agent mode |\n| **Claude Desktop** | ✅ Full | ✅ Embedded<br>(`CLAUDE.md`) | ✅ SessionStart<br>PostToolUse<br>Stop | ✅ Can auto-trigger<br>via hooks | ✅ SQLite<br>(Node 22+) | 🟢 **High**<br>Hooks auto-trigger | • Hooks are opt-in<br>• No conditional rules<br>• Fixed context: 200t |\n| **Codex CLI** | ✅ Full | ✅ Embedded<br>(`AGENTS.md`) | ❌ No | ✅ Manual call | ✅ SQLite<br>(Node 22+) | 🟡 **Low-Medium**<br>Agent decides when | • No auto `smart_turn`<br>• No conditional rules<br>• No hooks |\n| **Qwen Code** | ✅ Full | ✅ Embedded<br>(`AGENTS.md`) | ❌ No | ✅ Manual call | ✅ SQLite<br>(Node 22+) | 🟡 **Low-Medium**<br>Agent decides when | • No auto `smart_turn`<br>• No conditional rules<br>• No hooks |\n\n**Legend:**\n- 🟢 High: Hooks can auto-trigger tools at specific moments\n- 🟡 Medium/Low: Agent reads rules and decides when to use tools\n- ✅ Supported | ⚠️ Partial | ❌ Not supported\n\n---\n\n### What \"Near-Automatic\" Means\n\n**🟢 High (Claude Desktop with hooks):**\n- Hooks can auto-trigger `smart_turn(start)` when you start a session\n- Hooks can auto-checkpoint after significant tool use\n- Agent still decides which devctx tools to use for each task\n- **This is the closest to \"automatic\" behavior available**\n\n**🟡 Medium (Cursor):**\n- Agent reads base rules automatically (always active, 150 tokens)\n- Conditional profiles activate based on file globs (debugging, review, etc.)\n- Agent decides when to use devctx tools based on task\n- Agent must manually call `smart_turn` (not auto-triggered)\n\n**🟡 Low-Medium (Codex, Qwen):**\n- Agent reads embedded rules automatically (always active, 200 tokens)\n- Agent decides when to use devctx tools based on task\n- Agent must manually call `smart_turn` (not auto-triggered)\n- No conditional activation or hooks\n\n---\n\n### What \"Near-Automatic\" Does NOT Mean\n\n❌ **Not automatic prompt interception** - MCP cannot intercept or modify your prompts before the agent sees them  \n❌ **Not forced tool usage** - Agent always has autonomy to decide which tools to use  \n❌ **Not guaranteed workflow** - Agent may skip devctx tools for simple tasks (this is fine)  \n❌ **Not client-level magic** - Behavior depends on agent following rules and making good decisions\n\n---\n\n### The Reality\n\n**All clients work the same way:**\n1. Agent reads rules (guidance about when devctx tools are useful)\n2. Agent decides tool usage (autonomy to choose best approach)\n3. MCP provides tools (passive, only responds when called)\n4. You verify with metrics (`npm run report:metrics`)\n\n**The differences:**\n- **Hooks** (Claude Desktop) can auto-trigger specific tools at specific moments (e.g., `smart_turn(start)` on session start)\n- **Conditional rules** (Cursor) reduce fixed context cost and activate task-specific profiles when relevant\n- **Embedded rules** (Codex, Qwen) are simple, always active, and work everywhere\n\n---\n\n### Which Client Should I Use?\n\n**Choose Cursor if:**\n- ✅ You want lowest fixed context cost (150 tokens base + 120 tokens profile when active)\n- ✅ You work on complex, multi-file tasks (debugging, refactoring, architecture)\n- ✅ You want conditional rules that activate based on file patterns\n\n**Choose Claude Desktop if:**\n- ✅ You want closest to \"automatic\" behavior (hooks can auto-trigger `smart_turn`)\n- ✅ You want session-aware workflows with automatic checkpointing\n- ✅ You're okay with opt-in hook configuration\n\n**Choose Codex or Qwen if:**\n- ✅ You want simple, embedded rules (no separate config files)\n- ✅ You prefer lightweight setup (single `AGENTS.md` file)\n- ✅ You're okay with manual `smart_turn` calls and no conditional activation\n\n**Bottom line:** All clients work well. The choice depends on your preference for automation level vs simplicity.\n\nSee [Client Compatibility Guide](./docs/client-compatibility.md) for detailed comparison.\n\n---\n\n## Installation\n\n### Step 1: Install the MCP Server\n\n#### Minimal (Any Client)\n\n```bash\nnpm install -g smart-context-mcp\nnpx smart-context-init --target .\n```\n\nRestart your AI client. Done.\n\n#### Verify Installation\n\n```bash\n# Check installed version\nnpm list -g smart-context-mcp\n\n# Should show: smart-context-mcp@1.20.0 (or later)\n\n# Update to latest version\nnpm update -g smart-context-mcp\n\n# Or reinstall from scratch\nnpm uninstall -g smart-context-mcp\nnpm install -g smart-context-mcp\n```\n\n**After updating:** The binary is updated globally, but agent rules (`.cursorrules`, `CLAUDE.md`, `AGENTS.md`) in each project are generated from the installed version and are **not updated automatically**.\n\nRe-run init after each update to get the latest rules:\n\n```bash\n# Re-apply rules to a project after updating\nnpx smart-context-init --target /path/to/your/project --clients cursor\n# or for all clients\nnpx smart-context-init --target /path/to/your/project --clients all\n```\n\nThen restart your AI client to load the new version.\n\n---\n\n### Cursor\n\n```bash\nnpm install -g smart-context-mcp\nnpx smart-context-init --target . --clients cursor\n```\n\nRestart Cursor. Tools appear in Agent mode.\n\n**Files created:**\n- `.cursor/mcp.json` - MCP server config\n- `.cursor/rules/devctx.mdc` - Base agent rules (10 lines, always active)\n- `.cursor/rules/profiles-compact/*.mdc` - Task profiles (conditional)\n- `.devctx/bin/cursor-devctx` - Optional assisted launcher for long tasks\n- `.git/hooks/pre-commit` - Safety hook\n- `.gitignore` - Adds `.devctx/`\n\n---\n\n### Codex CLI\n\n```bash\nnpm install -g smart-context-mcp\nnpx smart-context-init --target . --clients codex\n```\n\nRestart Codex.\n\n**Files created:**\n- `.codex/config.toml` - MCP server config\n- `AGENTS.md` - Agent rules\n- `.git/hooks/pre-commit` - Safety hook\n- `.gitignore` - Adds `.devctx/`\n\n---\n\n### Claude Desktop\n\n```bash\nnpm install -g smart-context-mcp\nnpx smart-context-init --target . --clients claude\n```\n\nRestart Claude Desktop.\n\n**Files created:**\n- `.mcp.json` - MCP server config\n- `.claude/settings.json` - Hook config\n- `CLAUDE.md` - Agent rules\n- `.git/hooks/pre-commit` - Safety hook\n- `.gitignore` - Adds `.devctx/`\n\n---\n\n### Qwen Code\n\n```bash\nnpm install -g smart-context-mcp\nnpx smart-context-init --target . --clients qwen\n```\n\nRestart Qwen Code.\n\n**Files created:**\n- `.qwen/settings.json` - MCP server config\n- `AGENTS.md` - Agent rules\n- `.git/hooks/pre-commit` - Safety hook\n- `.gitignore` - Adds `.devctx/`\n\n## Agent Rules: The Secret Sauce\n\nWhat makes this MCP different is **task-specific agent guidance**. Installation generates rules that teach agents optimal workflows:\n\n### Debugging Profile\n```\nsmart_turn(start) → smart_search(intent=debug) → smart_read(symbol) → \nsmart_shell('npm test') → fix → smart_turn(end)\n```\n**Savings:** 90% (150K → 15K tokens)\n\n### Code Review Profile\n```\nsmart_turn(start) → smart_context(diff=true) → smart_read(signatures) → \nreview → smart_turn(end)\n```\n**Savings:** 87% (200K → 25K tokens)\n\n### Refactoring Profile\n```\nsmart_turn(start) → smart_context(entryFile) → smart_read(signatures) → \nrefactor → smart_shell('npm test') → smart_turn(end)\n```\n**Savings:** 89% (180K → 20K tokens)\n\n### Testing Profile\n```\nsmart_turn(start) → smart_search(intent=tests) → smart_read(symbol) → \nwrite test → smart_shell('npm test') → smart_turn(end)\n```\n**Savings:** 90% (120K → 12K tokens)\n\n### Architecture Profile\n```\nsmart_turn(start) → smart_context(detail=minimal) → smart_read(signatures) → \nanalyze → smart_turn(end)\n```\n**Savings:** 90% (300K → 30K tokens)\n\n**Key insight:** The value isn't just in the tools—it's in teaching agents **when** and **how** to use them.\n\n---\n\n### Step 2: Set Up Agent Rules (Recommended)\n\nTo ensure agents use devctx automatically, set up client-specific rules:\n\n#### Cursor Users\n\nAlready included: `.cursorrules` is committed in the project.\n\n**Verify it's working:**\n- Agent should mention devctx usage policy\n- Agent should use devctx tools automatically\n- For long tasks, prefer `./.devctx/bin/cursor-devctx task --prompt \"...\" -- <agent-command>`\n\n#### Claude Desktop Users\n\nCreate `CLAUDE.md` in your project root:\n\n```bash\n# Copy template\ncp docs/agent-rules-template.md CLAUDE.md\n# Edit to keep only the CLAUDE.md section\n```\n\nOr copy the content from `docs/agent-rules-template.md`.\n\n#### Other Agent Clients\n\nCreate `AGENTS.md` in your project root using the same template.\n\n**Why these rules matter:**\n- ✅ Agents use devctx automatically (no manual forcing)\n- ✅ Consistent behavior across all clients\n- ✅ Visible feedback when devctx is used\n- ✅ Warnings when devctx should be used but isn't\n\nSee [Agent Rules Template](./docs/agent-rules-template.md) for complete setup.\n\n---\n\n### Feedback When Not Used\n\nIf the agent doesn't use devctx tools in a non-trivial task, it will add a note:\n\n```\nNote: devctx not used because: [reason]\nTo use devctx next time: \"Use smart-context-mcp: smart_turn(start) → ...\"\n```\n\n**Why this matters:**\n- Makes non-usage visible\n- Educates about when devctx adds value\n- Provides forcing prompt for next turn\n- Identifies setup issues (MCP unavailable, index not built)\n\n---\n\n### How to Force devctx Usage\n\n**When to use these prompts:**\n- Agent didn't use devctx in a non-trivial task\n- You want to recover persisted task context\n- Task is complex (debugging, review, refactor, testing, architecture)\n\n**Official prompt (complete workflow):**\n```\nUse smart-context-mcp for this task:\n1. Start with smart_turn(start, userPrompt, ensureSession=true) to recover context\n2. Use smart_context or smart_search before reading files\n3. Use smart_read(outline|signatures|symbol) instead of full reads\n4. Close with smart_turn(end) when you reach a milestone\n```\n\n**Ultra-short prompt (copy-paste ready):**\n```\nUse devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)\n```\n\n**Example usage:**\n```\nUser: \"Debug the authentication error\"\nAgent: [uses native tools]\nAgent: \"Note: devctx not used because: already had sufficient context...\"\n\nUser: \"Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)\"\nAgent: [uses smart_turn, smart_search, smart_read]\nAgent: \"Found the issue in validateToken()...\"\n```\n\nSee [agent-rules/](./tools/devctx/agent-rules/) for complete profiles.\n\n## Getting Started\n\n### Day 1: Install + Build Index (Critical)\n\n1. **Install:**\n   ```bash\n   npm install smart-context-mcp\n   npx smart-context-init --target .\n   ```\n\n2. **Build index (REQUIRED for quality):**\n   ```bash\n   npm run build-index\n   # or tell agent: \"Run build_index tool\"\n   ```\n   \n   **Why critical:** Without index, `smart_search` and `smart_context` are degraded. Agent may prefer native tools. No token savings.\n\n3. **Use core tools:**\n   - `smart_read` for file structure\n   - `smart_search` for finding code\n   - `smart_context` for comprehensive context\n   - `smart_metrics` to verify savings\n\n4. **Let the agent decide:** Don't force tool usage. The generated rules will guide the agent naturally.\n\n### After 1 week: Add advanced tools\n\n- `smart_summary` if you work on long tasks\n- `smart_turn` if using Claude Code CLI\n- `git_blame` for code attribution\n- `cross_project` if working in monorepos\n\n### After 1 month: Optimize\n\n- Check `smart_metrics` for usage patterns\n- Enable `warm_cache` if cold starts are slow\n- Enable `prefetch` in `smart_context` for repetitive tasks\n\n## Metrics & Verification\n\n### Run full benchmark\n\n```bash\nnpm run benchmark\n```\n\nRuns all verification suites:\n- 740+ unit tests\n- 14 feature verifications\n- Synthetic corpus evaluation\n- Real project evaluation\n- Orchestration regression benchmark (5 core scenarios)\n- Production metrics report\n\nTakes 3-4 minutes. See [Benchmark Documentation](./docs/verification/benchmark.md) for details.\n\nRelease gating for orchestration quality is also available with `npm run benchmark:orchestration:release`, and `npm publish` now blocks on that gate via `prepublishOnly`.\n\n### Check it's working\n\n```bash\nnpm run report:metrics\n```\n\n**Good signs:**\n- Tool usage > 0 (agent using devctx)\n- Savings 60-90% (compression working)\n- Multiple tools used (workflows followed)\n\n**Bad signs:**\n- Tool usage = 0 (agent not using devctx)\n- Check: Rules installed? MCP running? Task complexity?\n\n**Example output:**\n\n```\ndevctx metrics report\n\nEntries:      3,696\nRaw tokens:   14,492,131\nFinal tokens: 1,641,051\nSaved tokens: 13,024,099 (89.87%)\n\nBy tool:\n  smart_search   count=692  saved=5,817,485 (95.45%)\n  smart_read     count=2108 saved=2,355,809 (70.52%)\n  smart_summary  count=449  saved=1,897,628 (97.89%)\n\nAdoption Analysis (Inferred from Tool Usage)\n\nTotal sessions:        156\nSessions with devctx:  89 (57%)\nSessions without:      67 (43%)\n\nNon-Trivial Tasks Only:\nTotal:                 112\nWith devctx:           78 (70%)\nWithout devctx:        34 (30%)\n\nBy Inferred Complexity:\n- complex      56/68 (82%)\n- moderate     25/52 (48%)\n- simple       8/36 (22%)\n\nWhen devctx IS used:\nAvg tools/session:     2.8\nAvg token savings:     146,337 tokens\n\nTop Tools Used:\n- smart_read            89 sessions\n- smart_search          67 sessions\n- smart_context         45 sessions\n\nLimitations:\n- Complexity inferred from operation count (not actual task complexity)\n- Can only measure when devctx IS used (tool calls visible)\n- Cannot measure feedback shown or forcing prompts (requires agent cooperation)\n- Sessions without devctx may be simple tasks (not adoption failures)\n```\n\n### Adoption Metrics (Experimental)\n\nThe metrics report now includes **adoption analysis** to measure how often devctx is actually used.\n\n**What we measure:**\n- ✅ Sessions with devctx tool usage (automatic, from tool calls)\n- ✅ Adoption rate overall and by inferred complexity\n- ✅ Top tools used per session\n- ✅ Average token savings when devctx is used\n\n**What we DON'T measure:**\n- ❌ Feedback frequency (requires agent to report it)\n- ❌ Feedback reasons (requires agent cooperation)\n- ❌ Forcing prompt usage (can't detect from metrics)\n- ❌ Actual task complexity (only inferred from operation count)\n\n**Limitations:**\n- Complexity is inferred (operation count), not actual\n- Can only measure when devctx IS used (tool calls visible)\n- Can't detect non-usage unless agent reports it\n- Sessions without devctx may be simple tasks (not failures)\n\n**Why this is useful:**\n- See if devctx is being adopted in practice\n- Identify patterns (complex tasks → higher adoption)\n- Verify rules and onboarding are working\n- Complement compression metrics with usage metrics\n\nSee [Adoption Metrics Design](./docs/adoption-metrics-design.md) for complete analysis.\n\n---\n\n### Real-Time Usage Feedback (New!)\n\nGet **immediate visibility** into devctx tool usage in every agent response.\n\n**ENABLED BY DEFAULT** - Shows feedback after every devctx tool call.\n\n**Disable if too verbose:**\n```bash\nexport DEVCTX_SHOW_USAGE=false\n```\n\n**What you'll see:**\n```markdown\n---\n\n📊 **devctx usage this session:**\n- **smart_read**: 3 calls | ~45.0K tokens saved (file1.js, file2.js, file3.js)\n- **smart_search**: 1 call | ~12.0K tokens saved (query)\n\n**Total saved:** ~57.0K tokens\n\n*To disable this message: `export DEVCTX_SHOW_USAGE=false`*\n```\n\n**Benefits:**\n- ✅ Know immediately if agent is using devctx\n- ✅ See token savings in real-time\n- ✅ Verify forcing prompts worked\n- ✅ Debug adoption issues instantly\n\n**When to use:**\n- Verifying agent follows rules\n- Debugging why devctx isn't used\n- Measuring real-time impact\n- Validating setup after installation\n\nSee [Usage Feedback Documentation](./docs/usage-feedback.md) for complete guide.\n\n---\n\n### Decision Explanations (New!)\n\nUnderstand **why** the agent chose devctx tools and what benefits are expected.\n\n**ENABLED BY DEFAULT** - Shows decision explanations for every devctx tool call.\n\n**Disable if too verbose:**\n```bash\nexport DEVCTX_EXPLAIN=false\n```\n\n**What you'll see:**\n```markdown\n---\n\n🤖 **Decision explanations:**\n\n**smart_read** (read src/server.js (outline mode))\n- **Why:** File is large (2500 lines), outline mode extracts structure only\n- **Instead of:** Read (full file)\n- **Expected benefit:** ~45.0K tokens saved\n- **Context:** 2500 lines, 50000 tokens → 5000 tokens\n\n**smart_search** (search \"authentication\" (intent: debug))\n- **Why:** Intent-aware search prioritizes relevant results\n- **Instead of:** Grep (unranked results)\n- **Expected benefit:** ~12.0K tokens saved, Better result ranking\n\n*To disable: `export DEVCTX_EXPLAIN=false`*\n```\n\n**Benefits:**\n- ✅ Understand agent decision-making\n- ✅ Learn when to use which tool\n- ✅ Debug tool selection issues\n- ✅ Validate agent is making good choices\n\n**When to use:**\n- Learning how devctx works\n- Debugging why certain tools were chosen\n- Validating agent behavior\n- Understanding best practices\n\n**Combine with usage feedback** for maximum visibility:\n```bash\nexport DEVCTX_SHOW_USAGE=true\nexport DEVCTX_EXPLAIN=true\n```\n\nSee [Decision Explainer Documentation](./docs/decision-explainer.md) for complete guide.\n\n---\n\n### Missed Opportunities Detection (New!)\n\nDetect when devctx **should have been used but wasn't**.\n\n**ENABLED BY DEFAULT** - Shows warnings when devctx adoption is low.\n\n**Disable if not needed:**\n```bash\nexport DEVCTX_DETECT_MISSED=false\n```\n\n**What you'll see:**\n```markdown\n---\n\n⚠️ **Missed devctx opportunities detected:**\n\n**Session stats:**\n- Duration: 420s\n- devctx operations: 2\n- Estimated total operations: 25\n- devctx adoption: 8%\n\n🟡 **low devctx adoption**\n- **Issue:** Low devctx adoption: 2/25 operations (8%). Target: >50%.\n- **Suggestion:** Agent may be using native tools. Consider forcing prompt.\n- **Potential savings:** ~184.0K tokens\n\n**How to fix:**\n1. Use forcing prompt\n2. Check if index is built\n3. Verify MCP is active\n```\n\n**Detects:**\n- 🔴 No devctx usage in long sessions (>5 min)\n- 🟡 Low adoption (<30% of operations)\n- 🟡 Usage dropped (no calls for >3 min)\n\n**Benefits:**\n- ✅ Identify adoption gaps\n- ✅ Quantify potential savings\n- ✅ Validate forcing prompts worked\n- ✅ Detect when agent switches to native tools\n\n**Limitations:**\n- Total operations are estimated (not measured)\n- May have false positives for simple tasks\n- Session-scoped only (resets on restart)\n\n**All features enabled by default.** To disable all:\n```bash\nexport DEVCTX_SHOW_USAGE=false\nexport DEVCTX_EXPLAIN=false\nexport DEVCTX_DETECT_MISSED=false\n```\n\nSee [Missed Opportunities Documentation](./docs/missed-opportunities.md) for complete guide.\n\n---\n\n### Agent Rules (Multi-Client Support)\n\nThe project includes **agent rules** that enforce devctx usage across different clients:\n\n- **Cursor:** `.cursorrules` (committed to git)\n- **Claude Desktop:** `CLAUDE.md` (create from template in `docs/agent-rules-template.md`)\n- **Other agents:** `AGENTS.md` (create from template in `docs/agent-rules-template.md`)\n\n**All rules enforce the same policy:**\n- Use `smart_read` instead of `Read`\n- Use `smart_search` instead of `Grep`\n- Use `smart_context` instead of multiple reads\n- Explain if native tools are used\n\nSee [Agent Rules Template](./docs/agent-rules-template.md) for setup instructions.\n\n---\n\n### MCP Prompts (Automatic Forcing)\n\nThe MCP server provides **prompts** that automatically inject forcing instructions:\n\n**Quick forcing:**\n```\n/prompt use-devctx\n```\n\nThis injects: `Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)`\n\n**Available prompts:**\n- `/prompt use-devctx` - Ultra-short forcing prompt\n- `/prompt devctx-workflow` - Complete workflow template\n- `/prompt devctx-preflight` - Preflight checklist (index + session init)\n\n**Benefits:**\n- ✅ No need to remember/type forcing syntax\n- ✅ Centrally managed (updates automatically)\n- ✅ Discoverable in Cursor prompts menu\n- ✅ No typos\n\nSee [MCP Prompts Documentation](./docs/mcp-prompts.md) for complete guide.\n\n---\n\n### Quick verification\n\n```bash\nnpm run verify  # Feature verification (20 tools)\nnpm test        # Unit tests (740+ tests)\nnpm run eval    # Synthetic corpus\nnpm run eval:self  # Real project\n```\n\n## Troubleshooting\n\n### Agent not using devctx tools\n\n**Check:**\n```bash\n# 1. Rules installed?\ncat .cursor/rules/devctx.mdc\n\n# 2. MCP running?\n# Cursor: Settings → MCP → Check \"smart-context\" active\n\n# 3. Index built?\nls .devctx/index.json\n\n# 4. Metrics show usage?\nnpm run report:metrics\n```\n\n**Possible causes:**\n- Rules not installed → Run `npx smart-context-init --target .`\n- MCP not running → Restart client\n- Index not built → Run `npm run build-index` or tell agent \"Run build_index tool\"\n- Task too simple → Built-in tools sufficient (this is fine)\n- Agent in Ask mode → Read-only, no MCP access\n\n**Force devctx usage (copy-paste ready):**\n```\nUse devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)\n```\n\nSee [How to Force devctx Usage](#how-to-force-devctx-usage) for complete workflow.\n\n---\n\n### Enable Workflow Tracking\n\nTo track complete workflows (debugging, review, refactor, testing, architecture):\n\n```bash\nexport DEVCTX_WORKFLOW_TRACKING=true\n```\n\nThen restart your AI client. View workflow metrics:\n\n```bash\nnpm run report:workflows -- --summary\n```\n\nSee [Workflow Metrics](./docs/workflow-metrics.md) for details.\n\n---\n\n### High token usage despite devctx\n\n**Check:**\n```bash\nnpm run report:metrics\n```\n\n**Look for:**\n- Low tool usage (< 20% of operations)\n- High `full` mode usage (agent not cascading)\n- Low compression ratios (< 50%)\n\n**Possible causes:**\n- Agent not following workflows\n- Task doesn't benefit from compression\n- Rules unclear for this task type\n\n---\n\n### Context not persisting\n\n**Check:**\n```bash\n# 1. Node version (need 22+ for SQLite)\nnode --version\n\n# 2. SQLite exists?\nls -lh .devctx/state.sqlite\n\n# 3. Agent calling smart_turn?\nsqlite3 .devctx/state.sqlite \"SELECT COUNT(*) FROM sessions\"\n```\n\n**Possible causes:**\n- Node 18-20 → No SQLite (upgrade to 22+)\n- Agent not calling `smart_turn` → No task checkpoints\n- Session ID mismatch → Can't recover checkpoint\n- `.devctx/state.sqlite` tracked/staged → runtime context writes are intentionally blocked until git hygiene is fixed\n- `.devctx/state.sqlite` locked/corrupted/oversized → inspect `storageHealth` from `smart_status` or `smart_metrics`\n- broader local-state preflight → run `smart_doctor` or `smart-context-doctor --json`\n\n**Recovery flow:**\n- `missing` → run a persisted action like `smart_summary update` or `smart_turn end`\n- `oversized` → run `smart_summary compact`\n- `locked` → stop competing devctx processes, then retry\n- `corrupted` → back up `.devctx/state.sqlite`, remove it, and let devctx recreate local state\n\n---\n\n### Rules not applied\n\n**Check:**\n```bash\ncat .cursor/rules/devctx.mdc  # or AGENTS.md, CLAUDE.md\n```\n\n**If missing:**\n```bash\nnpx smart-context-init --target .\n```\n\n**If exists but agent ignores:**\n- This is expected (rules are guidance, not enforcement)\n- Agent decides based on task\n- Check metrics to see actual usage\n\n## Supported Languages\n\n**First-class (AST parsing):** JavaScript, TypeScript, JSX, TSX\n\n**Heuristic parsing:** Python, Go, Rust, Java, C#, Kotlin, PHP, Swift\n\n**Structural extraction:** Shell, Terraform, HCL, Dockerfile, SQL, JSON, YAML, TOML\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Point to different project\nexport DEVCTX_PROJECT_ROOT=/path/to/project\n\n# Disable cache warming\nexport DEVCTX_CACHE_WARMING=false\n\n# Change warm file count\nexport DEVCTX_WARM_FILES=100\n```\n\n### Cross-Project Setup\n\nCreate `.devctx-projects.json`:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"projects\": [\n    { \"name\": \"main-app\", \"path\": \".\", \"type\": \"main\" },\n    { \"name\": \"shared-lib\", \"path\": \"../shared-lib\", \"type\": \"library\" },\n    { \"name\": \"api-service\", \"path\": \"../api-service\", \"type\": \"service\" }\n  ]\n}\n```\n\nBuild indexes for each project:\n\n```bash\ncd main-app && npx build-index\ncd ../shared-lib && npx build-index\ncd ../api-service && npx build-index\n```\n\n## Storage\n\nAll data stored in `.devctx/`:\n\n- `index.json` - Symbol index (`INDEX_VERSION 7`: ADR + ADR sections, richer Python/Go)\n- `state.sqlite` - Sessions, metrics, patterns, task handoffs, test failures, explain cache (Node 22+)\n- `metrics.jsonl` - Opt-in legacy file, only when `DEVCTX_METRICS_FILE=path.jsonl` is set\n\nCross-project (opt-in via `DEVCTX_GLOBAL_MEMORY=true`):\n\n- `~/.devctx/global.db` - Scrubbed decisions, patterns, playbooks, notes with semantic recall\n\nAdd to `.gitignore`:\n\n```\n.devctx/\n```\n\n## Security\n\nThis MCP is **secure by default**:\n\n- ✅ **Allowlist-only commands** - Only safe diagnostic commands (`ls`, `git status`, `npm test`, etc.)\n- ✅ **No shell operators** - Blocks `|`, `&`, `;`, `>`, `<`, `` ` ``, `$()`\n- ✅ **Path validation** - Cannot escape project root\n- ✅ **No write access** - Cannot modify your code\n- ✅ **Repository safety** - Prevents accidental commit of local state\n- ✅ **Resource limits** - 15s timeout, 10MB buffer\n\n**What `smart_shell` can run:**\n\n```bash\n# Allowed\ngit status              # ✓ Safe git read operations\nnpm test                # ✓ Safe package manager scripts\nfind . -name \"*.js\"     # ✓ File discovery\nrg \"pattern\"            # ✓ Code search\n\n# Blocked\ngit commit              # ✗ Write operations blocked\nnpm install pkg         # ✗ Package changes blocked\nls | grep secret        # ✗ Shell operators blocked\nrm -rf /                # ✗ Dangerous commands blocked\n```\n\n**Real rejection examples:**\n\n```javascript\n// Shell operator blocked\nsmartShell({ command: \"ls | grep secret\" })\n→ { exitCode: 126, blocked: true, output: \"Shell operators are not allowed...\" }\n\n// Dangerous command blocked\nsmartShell({ command: \"rm -rf /\" })\n→ { exitCode: 126, blocked: true, output: \"Dangerous pattern detected...\" }\n\n// Git write blocked\nsmartShell({ command: \"git commit -m 'test'\" })\n→ { exitCode: 126, blocked: true, output: \"Git subcommand not allowed: commit...\" }\n\n// Package install blocked\nsmartShell({ command: \"npm install malicious\" })\n→ { exitCode: 126, blocked: true, output: \"Package manager subcommand not allowed: install...\" }\n```\n\n**Verification:**\n\n```bash\n# Run 60+ security tests to verify behavior\ncd tools/devctx ",
  "bytes": 60000,
  "sha": "cab7fd47193383353a2097df8c93f2f8afcdfcdf52c3eabe390821557647e810",
  "repo_slug": "arrayo/smart-context-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arrayo_smart_context_mcp_e86346f1/readme"
}