context-mode 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,33 @@
+{
+  "name": "claude-context-mode",
+  "owner": {
+    "name": "Mert Koseoğlu",
+    "email": "code.bm.ksglu@gmail.com"
+  },
+  "metadata": {
+    "description": "Claude Code plugins by Mert Koseoğlu",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "context-mode",
+      "source": "./",
+      "description": "Claude Code MCP plugin that saves 94% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and smart truncation.",
+      "version": "0.5.0",
+      "author": {
+        "name": "Mert Koseoğlu"
+      },
+      "category": "development",
+      "keywords": [
+        "mcp",
+        "context-window",
+        "sandbox",
+        "code-execution",
+        "fts5",
+        "bm25",
+        "playwright",
+        "context7"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Claude Code MCP plugin that saves 94% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and smart truncation.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -10,16 +10,16 @@ Context Mode intercepts these operations, processes data in isolated subprocesse
 
 Claude Code has a 200K token context window. Here's how fast popular MCP servers eat through it:
 
-| MCP Server | Tool | Output per Call | Source |
-|---|---|---|---|
-| **Playwright** | `browser_snapshot` | 10K-135K tokens (50-540 KB) | [playwright-mcp#1233](https://github.com/microsoft/playwright-mcp/issues/1233) |
-| **Context7** | `query-docs` | 4K-10K tokens per query | [upstash/context7](https://github.com/upstash/context7) |
-| **GitHub** | `list_commits` (30) | 29K-64K tokens | [github-mcp-server#142](https://github.com/github/github-mcp-server/issues/142) |
-| **Sentry** | full mode tools | 14K tokens (definitions only) | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp) |
-| **Supabase** | database tools | 4.2K tokens (definitions only) | [supabase-community/supabase-mcp](https://github.com/supabase-community/supabase-mcp) |
-| **Firecrawl** | `scrape` / `crawl` | 5K-50K+ tokens per page | [firecrawl](https://github.com/mendableai/firecrawl) |
-| **Chrome DevTools** | all tools | 17K tokens (definitions only) | Community benchmark |
-| **Fetch** | `fetch` | 5K-50K tokens per page | Official reference server |
+| MCP Server | Tool | Without Context Mode | With Context Mode | Savings | Source |
+|---|---|---|---|---|---|
+| **Playwright** | `browser_snapshot` | 10K-135K tokens | ~20 tokens | **99%** | [playwright-mcp#1233](https://github.com/microsoft/playwright-mcp/issues/1233) |
+| **Context7** | `query-docs` | 4K-10K tokens | ~70 tokens | **98%** | [upstash/context7](https://github.com/upstash/context7) |
+| **GitHub** | `list_commits` (30) | 29K-64K tokens | ~10 tokens | **99%** | [github-mcp-server#142](https://github.com/github/github-mcp-server/issues/142) |
+| **Sentry** | issue analysis | 5K-30K tokens | ~25 tokens | **99%** | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp) |
+| **Supabase** | schema queries | 2K-30K tokens | ~30 tokens | **99%** | [supabase-community/supabase-mcp](https://github.com/supabase-community/supabase-mcp) |
+| **Firecrawl** | `scrape` / `crawl` | 5K-50K+ tokens | ~70 tokens | **99%** | [firecrawl](https://github.com/mendableai/firecrawl) |
+| **Chrome DevTools** | DOM / network | 5K-50K+ tokens | ~25 tokens | **99%** | Community benchmark |
+| **Fetch** | `fetch` | 5K-50K tokens | ~70 tokens | **99%** | Official reference server |
 
 **Real measurement** ([Scott Spence, 2025](https://scottspence.com/posts/optimising-mcp-server-context-usage-in-claude-code)): With 81+ MCP tools enabled across multiple servers, **143K of 200K tokens (72%) consumed** — 82K tokens just for MCP tool definitions. Only 28% left for actual work.
 
@@ -44,10 +44,11 @@ Claude Code has a 200K token context window. Here's how fast popular MCP servers
 ### Option 1: Claude Code Plugin (Recommended)
 
 ```bash
-/plugin install context-mode@claude-plugin-directory
+/plugin marketplace add mksglu/claude-context-mode
+/plugin install context-mode@claude-context-mode
 ```
 
-Installs as a Claude Code plugin with skills and MCP server bundled together.
+Installs as a Claude Code plugin with MCP server + skills bundled. The skill automatically guides Claude to route large outputs through Context Mode.
 
 ### Option 2: MCP Server Only
 
@@ -57,6 +58,12 @@ claude mcp add context-mode -- npx -y context-mode
 
 Restart Claude Code. 5 tools are now available.
 
+### Option 3: Local Development
+
+```bash
+claude --plugin-dir ./path/to/context-mode
+```
+
 ## Tools
 
 ### `execute` — Run Code in Sandbox
@@ -68,11 +75,22 @@ Claude calls: execute({ language: "shell", code: "gh pr list --json title,state
 Returns: "3"                  ← 2 bytes instead of 8KB JSON
 ```
 
+**Intent-driven search** (v0.5.0): When you provide an `intent` parameter and output exceeds 5KB, Context Mode uses BM25 search to return only the relevant sections — instead of blind head/tail truncation.
+
+```
+Claude calls: execute({
+  language: "shell",
+  code: "cat /var/log/app.log",
+  intent: "connection refused database error"
+})
+Returns: only the 3 matching log sections (1.5KB) ← instead of 100KB truncated log
+```
+
 Authenticated CLIs work out of the box — `gh`, `aws`, `gcloud`, `kubectl`, `docker` credentials are passed through securely. Bun auto-detected for 3-5x faster JS/TS.
 
 ### `execute_file` — Process Files Without Loading
 
-File contents never enter context. The file is read into a `FILE_CONTENT` variable inside the sandbox.
+File contents never enter context. The file is read into a `FILE_CONTENT` variable inside the sandbox. Also supports `intent` parameter for intent-driven search on large outputs.
 
 ```
 Claude calls: execute_file({ path: "access.log", language: "python", code: "..." })
@@ -207,6 +225,31 @@ Tail (40%): Final output with errors/results
 
 Line-boundary snapping — never cuts mid-line. Error messages at the bottom are always preserved.
 
+### Intent-Driven Search (v0.5.0)
+
+When `execute` or `execute_file` is called with an `intent` parameter and output exceeds 5KB, Context Mode replaces blind truncation with intelligent BM25 search:
+
+```
+Traditional truncation:
+  stdout (100KB) → head(60%) + tail(40%) → ~100KB in context
+  Problem: relevant info in the middle is lost
+
+Intent-driven search:
+  stdout (100KB) → chunk by lines → in-memory FTS5 → search(intent) → 2-5KB relevant sections
+  Result: only what you need enters context
+```
+
+Tested across 4 real-world scenarios:
+
+| Scenario | Smart Truncation | Intent Search | Intent Size | Truncation Size |
+|---|---|---|---|---|
+| Server log error (line 347/500) | **missed** | **found** | 1.5 KB | 5.0 KB |
+| 3 test failures among 200 tests | found 2/3 | **found 3/3** | 2.4 KB | 5.0 KB |
+| 2 build warnings among 300 lines | **missed both** | **found both** | 2.1 KB | 5.0 KB |
+| API auth error (line 743/1000) | **missed** | **found** | 1.2 KB | 4.9 KB |
+
+Smart truncation fails on 3 of 4 scenarios because relevant content is in the dropped middle section. Intent search finds the target every time while using 50-75% fewer bytes.
+
 ### HTML to Markdown Conversion
 
 `fetch_and_index` converts HTML in a subprocess (raw HTML never enters context):
@@ -264,6 +307,72 @@ Typical 45-minute debugging session:
 | Source code to edit | Plain `Read` tool | Need full content for edits |
 | Small files (<20 lines) | Plain `Read` tool | Minimal overhead |
 
+## Example Prompts
+
+Just ask naturally — Claude automatically routes through Context Mode when it saves tokens.
+
+### Git & GitHub
+
+```
+"Analyze the last 50 commits and find the most frequently changed files"
+"List all open PRs on this repo and summarize their status"
+"Show contributors ranked by commit count this month"
+"Find all commits that touched the auth module in the last 30 days"
+```
+
+### Code Analysis
+
+```
+"Analyze all TypeScript files in src/ and report function counts per file"
+"Find all TODO and FIXME comments across the codebase"
+"Count lines of code per language in this project"
+"List all exported functions from src/utils/ and their parameter signatures"
+```
+
+### Logs & Debugging
+
+```
+"Read the access log and break down requests by HTTP status code"
+"Find the top 10 slowest API endpoints from the request log"
+"Parse the error log and group exceptions by type with frequency"
+"Analyze the build output and list all warnings with file locations"
+```
+
+### Test & CI
+
+```
+"Run the test suite and give me a pass/fail summary"
+"Analyze test coverage output and find untested files"
+"Check which tests have been flaky in the last 10 CI runs"
+```
+
+### Data & Config
+
+```
+"Analyze package-lock.json and find the 10 largest dependencies by size"
+"Parse the CSV export and compute average response time per endpoint"
+"Read the Kubernetes manifests and summarize resource limits per pod"
+"Compare tsconfig.json across packages in this monorepo"
+```
+
+### Documentation Lookup
+
+```
+"Fetch the React useEffect docs and find the cleanup pattern"
+"Index the Next.js App Router documentation and search for loading states"
+"Look up the Zod docs and find string validation examples"
+"Fetch the Tailwind docs and search for responsive breakpoint utilities"
+```
+
+### Cloud & Infrastructure
+
+```
+"List all S3 buckets and their sizes using AWS CLI"
+"Show running Kubernetes pods and their restart counts"
+"List all Docker containers with their memory and CPU usage"
+"Check the status of all Cloudflare Workers in this account"
+```
+
 ## Requirements
 
 - **Node.js 18+**
@@ -279,12 +388,13 @@ Typical 45-minute debugging session:
 
 ## Test Suite
 
-113 tests across 3 suites:
+99+ tests across 4 suites:
 
 | Suite | Tests | Coverage |
 |---|---|---|
 | Executor | 55 | 10 languages, sandbox, truncation, concurrency, timeouts |
-| ContentStore | 34 | FTS5 schema, BM25 ranking, chunking, stemming, fixtures |
+| ContentStore | 40 | FTS5 schema, BM25 ranking, chunking, stemming, plain text indexing |
+| Intent Search | 4 | Smart truncation vs intent-driven search across 4 real-world scenarios |
 | MCP Integration | 24 | JSON-RPC protocol, all 5 tools, fetch_and_index, errors |
 
 ## Development
@@ -295,8 +405,8 @@ cd claude-context-mode
 npm install
 npm run build
 npm test              # executor (55 tests)
-npm run test:store    # FTS5/BM25 (34 tests)
-npm run test:all      # all suites (113 tests)
+npm run test:store    # FTS5/BM25 (40 tests)
+npm run test:all      # all suites (99+ tests)
 ```
 
 ## License

package/build/server.js

@@ -9,7 +9,7 @@ const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({
     name: "context-mode",
-    version: "0.4.0",
+    version: "0.5.0",
 });
 const executor = new PolyglotExecutor({ runtimes });
 // Lazy singleton — no DB overhead unless index/search is used
@@ -53,8 +53,14 @@ server.registerTool("execute", {
             .optional()
             .default(30000)
             .describe("Max execution time in ms"),
+        intent: z
+            .string()
+            .optional()
+            .describe("What you're looking for in the output. When provided and output is large (>5KB), " +
+            "returns only matching sections via BM25 search instead of truncated output. " +
+            "Example: 'find failing tests', 'HTTP 500 errors', 'memory usage statistics'."),
     }),
-}, async ({ language, code, timeout }) => {
+}, async ({ language, code, timeout, intent }) => {
     try {
         const result = await executor.execute({ language, code, timeout });
         if (result.timedOut) {
@@ -69,19 +75,34 @@ server.registerTool("execute", {
             };
         }
         if (result.exitCode !== 0) {
+            const output = `Exit code: ${result.exitCode}\n\nstdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`;
+            if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
+                return {
+                    content: [
+                        { type: "text", text: intentSearch(output, intent) },
+                    ],
+                    isError: true,
+                };
+            }
             return {
                 content: [
-                    {
-                        type: "text",
-                        text: `Exit code: ${result.exitCode}\n\nstdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`,
-                    },
+                    { type: "text", text: output },
                 ],
                 isError: true,
             };
         }
+        const stdout = result.stdout || "(no output)";
+        // Intent-driven search: if intent provided and output is large enough
+        if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
+            return {
+                content: [
+                    { type: "text", text: intentSearch(stdout, intent) },
+                ],
+            };
+        }
         return {
             content: [
-                { type: "text", text: result.stdout || "(no output)" },
+                { type: "text", text: stdout },
             ],
         };
     }
@@ -111,6 +132,36 @@ function indexStdout(stdout, source) {
     };
 }
 // ─────────────────────────────────────────────────────────
+// Helper: intent-driven search on execution output
+// ─────────────────────────────────────────────────────────
+const INTENT_SEARCH_THRESHOLD = 5_000; // bytes — ~80-100 lines
+function intentSearch(stdout, intent, maxResults = 5) {
+    const store = new ContentStore(":memory:");
+    try {
+        const totalLines = stdout.split("\n").length;
+        const totalBytes = Buffer.byteLength(stdout);
+        store.indexPlainText(stdout, "exec-output");
+        const results = store.search(intent, maxResults);
+        if (results.length === 0) {
+            return (`[Intent search: no matches for "${intent}" in ${totalLines}-line output. Returning full output.]\n\n` +
+                stdout);
+        }
+        const totalChunks = store.getStats().chunks;
+        const header = `[Intent search: ${results.length} of ${totalChunks} sections matched "${intent}" from ${totalLines}-line output (${(totalBytes / 1024).toFixed(1)}KB)]`;
+        const formatted = results
+            .map((r, i) => {
+            const matchLabel = i === 0 ? " (best match)" : "";
+            return `--- ${r.title}${matchLabel} ---\n${r.content}`;
+        })
+            .join("\n\n");
+        const footer = `[Full output: ${totalLines} lines / ${(totalBytes / 1024).toFixed(1)}KB. Re-run without intent to see raw output.]`;
+        return `${header}\n\n${formatted}\n\n${footer}`;
+    }
+    finally {
+        store.close();
+    }
+}
+// ─────────────────────────────────────────────────────────
 // Tool: execute_file
 // ─────────────────────────────────────────────────────────
 server.registerTool("execute_file", {
@@ -142,8 +193,13 @@ server.registerTool("execute_file", {
             .optional()
             .default(30000)
             .describe("Max execution time in ms"),
+        intent: z
+            .string()
+            .optional()
+            .describe("What you're looking for in the output. When provided and output is large (>5KB), " +
+            "returns only matching sections via BM25 search instead of truncated output."),
     }),
-}, async ({ path, language, code, timeout }) => {
+}, async ({ path, language, code, timeout, intent }) => {
     try {
         const result = await executor.executeFile({
             path,
@@ -163,19 +219,33 @@ server.registerTool("execute_file", {
             };
         }
         if (result.exitCode !== 0) {
+            const output = `Error processing ${path} (exit ${result.exitCode}):\n${result.stderr || result.stdout}`;
+            if (intent && intent.trim().length > 0 && Buffer.byteLength(output) > INTENT_SEARCH_THRESHOLD) {
+                return {
+                    content: [
+                        { type: "text", text: intentSearch(output, intent) },
+                    ],
+                    isError: true,
+                };
+            }
             return {
                 content: [
-                    {
-                        type: "text",
-                        text: `Error processing ${path} (exit ${result.exitCode}):\n${result.stderr || result.stdout}`,
-                    },
+                    { type: "text", text: output },
                 ],
                 isError: true,
             };
         }
+        const stdout = result.stdout || "(no output)";
+        if (intent && intent.trim().length > 0 && Buffer.byteLength(stdout) > INTENT_SEARCH_THRESHOLD) {
+            return {
+                content: [
+                    { type: "text", text: intentSearch(stdout, intent) },
+                ],
+            };
+        }
         return {
             content: [
-                { type: "text", text: result.stdout || "(no output)" },
+                { type: "text", text: stdout },
             ],
         };
     }

package/build/store.d.ts

@@ -33,6 +33,12 @@ export declare class ContentStore {
         path?: string;
         source?: string;
     }): IndexResult;
+    /**
+     * Index plain-text output (logs, build output, test results) by splitting
+     * into fixed-size line groups. Unlike markdown indexing, this does not
+     * look for headings — it chunks by line count with overlap.
+     */
+    indexPlainText(content: string, source: string, linesPerChunk?: number): IndexResult;
     search(query: string, limit?: number): SearchResult[];
     getStats(): StoreStats;
     close(): void;

package/build/store.js

@@ -94,6 +94,42 @@ export class ContentStore {
             codeChunks,
         };
     }
+    // ── Index Plain Text ──
+    /**
+     * Index plain-text output (logs, build output, test results) by splitting
+     * into fixed-size line groups. Unlike markdown indexing, this does not
+     * look for headings — it chunks by line count with overlap.
+     */
+    indexPlainText(content, source, linesPerChunk = 20) {
+        if (!content || content.trim().length === 0) {
+            const insertSource = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count) VALUES (?, 0, 0)");
+            const info = insertSource.run(source);
+            return {
+                sourceId: Number(info.lastInsertRowid),
+                label: source,
+                totalChunks: 0,
+                codeChunks: 0,
+            };
+        }
+        const chunks = this.#chunkPlainText(content, linesPerChunk);
+        const insertSource = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count) VALUES (?, ?, ?)");
+        const insertChunk = this.#db.prepare("INSERT INTO chunks (title, content, source_id, content_type) VALUES (?, ?, ?, ?)");
+        const transaction = this.#db.transaction(() => {
+            const info = insertSource.run(source, chunks.length, 0);
+            const sourceId = Number(info.lastInsertRowid);
+            for (const chunk of chunks) {
+                insertChunk.run(chunk.title, chunk.content, sourceId, "prose");
+            }
+            return sourceId;
+        });
+        const sourceId = transaction();
+        return {
+            sourceId,
+            label: source,
+            totalChunks: chunks.length,
+            codeChunks: 0,
+        };
+    }
     // ── Search ──
     search(query, limit = 3) {
         const sanitized = sanitizeQuery(query);
@@ -203,6 +239,41 @@ export class ContentStore {
         flush();
         return chunks;
     }
+    #chunkPlainText(text, linesPerChunk) {
+        // Try blank-line splitting first for naturally-sectioned output
+        const sections = text.split(/\n\s*\n/);
+        if (sections.length >= 3 &&
+            sections.length <= 200 &&
+            sections.every((s) => Buffer.byteLength(s) < 5000)) {
+            return sections
+                .map((section, i) => ({
+                title: `Section ${i + 1}`,
+                content: section.trim(),
+            }))
+                .filter((s) => s.content.length > 0);
+        }
+        const lines = text.split("\n");
+        // Small enough for a single chunk
+        if (lines.length <= linesPerChunk) {
+            return [{ title: "Output", content: text }];
+        }
+        // Fixed-size line groups with 2-line overlap
+        const chunks = [];
+        const overlap = 2;
+        const step = Math.max(linesPerChunk - overlap, 1);
+        for (let i = 0; i < lines.length; i += step) {
+            const slice = lines.slice(i, i + linesPerChunk);
+            if (slice.length === 0)
+                break;
+            const startLine = i + 1;
+            const endLine = Math.min(i + slice.length, lines.length);
+            chunks.push({
+                title: `Lines ${startLine}-${endLine}`,
+                content: slice.join("\n"),
+            });
+        }
+        return chunks;
+    }
     #buildTitle(headingStack, currentHeading) {
         if (headingStack.length === 0) {
             return currentHeading || "Untitled";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Claude Code MCP plugin that saves 94% of your context window. Sandboxed code execution, FTS5 knowledge base, and smart truncation.",
   "author": "Mert Koseoğlu",

package/skills/context-mode/SKILL.md

@@ -1,120 +1,139 @@
 ---
 name: context-mode
 description: |
-  Use context-mode tools (execute, execute_file) instead of Bash/cat when processing
-  large outputs. Trigger phrases: "analyze logs", "summarize output", "process data",
-  "parse JSON", "filter results", "extract errors", "check build output",
-  "analyze dependencies", "process API response", "large file analysis".
+  ALWAYS use context-mode tools instead of Bash/curl/cat when output MIGHT exceed 20 lines.
+  This includes: API requests (curl, fetch, gh, aws), file reading (cat, head, tail),
+  command output (npm test, git log, docker ps, kubectl), log analysis, data processing,
+  and ANY operation where you cannot guarantee the output will be small.
+  When in doubt, use context-mode — the cost of routing through it is near zero,
+  but the cost of flooding context with 50KB+ of raw data is catastrophic.
 ---
 
-# Context Mode: execute & execute_file
+# Context Mode: Default for All Large Output
 
-## When to Use (Decision Tree)
+## MANDATORY RULE
 
-```
-Will the command output > 20 lines?
-├── YES → Will you process/filter/summarize that output?
-│   ├── YES → Use execute or execute_file
-│   └── NO  → Use Bash (you need raw output)
-└── NO  → Use Bash (small output fits in context)
-```
-
-**Rule of thumb:** If you would pipe Bash output through grep/awk/jq to reduce it,
-use `execute` or `execute_file` instead — the LLM summary is better.
-
-## Quick Reference
-
-| Tool | Purpose | Key Parameters |
-|------|---------|---------------|
-| `execute` | Run inline code, get LLM summary | `code`, `language`, `timeout_ms`, `summary_prompt` |
-| `execute_file` | Run a script file, get LLM summary | `file_path`, `args`, `timeout_ms`, `summary_prompt` |
+**Before using Bash, curl, cat, or any command that produces output, ask yourself:**
 
-Both tools execute code and return an **LLM-generated summary** instead of raw stdout.
-The raw output never enters your context window — only the summary does.
+> "Could this output be more than 20 lines?"
 
-## Language Selection Guide
+If YES or UNCERTAIN → use `execute` or `execute_file`. Not Bash. Not curl. Not cat.
 
-| Scenario | Language | Why |
-|----------|----------|-----|
-| HTTP requests, JSON APIs | `javascript` | Native fetch, JSON.parse |
-| Data analysis, CSV, math | `python` | pandas, csv module, statistics |
-| Piping commands, grep, find | `shell` | Native OS tools |
-| TypeScript project analysis | `javascript` | Can require/import project files |
-| Log file filtering | `shell` | grep/awk are purpose-built |
-| File comparison | `python` | difflib is excellent |
+**This is not optional.** Every KB of unnecessary context reduces the quality and speed of the entire session.
 
-## Usage Pattern
-
-### execute — inline code
+## Decision Tree
 
 ```
-Tool: execute
-Parameters:
-  code: |
-    const data = require('fs').readFileSync('package.json', 'utf8');
-    const pkg = JSON.parse(data);
-    console.log(`Name: ${pkg.name}`);
-    console.log(`Dependencies: ${Object.keys(pkg.dependencies || {}).length}`);
-    console.log(`DevDependencies: ${Object.keys(pkg.devDependencies || {}).length}`);
-    Object.entries(pkg.dependencies || {}).forEach(([k, v]) => console.log(`  ${k}: ${v}`));
-  language: javascript
-  timeout_ms: 10000
-  summary_prompt: "List the package name, dependency count, and any outdated patterns"
+About to run a command / read a file / call an API?
+│
+├── Output is GUARANTEED small (<20 lines)?
+│   └── Use Bash (git status, pwd, ls, echo, etc.)
+│
+├── Output MIGHT be large or you're UNSURE?
+│   └── Use context-mode execute or execute_file
+│
+├── Fetching web documentation or HTML page?
+│   └── Use fetch_and_index → search
+│
+├── Processing output from another MCP tool (Playwright, Context7, etc.)?
+│   └── Use index → search
+│
+└── Reading a file to analyze/summarize (not edit)?
+    └── Use execute_file (file loads into FILE_CONTENT, not context)
 ```
 
-### execute_file — run existing script
-
-```
-Tool: execute_file
-Parameters:
-  file_path: ./scripts/analyze-bundle.js
-  args: ["--format", "summary"]
-  timeout_ms: 30000
-  summary_prompt: "Report bundle size changes and any chunks exceeding 500KB"
-```
+## When to Use Each Tool
+
+| Situation | Tool | Example |
+|-----------|------|---------|
+| Hit an API endpoint | `execute` | `fetch('http://localhost:3000/api/orders')` |
+| Run CLI that returns data | `execute` | `gh pr list`, `aws s3 ls`, `kubectl get pods` |
+| Run tests | `execute` | `npm test`, `pytest`, `go test ./...` |
+| Git operations | `execute` | `git log --oneline -50`, `git diff HEAD~5` |
+| Docker/K8s inspection | `execute` | `docker stats --no-stream`, `kubectl describe pod` |
+| Read a log file | `execute_file` | Parse access.log, error.log, build output |
+| Read a data file | `execute_file` | Analyze CSV, JSON, YAML, XML |
+| Read source code to analyze | `execute_file` | Count functions, find patterns, extract metrics |
+| Fetch web docs | `fetch_and_index` | Index React/Next.js/Zod docs, then search |
+| Process large MCP output | `index` → `search` | Index Playwright snapshot, then query elements |
+
+## Automatic Triggers
+
+Use context-mode for ANY of these, without being asked:
+
+- **API debugging**: "hit this endpoint", "call the API", "check the response", "find the bug in the response"
+- **Log analysis**: "check the logs", "what errors", "read access.log", "debug the 500s"
+- **Test runs**: "run the tests", "check if tests pass", "test suite output"
+- **Git history**: "show recent commits", "git log", "what changed", "diff between branches"
+- **Data inspection**: "look at the CSV", "parse the JSON", "analyze the config"
+- **Infrastructure**: "list containers", "check pods", "S3 buckets", "show running services"
+- **Dependency audit**: "check dependencies", "outdated packages", "security audit"
+- **Build output**: "build the project", "check for warnings", "compile errors"
+- **Code metrics**: "count lines", "find TODOs", "function count", "analyze codebase"
+- **Web docs lookup**: "look up the docs", "check the API reference", "find examples"
+
+## Language Selection
+
+| Situation | Language | Why |
+|-----------|----------|-----|
+| HTTP/API calls, JSON | `javascript` | Native fetch, JSON.parse, async/await |
+| Data analysis, CSV, stats | `python` | csv, statistics, collections, re |
+| Shell commands with pipes | `shell` | grep, awk, jq, native tools |
+| File pattern matching | `shell` | find, wc, sort, uniq |
 
 ## Critical Rules
 
-1. **Always print/log output.** The tool captures stdout. No output = empty summary.
-2. **Use `summary_prompt`** to guide what the LLM extracts from the output.
-3. **Set appropriate `timeout_ms`** — network calls need 15000+, file ops need 5000+.
-4. **Print structured data** — JSON.stringify or formatted tables summarize better.
-5. **Don't use for < 20 lines** — Bash is simpler and wastes no LLM call.
+1. **Always console.log/print your findings.** stdout is all that enters context. No output = wasted call.
+2. **Write analysis code, not just data dumps.** Don't `console.log(JSON.stringify(data))` — analyze first, print findings.
+3. **Be specific in output.** Print bug details with IDs, line numbers, exact values — not just counts.
+4. **For files you need to EDIT**: Use the normal Read tool. context-mode is for analysis, not editing.
+5. **For tiny outputs (<5 lines guaranteed)**: Use Bash. Don't over-engineer `git status` through context-mode.
 
-## Examples by Language
+## Examples
 
-### JavaScript: API response analysis
+### Debug an API endpoint
 ```javascript
-const resp = await fetch('https://api.example.com/status');
-const data = await resp.json();
-console.log(JSON.stringify(data, null, 2));
+const resp = await fetch('http://localhost:3000/api/orders');
+const { orders } = await resp.json();
+
+const bugs = [];
+const negQty = orders.filter(o => o.quantity < 0);
+if (negQty.length) bugs.push(`Negative qty: ${negQty.map(o => o.id).join(', ')}`);
+
+const nullFields = orders.filter(o => !o.product || !o.customer);
+if (nullFields.length) bugs.push(`Null fields: ${nullFields.map(o => o.id).join(', ')}`);
+
+console.log(`${orders.length} orders, ${bugs.length} bugs found:`);
+bugs.forEach(b => console.log(`- ${b}`));
 ```
-> summary_prompt: "Report service health, any degraded components, and error rates"
 
-### Python: Log analysis
-```python
-import re
-with open('/var/log/app.log') as f:
-    errors = [l for l in f if 'ERROR' in l]
-for e in errors[-50:]:
-    print(e.strip())
-print(f"\nTotal errors: {len(errors)}")
+### Analyze test output
+```shell
+npm test 2>&1
+echo "EXIT=$?"
 ```
-> summary_prompt: "Categorize errors by type and report frequency of each"
 
-### Shell: Build output filtering
+### Check GitHub PRs
 ```shell
-npm run build 2>&1
-echo "EXIT_CODE=$?"
+gh pr list --json number,title,state,reviewDecision --jq '.[] | "\(.number) [\(.state)] \(.title) — \(.reviewDecision // "no review")"'
+```
+
+### Read and analyze a large file
+```python
+# FILE_CONTENT is pre-loaded by execute_file
+import json
+data = json.loads(FILE_CONTENT)
+print(f"Records: {len(data)}")
+# ... analyze and print findings
 ```
-> summary_prompt: "Report success/failure, list any errors or warnings with file locations"
 
-## Anti-Patterns (Avoid These)
+## Anti-Patterns
 
-- Using `execute` for `git status` (small output — use Bash)
-- Forgetting `console.log()` / `print()` (produces empty summary)
-- Setting `timeout_ms: 5000` for network requests (will timeout)
-- Loading a 10K-line file into context then asking to summarize (use execute instead)
+- Using `curl http://api/endpoint` via Bash → 50KB floods context. Use `execute` with fetch instead.
+- Using `cat large-file.json` via Bash → entire file in context. Use `execute_file` instead.
+- Using `gh pr list` via Bash → raw JSON in context. Use `execute` with `--jq` filter instead.
+- Piping Bash output through `| head -20` → you lose the rest. Use `execute` to analyze ALL data and print summary.
+- Running `npm test` via Bash → full test output in context. Use `execute` to capture and summarize.
 
 ## Reference Files