context-mode 0.4.0

package/build/store.js

@@ -0,0 +1,212 @@
+/**
+ * ContentStore — FTS5 BM25-based knowledge base for context-mode.
+ *
+ * Chunks markdown content by headings (keeping code blocks intact),
+ * stores in SQLite FTS5, and retrieves via BM25-ranked search.
+ *
+ * Use for documentation, API references, and any content where
+ * you need EXACT text later — not summaries.
+ */
+import Database from "better-sqlite3";
+import { readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// ─────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────
+function sanitizeQuery(query) {
+    const words = query
+        .replace(/['"(){}[\]*:^~]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 0 &&
+        !["AND", "OR", "NOT", "NEAR"].includes(w.toUpperCase()));
+    if (words.length === 0)
+        return '""';
+    return words.map((w) => `"${w}"`).join(" ");
+}
+// ─────────────────────────────────────────────────────────
+// ContentStore
+// ─────────────────────────────────────────────────────────
+export class ContentStore {
+    #db;
+    constructor(dbPath) {
+        const path = dbPath ?? join(tmpdir(), `context-mode-${process.pid}.db`);
+        this.#db = new Database(path);
+        this.#db.pragma("journal_mode = WAL");
+        this.#db.pragma("synchronous = NORMAL");
+        this.#initSchema();
+    }
+    // ── Schema ──
+    #initSchema() {
+        this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS sources (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        label TEXT NOT NULL,
+        chunk_count INTEGER NOT NULL DEFAULT 0,
+        code_chunk_count INTEGER NOT NULL DEFAULT 0,
+        indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
+        title,
+        content,
+        source_id UNINDEXED,
+        content_type UNINDEXED,
+        tokenize='porter unicode61'
+      );
+    `);
+    }
+    // ── Index ──
+    index(options) {
+        const { content, path, source } = options;
+        if (!content && !path) {
+            throw new Error("Either content or path must be provided");
+        }
+        const text = content ?? readFileSync(path, "utf-8");
+        const label = source ?? path ?? "untitled";
+        const chunks = this.#chunkMarkdown(text);
+        if (chunks.length === 0) {
+            const insertSource = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count) VALUES (?, 0, 0)");
+            const info = insertSource.run(label);
+            return {
+                sourceId: Number(info.lastInsertRowid),
+                label,
+                totalChunks: 0,
+                codeChunks: 0,
+            };
+        }
+        const codeChunks = chunks.filter((c) => c.hasCode).length;
+        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(label, chunks.length, codeChunks);
+            const sourceId = Number(info.lastInsertRowid);
+            for (const chunk of chunks) {
+                insertChunk.run(chunk.title, chunk.content, sourceId, chunk.hasCode ? "code" : "prose");
+            }
+            return sourceId;
+        });
+        const sourceId = transaction();
+        return {
+            sourceId,
+            label,
+            totalChunks: chunks.length,
+            codeChunks,
+        };
+    }
+    // ── Search ──
+    search(query, limit = 3) {
+        const sanitized = sanitizeQuery(query);
+        const stmt = this.#db.prepare(`
+      SELECT
+        chunks.title,
+        chunks.content,
+        chunks.content_type,
+        sources.label,
+        bm25(chunks, 2.0, 1.0) AS rank
+      FROM chunks
+      JOIN sources ON sources.id = chunks.source_id
+      WHERE chunks MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `);
+        const rows = stmt.all(sanitized, limit);
+        return rows.map((r) => ({
+            title: r.title,
+            content: r.content,
+            source: r.label,
+            rank: r.rank,
+            contentType: r.content_type,
+        }));
+    }
+    // ── Stats ──
+    getStats() {
+        const sources = this.#db.prepare("SELECT COUNT(*) as c FROM sources").get()?.c ?? 0;
+        const chunks = this.#db
+            .prepare("SELECT COUNT(*) as c FROM chunks")
+            .get()?.c ?? 0;
+        const codeChunks = this.#db
+            .prepare("SELECT COUNT(*) as c FROM chunks WHERE content_type = 'code'")
+            .get()?.c ?? 0;
+        return { sources, chunks, codeChunks };
+    }
+    // ── Cleanup ──
+    close() {
+        this.#db.close();
+    }
+    // ── Chunking ──
+    #chunkMarkdown(text) {
+        const chunks = [];
+        const lines = text.split("\n");
+        const headingStack = [];
+        let currentContent = [];
+        let currentHeading = "";
+        const flush = () => {
+            const joined = currentContent.join("\n").trim();
+            if (joined.length === 0)
+                return;
+            chunks.push({
+                title: this.#buildTitle(headingStack, currentHeading),
+                content: joined,
+                hasCode: currentContent.some((l) => /^`{3,}/.test(l)),
+            });
+            currentContent = [];
+        };
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            // Horizontal rule separator (Context7 uses long dashes)
+            if (/^[-_*]{3,}\s*$/.test(line)) {
+                flush();
+                i++;
+                continue;
+            }
+            // Heading (H1-H4)
+            const headingMatch = line.match(/^(#{1,4})\s+(.+)$/);
+            if (headingMatch) {
+                flush();
+                const level = headingMatch[1].length;
+                const heading = headingMatch[2].trim();
+                // Pop deeper levels from stack
+                while (headingStack.length > 0 &&
+                    headingStack[headingStack.length - 1].level >= level) {
+                    headingStack.pop();
+                }
+                headingStack.push({ level, text: heading });
+                currentHeading = heading;
+                currentContent.push(line);
+                i++;
+                continue;
+            }
+            // Code block — collect entire block as a unit
+            const codeMatch = line.match(/^(`{3,})(.*)?$/);
+            if (codeMatch) {
+                const fence = codeMatch[1];
+                const codeLines = [line];
+                i++;
+                while (i < lines.length) {
+                    codeLines.push(lines[i]);
+                    if (lines[i].startsWith(fence) && lines[i].trim() === fence) {
+                        i++;
+                        break;
+                    }
+                    i++;
+                }
+                currentContent.push(...codeLines);
+                continue;
+            }
+            // Regular line
+            currentContent.push(line);
+            i++;
+        }
+        // Flush remaining content
+        flush();
+        return chunks;
+    }
+    #buildTitle(headingStack, currentHeading) {
+        if (headingStack.length === 0) {
+            return currentHeading || "Untitled";
+        }
+        return headingStack.map((h) => h.text).join(" > ");
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "context-mode",
+  "version": "0.4.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",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "context-window",
+    "sandbox",
+    "code-execution",
+    "fts5",
+    "bm25"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mksglu/claude-context-mode"
+  },
+  "homepage": "https://github.com/mksglu/claude-context-mode#readme",
+  "bugs": "https://github.com/mksglu/claude-context-mode/issues",
+  "bin": {
+    "context-mode": "./build/server.js"
+  },
+  "files": [
+    "build",
+    "skills",
+    ".claude-plugin",
+    ".mcp.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "npx tsx src/server.ts",
+    "setup": "npx tsx src/cli.ts setup",
+    "doctor": "npx tsx src/cli.ts doctor",
+    "typecheck": "tsc --noEmit",
+    "test": "npx tsx tests/executor.test.ts",
+    "benchmark": "npx tsx tests/benchmark.ts",
+    "test:use-cases": "npx tsx tests/use-cases.ts",
+    "test:compare": "npx tsx tests/context-comparison.ts",
+    "test:ecosystem": "npx tsx tests/ecosystem-benchmark.ts",
+    "test:store": "npx tsx tests/store.test.ts",
+    "test:all": "npx tsx tests/executor.test.ts && npx tsx tests/store.test.ts && npx tsx tests/use-cases.ts && npx tsx tests/context-comparison.ts && npx tsx tests/benchmark.ts && npx tsx tests/ecosystem-benchmark.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "picocolors": "^1.1.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.19.11",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/context-mode/SKILL.md

@@ -0,0 +1,124 @@
+---
+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".
+---
+
+# Context Mode: execute & execute_file
+
+## When to Use (Decision Tree)
+
+```
+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` |
+
+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.
+
+## Language Selection Guide
+
+| 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 |
+
+## Usage Pattern
+
+### execute — inline code
+
+```
+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"
+```
+
+### 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"
+```
+
+## 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.
+
+## Examples by Language
+
+### JavaScript: API response analysis
+```javascript
+const resp = await fetch('https://api.example.com/status');
+const data = await resp.json();
+console.log(JSON.stringify(data, null, 2));
+```
+> 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)}")
+```
+> summary_prompt: "Categorize errors by type and report frequency of each"
+
+### Shell: Build output filtering
+```shell
+npm run build 2>&1
+echo "EXIT_CODE=$?"
+```
+> summary_prompt: "Report success/failure, list any errors or warnings with file locations"
+
+## Anti-Patterns (Avoid These)
+
+- 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)
+
+## Reference Files
+
+- [JavaScript/TypeScript Patterns](./references/patterns-javascript.md)
+- [Python Patterns](./references/patterns-python.md)
+- [Shell Patterns](./references/patterns-shell.md)
+- [Anti-Patterns & Common Mistakes](./references/anti-patterns.md)

package/skills/context-mode/references/anti-patterns.md

@@ -0,0 +1,257 @@
+# Anti-Patterns: Common Mistakes with execute / execute_file
+
+Avoid these pitfalls when using context-mode tools.
+
+---
+
+## 1. Using execute for Small Outputs (< 20 Lines)
+
+**Problem:** `execute` adds overhead (LLM summarization call). For small outputs, Bash is faster and cheaper.
+
+```
+BAD — wasteful use of execute:
+  Tool: execute
+  code: "echo $(node --version)"
+  language: shell
+
+GOOD — just use Bash:
+  Tool: Bash
+  command: node --version
+```
+
+**Rule:** If the output fits comfortably in your context window (under ~20 lines), use Bash directly. Reserve `execute` for outputs that would bloat context or need intelligent summarization.
+
+More examples of "just use Bash":
+- `git status` — usually 5-10 lines
+- `ls -la` — directory listing
+- `cat .env.example` — small config file
+- `pwd`, `whoami`, `which node`
+- `wc -l src/index.ts` — single line output
+
+---
+
+## 2. Forgetting to Print Output
+
+**Problem:** `execute` captures stdout. If your code doesn't print anything, the summary will be empty or meaningless.
+
+```javascript
+// BAD — no output:
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const deps = Object.keys(data.dependencies);
+// Nothing printed! The LLM sees empty stdout.
+
+// GOOD — explicit output:
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const deps = Object.keys(data.dependencies);
+console.log(`Dependencies (${deps.length}):`);
+deps.forEach(d => console.log(`  ${d}: ${data.dependencies[d]}`));
+```
+
+```python
+# BAD — computes but never prints:
+with open('data.json') as f:
+    data = json.load(f)
+result = [x for x in data if x['status'] == 'error']
+# result is lost — never printed
+
+# GOOD — always print results:
+with open('data.json') as f:
+    data = json.load(f)
+result = [x for x in data if x['status'] == 'error']
+print(f"Found {len(result)} errors:")
+for r in result:
+    print(f"  {r['id']}: {r['message']}")
+```
+
+**Rule:** Every `execute` script must end with print/console.log of the results you want summarized.
+
+---
+
+## 3. Using Bash When JS/Python Would Be Cleaner
+
+**Problem:** Complex data processing in Bash quickly becomes unreadable and error-prone.
+
+```shell
+# BAD — parsing JSON in Bash is fragile:
+cat data.json | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for item in data:
+    if item['status'] == 'error':
+        print(item['id'], item['message'])
+"
+# If you're already using Python inline, just use language: python
+```
+
+```javascript
+// GOOD — use the right language for the job:
+// language: javascript
+const data = require('./data.json');
+data.filter(x => x.status === 'error')
+    .forEach(x => console.log(`${x.id}: ${x.message}`));
+```
+
+**Rule:** If your Bash script contains inline Python/Node or complex `jq`/`awk` chains, switch to `language: python` or `language: javascript` instead.
+
+Signs you should switch from shell:
+- Using `python3 -c` or `node -e` inside the shell script
+- More than 3 pipes chained together
+- Using `jq` for complex JSON transformations
+- Nested loops in Bash
+- String manipulation beyond simple `cut`/`sed`
+
+---
+
+## 4. Loading Entire Files into Context Then Processing
+
+**Problem:** Reading a 10,000-line file with `Read` tool, then asking about it, wastes your entire context window. Use `execute` to process the file and return only the summary.
+
+```
+BAD workflow:
+  1. Read tool: read 'server.log' (10,000 lines loaded into context)
+  2. "Find all errors in this log"
+  → 10,000 lines consumed context for a question that needs ~20 lines of output
+
+GOOD workflow:
+  1. execute with language: python
+     code: |
+       with open('server.log') as f:
+           errors = [l for l in f if 'ERROR' in l]
+       print(f"Total errors: {len(errors)}")
+       for e in errors[-20:]:
+           print(e.strip())
+     summary_prompt: "Categorize errors and report frequency"
+  → Only the summary enters context
+```
+
+```
+BAD workflow:
+  1. Read tool: read 'package-lock.json' (20,000 lines)
+  2. "What version of lodash is installed?"
+
+GOOD workflow:
+  1. execute with language: javascript
+     code: |
+       const lock = require('./package-lock.json');
+       const find = (deps, name) => {
+         if (deps[name]) return deps[name].version;
+         for (const [, dep] of Object.entries(deps)) {
+           if (dep.dependencies) {
+             const v = find(dep.dependencies, name);
+             if (v) return v;
+           }
+         }
+       };
+       console.log(`lodash: ${find(lock.dependencies, 'lodash') || 'not found'}`);
+     summary_prompt: "Report the installed version of lodash"
+```
+
+**Rule:** If a file is over 200 lines and you only need specific data from it, use `execute` to extract what you need rather than reading the whole file into context.
+
+---
+
+## 5. Not Using JSON.stringify for Structured Output
+
+**Problem:** Printing objects without serialization gives `[object Object]` in JavaScript.
+
+```javascript
+// BAD — prints [object Object]:
+const pkg = require('./package.json');
+console.log(pkg.dependencies);
+// Output: [object Object]
+
+// GOOD — serialize properly:
+const pkg = require('./package.json');
+console.log(JSON.stringify(pkg.dependencies, null, 2));
+// Output: { "react": "^18.2.0", "next": "^14.0.0", ... }
+```
+
+```javascript
+// BAD — loses structure in arrays:
+const items = [{name: 'a', value: 1}, {name: 'b', value: 2}];
+console.log(items);
+// May print unhelpfully
+
+// GOOD — format as table:
+const items = [{name: 'a', value: 1}, {name: 'b', value: 2}];
+console.log('Name  | Value');
+console.log('------|------');
+items.forEach(i => console.log(`${i.name.padEnd(5)} | ${i.value}`));
+// Or use JSON.stringify:
+console.log(JSON.stringify(items, null, 2));
+```
+
+**Rule:** Always use `JSON.stringify(data, null, 2)` for objects/arrays in JavaScript, or format as a readable table. In Python, use `json.dumps(data, indent=2)` or `pprint.pprint(data)`.
+
+---
+
+## 6. Timeout Too Short for Network Operations
+
+**Problem:** Default timeout may be too short for API calls, builds, or test suites.
+
+```
+BAD — will timeout on API calls:
+  Tool: execute
+  code: |
+    const resp = await fetch('https://api.slow-service.com/data');
+    console.log(await resp.json());
+  language: javascript
+  timeout_ms: 5000  ← API may take 10+ seconds
+
+GOOD — generous timeout for network:
+  Tool: execute
+  code: |
+    const resp = await fetch('https://api.slow-service.com/data');
+    console.log(JSON.stringify(await resp.json(), null, 2));
+  language: javascript
+  timeout_ms: 30000  ← 30 seconds for network calls
+```
+
+**Recommended timeouts:**
+| Operation | timeout_ms |
+|-----------|-----------|
+| File reading/parsing | 5000 - 10000 |
+| Local computation | 10000 |
+| Single API request | 15000 - 30000 |
+| Paginated API calls | 30000 - 60000 |
+| npm install / build | 120000 |
+| Full test suite | 120000 - 300000 |
+
+**Rule:** Always consider what your script does and set `timeout_ms` accordingly. Network calls and builds need significantly more time than file operations.
+
+---
+
+## 7. Not Using summary_prompt Effectively
+
+**Problem:** Without a good `summary_prompt`, the LLM summarization may focus on irrelevant details.
+
+```
+BAD — vague or missing summary_prompt:
+  summary_prompt: "Summarize this"
+  → May focus on the wrong aspects
+
+GOOD — specific and actionable:
+  summary_prompt: "Report the count of failing tests, list each failure with its file path and error message, and identify any patterns in the failures"
+```
+
+**Tips for effective summary_prompt:**
+- Be specific about what data points you need
+- Ask for counts and metrics, not just descriptions
+- Request actionable insights ("suggest fixes", "identify patterns")
+- Mention the format you want ("list as bullet points", "group by category")
+
+---
+
+## Summary Checklist
+
+Before using `execute`, verify:
+
+- [ ] Output will be > 20 lines (otherwise use Bash)
+- [ ] Script prints all results to stdout
+- [ ] Objects are serialized with JSON.stringify / json.dumps
+- [ ] Timeout matches the operation type
+- [ ] Language matches the task (JS for JSON/API, Python for data, Shell for pipes)
+- [ ] summary_prompt is specific and actionable
+- [ ] Not loading a file into context that could be processed inside execute