context-mode 0.5.20 → 0.5.23

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "0.5.20",
+      "version": "0.5.23",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.20",
+  "version": "0.5.23",
   "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 10 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",
@@ -33,7 +33,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "You have mcp__context-mode__execute and mcp__context-mode__execute_file available. If this Bash command could produce more than 20 lines of output (curl, npm test, git log, cat large files, API calls, docker/kubectl commands), use mcp__context-mode__execute instead — it processes output in a sandbox and only returns a summary to context. For small commands (git status, pwd, ls, echo) Bash is fine."
+            "prompt": "STOP. Default to mcp__context-mode__execute for ALL Bash commands. ONLY use Bash for these guaranteed-small-output operations: file mutations (mkdir, mv, cp, rm, touch, chmod), git writes (git add, git commit, git push, git checkout, git branch, git merge), navigation (cd, pwd, which), process control (kill, pkill), package management (npm install/publish, pip install), and simple echo/printf. Everything else — any command that reads, queries, fetches, lists, logs, tests, builds, diffs, inspects, or calls an external service — MUST use mcp__context-mode__execute instead. When uncertain, use context-mode."
           }
         ]
       }

package/README.md

@@ -1,21 +1,14 @@
 # Context Mode
 
-**Stop losing context to large outputs.**
+**The other half of the context problem.**
 
-[![npm](https://img.shields.io/npm/v/context-mode)](https://www.npmjs.com/package/context-mode) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/context-mode)](https://www.npmjs.com/package/context-mode) [![marketplace](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmksglu%2Fclaude-context-mode%2Fmain%2F.claude-plugin%2Fmarketplace.json&query=%24.plugins%5B0%5D.version&label=marketplace&color=brightgreen)](https://github.com/mksglu/claude-context-mode) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Run tests without burning 5K tokens. Query docs without loading raw HTML. Debug logs without reading 45KB of noise. Only summaries reach Claude — everything else stays in the sandbox.
+Every MCP tool call in Claude Code dumps raw data into your 200K context window. A Playwright snapshot costs 56 KB. Twenty GitHub issues cost 59 KB. One access log — 45 KB. After 30 minutes, 40% of your context is gone.
 
-```
-Without Context Mode                          With Context Mode
-─────────────────────                         ────────────────────
-Playwright snapshot → 56 KB into context      → 299 B summary
-GitHub issues (20)  → 59 KB into context      → 1.1 KB summary
-Access log (500)    → 45 KB into context      → 155 B summary
-Context7 docs       →  6 KB into context      → 261 B summary
-
-Total: 166 KB = 42K tokens gone               Total: 1.8 KB = ~450 tokens
-```
+Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode-mcp/) — which compresses tool definitions from millions of tokens into ~1,000 — we asked: what about the other direction?
+
+Context Mode is an MCP server that sits between Claude Code and these outputs. **315 KB becomes 5.4 KB. 98% reduction.**
 
 ## Install
 
@@ -23,7 +16,7 @@ Total: 166 KB = 42K tokens gone               Total: 1.8 KB = ~450 tokens
 claude mcp add context-mode -- npx -y context-mode
 ```
 
-Restart Claude Code. Done. You now have 5 tools that intercept large outputs and return only what matters.
+Restart Claude Code. Done.
 
 <details>
 <summary><strong>Plugin install</strong> (includes auto-routing skill)</summary>
@@ -33,7 +26,7 @@ Restart Claude Code. Done. You now have 5 tools that intercept large outputs and
 /plugin install context-mode@claude-context-mode
 ```
 
-Installs the MCP server + a skill that automatically guides Claude to route large outputs through Context Mode. No prompting needed.
+Installs the MCP server + a skill that automatically routes large outputs through Context Mode. No prompting needed.
 
 </details>
 
@@ -46,116 +39,91 @@ claude --plugin-dir ./path/to/context-mode
 
 </details>
 
-## What It Does
+## The Problem
 
-Every MCP tool call dumps raw data into your 200K context window. With [81+ tools active, 143K tokens (72%) get consumed before your first message](https://scottspence.com/posts/optimising-mcp-server-context-usage-in-claude-code). Context Mode intercepts these operations, processes data in isolated subprocesses, and returns only what you need.
+MCP has become the standard way for AI agents to use external tools. But there is a tension at its core: every tool interaction fills the context window from both sides — definitions on the way in, raw output on the way out.
 
-**Result:** 315 KB raw data becomes 5.4 KB of context across 14 real scenarios — **98% savings**.
+With [81+ tools active, 143K tokens (72%) get consumed before your first message](https://scottspence.com/posts/optimising-mcp-server-context-usage-in-claude-code). And then the tools start returning data. A single Playwright snapshot burns 56 KB. A `gh issue list` dumps 59 KB. Run a test suite, read a log file, fetch documentation — each response eats into what remains.
 
-| Metric | Without | With |
-|---|---|---|
-| Context consumed per session | 315 KB | 5.4 KB |
-| Time before slowdown | ~30 min | ~3 hours |
-| Context remaining after 45 min | 60% | 99% |
+Code Mode showed that tool definitions can be compressed by 99.9%. Context Mode applies the same principle to tool outputs — processing them in sandboxes so only summaries reach the model.
 
 ## Tools
 
-### `execute` — Run code in sandbox
+| Tool | What it does | Context saved |
+|---|---|---|
+| `execute` | Run code in 10 languages. Only stdout enters context. | 56 KB → 299 B |
+| `execute_file` | Process files in sandbox. Raw content never leaves. | 45 KB → 155 B |
+| `index` | Chunk markdown into FTS5 with BM25 ranking. | 60 KB → 40 B |
+| `search` | Query indexed content. Returns exact code blocks. | On-demand retrieval |
+| `fetch_and_index` | Fetch URL, convert to markdown, index. | 60 KB → 40 B |
 
-Execute code in 10 languages (JS, TS, Python, Shell, Ruby, Go, Rust, PHP, Perl, R). Only stdout enters context.
+## How the Sandbox Works
 
-```
-execute({ language: "shell", code: "gh pr list --json title,state | jq length" })
-→ "3"                                           ← 2 bytes instead of 8KB
-```
+Each `execute` call spawns an isolated subprocess with its own process boundary. Scripts can't access each other's memory or state. The subprocess runs your code, captures stdout, and only that stdout enters the conversation context. The raw data — log files, API responses, snapshots — never leaves the sandbox.
 
-Add `intent` for large outputs — Context Mode filters to relevant sections automatically:
+Ten language runtimes are available: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R. Bun is auto-detected for 3-5x faster JS/TS execution.
 
-```
-execute({ language: "shell", code: "cat app.log", intent: "database connection error" })
-→ matching sections + searchable terms           ← 500B instead of 100KB
-```
+Authenticated CLIs work through credential passthrough — `gh`, `aws`, `gcloud`, `kubectl`, `docker` inherit environment variables and config paths without exposing them to the conversation.
 
-Authenticated CLIs work out of the box — `gh`, `aws`, `gcloud`, `kubectl`, `docker` credentials pass through. Bun auto-detected for 3-5x faster JS/TS.
+When output exceeds 5 KB and an `intent` is provided, Context Mode switches to intent-driven filtering: it indexes the full output into the knowledge base, searches for sections matching your intent, and returns only the relevant matches with a vocabulary of searchable terms for follow-up queries.
 
-### `execute_file` — Process files without loading
+## How the Knowledge Base Works
 
-File contents stay in the sandbox as `FILE_CONTENT`. Your code summarizes. Only the summary enters context.
+The `index` tool chunks markdown content by headings while keeping code blocks intact, then stores them in a **SQLite FTS5** (Full-Text Search 5) virtual table. Search uses **BM25 ranking** — a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and document length normalization. **Porter stemming** is applied at index time so "running", "runs", and "ran" match the same stem.
 
-```
-execute_file({ path: "access.log", language: "python", code: "..." })
-→ "200: 312 | 404: 89 | 500: 14"                ← 30 bytes instead of 45KB
-```
+When you call `search`, it returns exact code blocks with their heading hierarchy — not summaries, not approximations, the actual indexed content. `fetch_and_index` extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context.
 
-### `index` + `search` — Searchable knowledge base
+## The Numbers
 
-Index documentation into FTS5 with BM25 ranking. Search returns exact code blocks — not summaries.
+Measured across 11 real-world scenarios. Every operation under 1 KB output.
 
-```
-index({ content: <60KB React docs>, source: "React useEffect" })
-→ "Indexed 33 sections (15 with code)"           ← 40 bytes
+**Playwright snapshot** — 56.2 KB raw → 299 B context (99% saved)
+**GitHub Issues (20)** — 58.9 KB raw → 1.1 KB context (98% saved)
+**Access log (500 requests)** — 45.1 KB raw → 155 B context (100% saved)
+**Context7 React docs** — 5.9 KB raw → 261 B context (96% saved)
+**Analytics CSV (500 rows)** — 85.5 KB raw → 222 B context (100% saved)
+**Git log (153 commits)** — 11.6 KB raw → 107 B context (99% saved)
+**Test output (30 suites)** — 6.0 KB raw → 337 B context (95% saved)
 
-search({ query: "useEffect cleanup function" })
-→ exact code example with heading context        ← 500 bytes instead of 60KB
-```
+Over a full session: 315 KB of raw output becomes 5.4 KB. Session time before slowdown goes from ~30 minutes to ~3 hours. Context remaining after 45 minutes: 99% instead of 60%.
 
-### `fetch_and_index` — Fetch URLs into knowledge base
+[Full benchmark data with 21 scenarios →](BENCHMARK.md)
+
+## Try It
 
-Fetches, converts HTML to markdown, indexes. Raw content never enters context. Use instead of WebFetch or Context7 when you need to reference docs multiple times.
+These prompts work out of the box. Claude routes through Context Mode automatically.
 
+**Git history analysis**
 ```
-fetch_and_index({ url: "https://react.dev/reference/react/useEffect" })
-→ "Indexed 33 sections (15 with code)"           ← 40 bytes instead of 60KB
+Clone https://github.com/modelcontextprotocol/servers and analyze its git history:
+top contributors, commit types (feat/fix/docs/chore), and busiest weeks.
 ```
 
-## Example Prompts
-
-Just ask naturally — Claude routes through Context Mode automatically when it saves tokens.
-
+**Web page extraction**
 ```
-"Analyze the last 50 commits and find the most frequently changed files"
-"Read the access log and break down requests by HTTP status code"
-"Run the test suite and give me a pass/fail summary"
-"Fetch the React useEffect docs and find the cleanup pattern"
-"List all Docker containers with their memory usage"
-"Find all TODO comments across the codebase"
-"Analyze package-lock.json and find the 10 largest dependencies"
-"Show running Kubernetes pods and their restart counts"
+Fetch the Hacker News front page and extract: top 15 posts with titles, scores,
+comment counts, and domains. Group them by domain.
 ```
 
-## Real-World Benchmarks
-
-| Operation | Raw | Context | Savings |
-|---|---|---|---|
-| Playwright `browser_snapshot` | 56.2 KB | 299 B | **99%** |
-| GitHub Issues (20) | 58.9 KB | 1.1 KB | **98%** |
-| Access log (500 requests) | 45.1 KB | 155 B | **100%** |
-| Context7 React docs | 5.9 KB | 261 B | **96%** |
-| Analytics CSV (500 rows) | 85.5 KB | 222 B | **100%** |
-| Git log (153 commits) | 11.6 KB | 107 B | **99%** |
-| Test output (30 suites) | 6.0 KB | 337 B | **95%** |
-
-[Full benchmark data with 21 scenarios →](BENCHMARK.md)
-
-## How It Works
+**Documentation lookup**
+```
+Fetch the React useEffect docs and find the cleanup pattern.
+```
 
+**Monorepo dependency audit**
 ```
-┌─────────────┐    stdio / JSON-RPC     ┌─────────────────────────────────┐
-│ Claude Code │ ◄─────────────────────► │  Context Mode MCP Server        │
-│             │    tool calls/results    │                                 │
-└─────────────┘                          │  Sandboxed subprocesses         │
-                                         │  • 10 language runtimes         │
-                                         │  • Auth passthrough (gh, aws…)  │
-                                         │  • Intent-driven search         │
-                                         │                                 │
-                                         │  SQLite FTS5 knowledge base     │
-                                         │  • BM25 ranking                 │
-                                         │  • Porter stemming              │
-                                         │  • Heading-aware chunking       │
-                                         └─────────────────────────────────┘
+Analyze package-lock.json: find the 10 largest dependencies,
+which packages share the most common deps, and the heaviest package by count.
 ```
 
-Each `execute` call spawns an isolated subprocess — scripts can't access each other, but authenticated CLIs (`gh`, `aws`, `gcloud`) find their configs through secure credential passthrough.
+**Parallel browser + docs analysis**
+```
+Run 3 parallel tasks:
+1. Navigate to news.ycombinator.com, take a snapshot, count all links and interactive elements
+2. Navigate to jsonplaceholder.typicode.com, extract all API endpoint paths and HTTP methods
+3. Fetch the Anthropic prompt caching docs, search for cache TTL and token pricing
+Present all findings in a comparison table.
+```
 
 ## Requirements
 
@@ -168,7 +136,7 @@ Each `execute` call spawns an isolated subprocess — scripts can't access each
 ```bash
 git clone https://github.com/mksglu/claude-context-mode.git
 cd claude-context-mode && npm install
-npm test              # 100+ tests across 4 suites
+npm test              # run tests
 npm run test:all      # full suite
 ```
 

package/build/server.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { PolyglotExecutor } from "./executor.js";
 import { ContentStore } from "./store.js";
 import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime, } from "./runtime.js";
-const VERSION = "0.5.20";
+const VERSION = "0.5.23";
 const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({

package/build/store.js

@@ -7,10 +7,21 @@
  * Use for documentation, API references, and any content where
  * you need EXACT text later — not summaries.
  */
-import Database from "better-sqlite3";
+import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+// Lazy-load better-sqlite3 — only when ContentStore is first used.
+// This lets the MCP server start instantly even if the native module
+// isn't installed yet (marketplace first-run scenario).
+let _Database = null;
+function loadDatabase() {
+    if (!_Database) {
+        const require = createRequire(import.meta.url);
+        _Database = require("better-sqlite3");
+    }
+    return _Database;
+}
 // ─────────────────────────────────────────────────────────
 // Constants
 // ─────────────────────────────────────────────────────────
@@ -48,6 +59,7 @@ function sanitizeQuery(query) {
 export class ContentStore {
     #db;
     constructor(dbPath) {
+        const Database = loadDatabase();
         const path = dbPath ?? join(tmpdir(), `context-mode-${process.pid}.db`);
         this.#db = new Database(path, { timeout: 5000 });
         this.#db.pragma("journal_mode = WAL");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.20",
+  "version": "0.5.23",
   "type": "module",
   "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution, FTS5 knowledge base, and intent-driven search.",
   "author": "Mert Koseoğlu",
@@ -27,6 +27,7 @@
   },
   "files": [
     "build",
+    "server.bundle.mjs",
     "skills",
     ".claude-plugin",
     ".mcp.json",
@@ -36,6 +37,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "bundle": "esbuild src/server.ts --bundle --platform=node --target=node18 --format=esm --outfile=server.bundle.mjs --external:better-sqlite3 --minify",
     "prepublishOnly": "npm run build",
     "dev": "npx tsx src/server.ts",
     "setup": "npx tsx src/cli.ts setup",
@@ -59,6 +61,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.19.11",
+    "esbuild": "^0.27.3",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0"
   }