context-mode 0.5.10 → 0.5.13

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.10",
+      "version": "0.5.13",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.10",
+  "version": "0.5.13",
   "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",
@@ -21,8 +21,8 @@
   ],
   "mcpServers": {
     "context-mode": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/build/server.js"]
+      "command": "npx",
+      "args": ["-y", "context-mode"]
     }
   },
   "skills": "./skills/"

package/.mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "context-mode": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/build/server.js"]
+      "command": "npx",
+      "args": ["-y", "context-mode"]
     }
   }
 }

package/README.md

@@ -1,410 +1,175 @@
 # Context Mode
 
-**Claude Code MCP plugin that saves 98% of your context window.**
+**Stop losing context to large outputs.**
 
-Every tool call in Claude Code consumes context tokens. A single Playwright snapshot burns 10K-135K tokens. A Context7 docs lookup dumps 4K-10K tokens. GitHub's `list_commits` with 30 results costs 29K-64K tokens. With 5+ MCP servers active, you lose ~55K tokens before your first message — and after 30 minutes of real debugging, responses slow to a crawl.
+[![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)
 
-Context Mode intercepts these operations, processes data in isolated subprocesses, and returns only what matters.
+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.
 
-## The Problem: MCP Context Bloat
-
-Claude Code has a 200K token context window. Here's how fast popular MCP servers eat through it:
-
-| MCP Server | Tool | Without Context Mode | With Context Mode | Savings | Source |
-|---|---|---|---|---|---|
-| **Playwright** | `browser_snapshot` | 10K-135K tokens | ~75 tokens | **99%** | [playwright-mcp#1233](https://github.com/microsoft/playwright-mcp/issues/1233) |
-| **Context7** | `query-docs` | 4K-10K tokens | ~65 tokens | **98%** | [upstash/context7](https://github.com/upstash/context7) |
-| **GitHub** | `list_commits` (30) | 29K-64K tokens | ~180 tokens | **99%** | [github-mcp-server#142](https://github.com/github/github-mcp-server/issues/142) |
-| **Sentry** | issue analysis | 5K-30K tokens | ~85 tokens | **99%** | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp) |
-| **Supabase** | schema queries | 2K-30K tokens | ~80 tokens | **99%** | [supabase-community/supabase-mcp](https://github.com/supabase-community/supabase-mcp) |
-| **Firecrawl** | `scrape` / `crawl` | 5K-50K+ tokens | ~65 tokens | **99%** | [firecrawl](https://github.com/mendableai/firecrawl) |
-| **Chrome DevTools** | DOM / network | 5K-50K+ tokens | ~75 tokens | **99%** | Community benchmark |
-| **Fetch** | `fetch` | 5K-50K tokens | ~65 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.
-
-**Vercel's finding** ([December 2025](https://www.anthropic.com/engineering/advanced-tool-use)): Removing 80% of tools resulted in 3.5x faster execution, 37% fewer tokens, and 100% success rate (up from 80%).
+```
+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
 
-## Before / After
+Total: 166 KB = 42K tokens gone               Total: 1.8 KB = ~450 tokens
+```
 
-| What you're doing | Without Context Mode | With Context Mode | Savings |
-|---|---|---|---|
-| Playwright `browser_snapshot` | 56 KB into context | 299 B summary | **99%** |
-| Context7 `query-docs` (React) | 5.9 KB raw docs | 261 B summary | **96%** |
-| GitHub issues (20) | 59 KB JSON response | 1.1 KB summary | **98%** |
-| Read `access.log` (500 req) | 45 KB raw log | 155 B status breakdown | **100%** |
-| `vitest` (30 suites) | 6 KB raw output | 337 B pass/fail | **95%** |
-| Git log (153 commits) | 12 KB raw log | 107 B summary | **99%** |
-| Analytics CSV (500 rows) | 86 KB raw data | 222 B summary | **100%** |
+## Install
 
-**Real aggregate across 14 scenarios: 315 KB raw → 5.4 KB context (98% savings)**
+```bash
+claude mcp add context-mode -- npx -y context-mode
+```
 
-## Quick Start
+Restart Claude Code. Done. You now have 5 tools that intercept large outputs and return only what matters.
 
-### Option 1: Claude Code Plugin (Recommended)
+<details>
+<summary><strong>Plugin install</strong> (includes auto-routing skill)</summary>
 
 ```bash
 /plugin marketplace add mksglu/claude-context-mode
 /plugin install context-mode@claude-context-mode
 ```
 
-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
-
-```bash
-claude mcp add context-mode -- npx -y context-mode
-```
+Installs the MCP server + a skill that automatically guides Claude to route large outputs through Context Mode. No prompting needed.
 
-Restart Claude Code. 5 tools are now available.
+</details>
 
-### Option 3: Local Development
+<details>
+<summary><strong>Local development</strong></summary>
 
 ```bash
 claude --plugin-dir ./path/to/context-mode
 ```
 
-## Tools
-
-### `execute` — Run Code in Sandbox
-
-Execute code in 10 languages: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R. Only stdout enters context — raw data stays in the subprocess.
+</details>
 
-```
-Claude calls: execute({ language: "shell", code: "gh pr list --json title,state | jq length" })
-Returns: "3"                  ← 2 bytes instead of 8KB JSON
-```
+## What It Does
 
-**Intent-driven search** (v0.5.2): When you provide an `intent` parameter and output exceeds 5KB, Context Mode uses score-based BM25 search to return only the relevant sections matching your intent.
+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.
 
-```
-Claude calls: execute({
-  language: "shell",
-  code: "cat /var/log/app.log",
-  intent: "connection refused database error"
-})
-Returns: section titles + searchable terms (500B) ← instead of 100KB raw log
-```
+**Result:** 315 KB raw data becomes 5.4 KB of context across 14 real scenarios — **98% savings**.
 
-When intent search runs, the response includes `Searchable terms` — distinctive vocabulary
-extracted from the output via IDF scoring. Use these terms for targeted follow-up `search()` calls.
+| 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% |
 
-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.
+## Tools
 
-### `execute_file` — Process Files Without Loading
+### `execute` — Run code in 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.
+Execute code in 10 languages (JS, TS, Python, Shell, Ruby, Go, Rust, PHP, Perl, R). Only stdout enters context.
 
 ```
-Claude calls: execute_file({ path: "access.log", language: "python", code: "..." })
-Returns: "200: 312 | 404: 89 | 500: 14"     ← 30 bytes instead of 45KB
+execute({ language: "shell", code: "gh pr list --json title,state | jq length" })
+→ "3"                                           ← 2 bytes instead of 8KB
 ```
 
-### `index` — Build Searchable Knowledge Base
-
-Chunks markdown by headings, keeps code blocks intact, stores in ephemeral FTS5 database with BM25 ranking.
+Add `intent` for large outputs — Context Mode filters to relevant sections automatically:
 
 ```
-Claude calls: index({ content: <60KB React docs>, source: "React useEffect" })
-Returns: "Indexed 33 sections (15 with code)"     ← 40 bytes
+execute({ language: "shell", code: "cat app.log", intent: "database connection error" })
+→ matching sections + searchable terms           ← 500B instead of 100KB
 ```
 
-### `search` — Retrieve Exact Content
-
-BM25 full-text search with Porter stemming. Returns exact code blocks — not summaries.
-
-```
-Claude calls: search({ query: "useEffect cleanup function" })
-Returns: exact code example with heading context     ← 500 bytes instead of 60KB
-```
+Authenticated CLIs work out of the box — `gh`, `aws`, `gcloud`, `kubectl`, `docker` credentials pass through. Bun auto-detected for 3-5x faster JS/TS.
 
-### `fetch_and_index` — Fetch & Index URLs
+### `execute_file` — Process files without loading
 
-Fetches URL in subprocess, converts HTML to markdown, indexes into FTS5. Raw content never enters context.
+File contents stay in the sandbox as `FILE_CONTENT`. Your code summarizes. Only the summary enters context.
 
 ```
-Claude calls: fetch_and_index({ url: "https://react.dev/reference/react/useEffect" })
-Returns: "Indexed 33 sections (15 with code)"     ← 40 bytes instead of 60KB
+execute_file({ path: "access.log", language: "python", code: "..." })
+→ "200: 312 | 404: 89 | 500: 14"                ← 30 bytes instead of 45KB
 ```
 
-Use instead of WebFetch or Context7 when you need documentation — index once, search many times.
-
-## How It Works
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│ Without Context Mode                                             │
-│                                                                  │
-│ Claude Code → Playwright snapshot → 56KB into context            │
-│ Claude Code → Context7 docs      →  6KB into context             │
-│ Claude Code → gh pr list         →  6KB into context             │
-│ Claude Code → cat access.log     → 45KB into context             │
-│                                                                  │
-│ Total: 113KB consumed = ~29,000 tokens = 14% of context gone     │
-└──────────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────────┐
-│ With Context Mode                                                │
-│                                                                  │
-│ Claude Code → fetch_and_index(url)  → "Indexed 8 sections" (50B)│
-│ Claude Code → search("snapshot")    → exact element       (500B) │
-│ Claude Code → execute("gh pr list") → "5 PRs, +59 -0"    (719B)│
-│ Claude Code → execute_file(log)     → "500:13, 404:13"    (155B)│
-│                                                                  │
-│ Total: 1.4KB consumed = ~350 tokens = 0.18% of context           │
-└──────────────────────────────────────────────────────────────────┘
-```
+### `index` + `search` — Searchable knowledge base
 
-## Architecture
+Index documentation into FTS5 with BM25 ranking. Search returns exact code blocks — not summaries.
 
 ```
-┌─────────────┐    stdio / JSON-RPC     ┌──────────────────────────────┐
-│             │ ◄──────────────────────► │  Context Mode MCP Server     │
-│ Claude Code │    tool calls/results    │                              │
-│             │                          │  ┌────────────────────────┐  │
-└─────────────┘                          │  │ PolyglotExecutor       │  │
-                                         │  │ • 10 language runtimes │  │
-                                         │  │ • Sandboxed subprocess │  │
-                                         │  │ • Auth passthrough     │  │
-                                         │  │ • Intent-driven search │  │
-                                         │  └────────────────────────┘  │
-                                         │                              │
-                                         │  ┌────────────────────────┐  │
-                                         │  │ ContentStore           │  │
-                                         │  │ • SQLite FTS5          │  │
-                                         │  │ • BM25 ranking         │  │
-                                         │  │ • Porter stemming      │  │
-                                         │  │ • Heading-aware chunks │  │
-                                         │  │ • Vocabulary hints     │  │
-                                         │  └────────────────────────┘  │
-                                         └──────────────────────────────┘
-```
-
-### Sandbox Isolation
+index({ content: <60KB React docs>, source: "React useEffect" })
+→ "Indexed 33 sections (15 with code)"           ← 40 bytes
 
-Each `execute` call spawns an isolated subprocess with:
-
-- **Isolated temp directory** per execution — scripts can't access each other
-- **Real HOME** — so `gh`, `aws`, `gcloud` find their auth configs
-- **Auth passthrough** — GH_TOKEN, AWS credentials, KUBECONFIG, Docker, npm tokens, XDG paths
-- **Clean environment** — PATH, LANG, NO_COLOR, Python unbuffered mode
-
-### FTS5 Knowledge Base
-
-The `index` and `search` tools use SQLite FTS5 with BM25 ranking:
-
-```sql
-CREATE VIRTUAL TABLE chunks USING fts5(
-  title,                        -- heading hierarchy, weighted 2x
-  content,                      -- section text + code blocks
-  source_id UNINDEXED,
-  content_type UNINDEXED,       -- "code" or "prose"
-  tokenize='porter unicode61'   -- stemming + unicode support
-);
-
-SELECT title, content, bm25(chunks, 2.0, 1.0) AS rank
-FROM chunks
-WHERE chunks MATCH ?
-ORDER BY rank LIMIT 3;
+search({ query: "useEffect cleanup function" })
+→ exact code example with heading context        ← 500 bytes instead of 60KB
 ```
 
-**Chunking algorithm:**
-- Splits on H1-H4 headings and `---` separators
-- Tracks heading hierarchy: `"React > Hooks > useEffect > Cleanup"`
-- Keeps code blocks intact — never splits mid-block
-- Marks chunks as `code` or `prose` for content-type filtering
-- Porter stemming: "connecting" matches "connect", "connection", "connected"
-
-**Lazy singleton:** Database created only when `index` or `search` is first called — zero overhead for sessions that don't use it.
+### `fetch_and_index` — Fetch URLs into knowledge base
 
-### Intent-Driven Search (v0.5.2)
-
-When `execute` or `execute_file` is called with an `intent` parameter and output exceeds 5KB, Context Mode uses score-based BM25 search to return only the relevant sections:
-
-- **Score-based search**: Searches ALL intent words independently, ranks chunks by match count
-- **Searchable terms**: Distinctive vocabulary hints extracted via IDF scoring, helping you craft precise follow-up `search()` calls
-- **Smarter chunk titles**: Uses the first content line of each chunk instead of generic "Section N" labels
+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.
 
 ```
-Without intent:
-  stdout (100KB) → full output enters context
-
-With intent:
-  stdout (100KB) → chunk by lines → in-memory FTS5 → score all intent words → top chunks + searchable terms
-  Result: only what you need enters context, plus vocabulary for targeted follow-ups
+fetch_and_index({ url: "https://react.dev/reference/react/useEffect" })
+→ "Indexed 33 sections (15 with code)"           ← 40 bytes instead of 60KB
 ```
 
-**31% to 100% recall on real-world CHANGELOG test** — the score-based approach finds every relevant section, not just those matching a single query string.
-
-Tested across 5 real-world scenarios:
-
-| Scenario | Without Intent | With Intent | Size Reduction |
-|---|---|---|---|
-| Server log error (line 347/500) | error lost in output | **found** | 1.5 KB vs 5.0 KB |
-| 3 test failures among 200 tests | only 2/3 visible | **all 3 found** | 2.4 KB vs 5.0 KB |
-| 2 build warnings among 300 lines | both lost in output | **both found** | 2.1 KB vs 5.0 KB |
-| API auth error (line 743/1000) | error lost in output | **found** | 1.2 KB vs 4.9 KB |
-| Semantic gap (CHANGELOG search) | 31% recall | **100% recall** | Full coverage |
-
-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):
-
-1. Strip `<script>`, `<style>`, `<nav>`, `<header>`, `<footer>`
-2. Convert `<h1>`-`<h4>` to `#`-`####` markdown headings
-3. Convert `<pre><code>` to fenced code blocks with language detection
-4. Convert `<a>`, `<li>`, `<p>`, `<br>`, `<hr>` to markdown
-5. Decode HTML entities (`&amp;`, `&lt;`, `&nbsp;`, etc.)
-6. Collapse excessive whitespace
-
-## Benchmarks
-
-### Real MCP Ecosystem Comparison
-
-Tested with tools from popular MCP servers and Claude Code workflows:
-
-| Scenario | Tool | Raw | Context | Savings |
-|---|---|---|---|---|
-| Playwright page snapshot | `execute` | 56.2 KB | 299 B | **99%** |
-| Context7 React docs | `execute` | 5.9 KB | 261 B | **96%** |
-| Context7 Next.js docs | `execute` | 6.5 KB | 249 B | **96%** |
-| Context7 Tailwind docs | `execute` | 4.0 KB | 186 B | **95%** |
-| GitHub Issues (20) | `execute` | 58.9 KB | 1.1 KB | **98%** |
-| GitHub PR list (5) | `execute` | 6.4 KB | 719 B | **89%** |
-| Access log (500 req) | `execute_file` | 45.1 KB | 155 B | **100%** |
-| Analytics CSV (500 rows) | `execute_file` | 85.5 KB | 222 B | **100%** |
-| MCP tools manifest (40 tools) | `execute_file` | 17.0 KB | 742 B | **96%** |
-| Test output (30 suites) | `execute` | 6.0 KB | 337 B | **95%** |
-| Git log (153 commits) | `execute` | 11.6 KB | 107 B | **99%** |
-
-### Session Impact
-
-Typical 45-minute debugging session:
-
-| Metric | Without | With | Delta |
-|---|---|---|---|
-| Context consumed | 315 KB | 5.4 KB | **-98%** |
-| Tokens used | ~80,600 | ~1,400 | **-98%** |
-| Context remaining | 60% | 99% | **+39pp** |
-| Time before slowdown | ~30 min | ~3 hours | **+6x** |
-
-## Tool Decision Matrix
-
-| Data Type | Best Tool | Why |
-|---|---|---|
-| Web documentation | `fetch_and_index` → `search` | Index once, search many times |
-| MCP tool output (large) | `index` → `search` | Keep raw output out of context |
-| Log files | `execute_file` | Aggregate stats |
-| Test output | `execute_file` | Pass/fail summary |
-| CSV / JSON data | `execute_file` | Computed metrics |
-| Git / GitHub operations | `execute` | `gh`, `git` commands with auth |
-| Cloud CLI | `execute` | `aws`, `gcloud`, `kubectl` with auth |
-| Build output | `execute` | Error counts and warnings |
-| 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
+Just ask naturally — Claude routes through Context Mode automatically when it saves tokens.
 
 ```
 "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"
+"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"
 ```
 
-### 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"
-```
+## Real-World Benchmarks
 
-### Documentation Lookup
+| 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%** |
 
-```
-"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"
-```
+[Full benchmark data with 21 scenarios →](BENCHMARK.md)
 
-### Cloud & Infrastructure
+## How It Works
 
 ```
-"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"
+┌─────────────┐    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       │
+                                         └─────────────────────────────────┘
 ```
 
+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.
+
 ## Requirements
 
 - **Node.js 18+**
 - **Claude Code** with MCP support
-
-### Auto-Detected Runtimes
-
-| Runtime | Used For | Speed |
-|---|---|---|
-| Bun (optional) | JS/TS execution | 3-5x faster than Node |
-| Python 3 | Python code | Standard |
-| Ruby, Go, Rust, PHP, Perl, R | Respective languages | Standard |
-
-## Test Suite
-
-100+ tests across 4 suites:
-
-| Suite | Tests | Coverage |
-|---|---|---|
-| Executor | 55 | 10 languages, sandbox, output handling, concurrency, timeouts |
-| ContentStore | 40 | FTS5 schema, BM25 ranking, chunking, stemming, plain text indexing |
-| Intent Search | 5 | Intent-driven search across 5 real-world scenarios (incl. semantic gap) |
-| MCP Integration | 24 | JSON-RPC protocol, all 5 tools, fetch_and_index, errors |
+- Optional: Bun (auto-detected, 3-5x faster JS/TS)
 
 ## Development
 
 ```bash
 git clone https://github.com/mksglu/claude-context-mode.git
-cd claude-context-mode
-npm install
-npm run build
-npm test              # executor (55 tests)
-npm run test:store    # FTS5/BM25 (40 tests)
-npm run test:all      # all suites (100+ tests)
+cd claude-context-mode && npm install
+npm test              # 100+ tests across 4 suites
+npm run test:all      # full suite
 ```
 
 ## License

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.10";
+const VERSION = "0.5.13";
 const runtimes = detectRuntimes();
 const available = getAvailableLanguages(runtimes);
 const server = new McpServer({

package/build/store.js

@@ -49,7 +49,7 @@ export class ContentStore {
     #db;
     constructor(dbPath) {
         const path = dbPath ?? join(tmpdir(), `context-mode-${process.pid}.db`);
-        this.#db = new Database(path);
+        this.#db = new Database(path, { timeout: 5000 });
         this.#db.pragma("journal_mode = WAL");
         this.#db.pragma("synchronous = NORMAL");
         this.#initSchema();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.10",
+  "version": "0.5.13",
   "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",

package/skills/context-mode/SKILL.md

@@ -1,54 +1,21 @@
 ---
 name: context-mode
 description: |
-  Use context-mode tools (execute, execute_file, fetch_and_index, index, search) instead of
-  Bash/curl/cat when processing large outputs. The cost of routing through context-mode is near zero,
-  but flooding context with 50KB+ of raw data is catastrophic.
-
-  Use when the user's intent involves ANY of these categories (and similar variations):
-
-  Documentation & APIs: fetch docs, look up docs, check API reference, find examples,
-  index documentation, search docs, read the changelog, check release notes.
-
-  Logs & Debugging: analyze logs, check logs, debug errors, find 500s, trace requests,
-  inspect error output, review stack traces.
-
-  Testing: run tests, check test results, test suite output, coverage report.
-
-  Version Control: git history, recent commits, what changed, diff between branches,
-  commit log, blame, changelog analysis.
-
-  Data Processing: parse JSON, parse CSV, analyze output, summarize output, process data,
-  filter results, extract patterns, transform data, count occurrences.
-
-  Infrastructure & Containers: list containers, container resource usage, container stats,
-  container memory, container CPU, pod status, service health, deployment status,
-  cluster info, orchestration state, compose services.
-
-  System & Processes: running processes, system resource usage, disk usage, memory usage,
-  network connections, open ports, file descriptors, system load.
-
-  Package & Dependency Management: list dependencies, outdated packages, dependency tree,
-  installed packages, audit vulnerabilities, license check.
-
-  Database: list databases, show tables, describe schema, explain query, query results.
-
-  Cloud & DevOps: cloud resources, storage buckets, compute instances, cloud functions,
-  DNS records, SSL certificates, CDN status, CI/CD pipeline output.
-
-  Code Analysis: count lines, find TODOs, analyze codebase, security audit, code metrics,
-  find patterns, codebase statistics.
-
-  API Endpoints: hit endpoint, call API, check response, test endpoint, API debugging.
-
-  Browser & UI Inspection: page snapshot, browser snapshot, extract elements, DOM structure,
-  page accessibility tree, inspect page, page elements, form fields, UI components,
-  screenshot analysis, web page structure, HTML elements, element selectors.
-
-  MCP Tool Output Routing: ANY large output from Playwright, Context7, GitHub API,
-  Sentry, or other MCP tools should be routed through index → search.
-
-  Or ANY operation where output might exceed 20 lines.
+  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",
+  "extract elements", "page snapshot", "browser snapshot", "take a snapshot",
+  "DOM structure", "inspect page", "form fields", "element selectors",
+  "web page structure", "accessibility tree", "Playwright snapshot",
+  "run tests", "test output", "coverage report", "git log", "recent commits",
+  "diff between branches", "list containers", "pod status", "disk usage",
+  "fetch docs", "API reference", "index documentation", "hit endpoint",
+  "call API", "check response", "query results", "show tables",
+  "find TODOs", "count lines", "codebase statistics", "security audit",
+  "outdated packages", "dependency tree", "cloud resources", "CI/CD output".
+  Also triggers on ANY MCP tool output (Playwright, Context7, GitHub API) that
+  may exceed 20 lines, and any operation where output size is uncertain.
 ---
 
 # Context Mode: Default for All Large Output
@@ -77,8 +44,30 @@ About to run a command / read a file / call an API?
 ├── Fetching web documentation or HTML page?
 │   └── Use fetch_and_index → search
 │
-├── Processing output from another MCP tool (Playwright, Context7, etc.)?
-│   └── Use index → search
+├── Using Playwright (navigate, snapshot, console, network)?
+│   └── ALWAYS use filename parameter to save to file, then:
+│       browser_snapshot(filename) → index(path) or execute_file(path)
+│       browser_console_messages(filename) → execute_file(path)
+│       browser_network_requests(filename) → execute_file(path)
+│       ⚠ browser_navigate returns a snapshot automatically — ignore it,
+│         use browser_snapshot(filename) for any inspection.
+│       ⚠ Playwright MCP uses a SINGLE browser instance — NOT parallel-safe.
+│         For parallel browser ops, use agent-browser via execute instead.
+│
+├── Using agent-browser (parallel-safe browser automation)?
+│   └── Run via execute (shell) — each call gets its own subprocess:
+│       execute("agent-browser open example.com && agent-browser snapshot -i -c")
+│       ✓ Supports sessions for isolated browser instances
+│       ✓ Safe for parallel subagent execution
+│       ✓ Lightweight accessibility tree with ref-based interaction
+│
+├── Processing output from another MCP tool (Context7, GitHub API, etc.)?
+│   ├── Output already in context from a previous tool call?
+│   │   └── Use it directly. Do NOT re-index with index(content: ...).
+│   ├── Need to search the output multiple times?
+│   │   └── Save to file via execute, then index(path) → search
+│   └── One-shot extraction?
+│       └── Save to file via execute, then execute_file(path)
 │
 └── Reading a file to analyze/summarize (not edit)?
     └── Use execute_file (file loads into FILE_CONTENT, not context)
@@ -97,7 +86,11 @@ About to run a command / read a file / call an API?
 | 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 |
+| Playwright snapshot | `browser_snapshot(filename)` → `index(path)` → `search` | Save to file, index server-side, query |
+| Playwright snapshot (one-shot) | `browser_snapshot(filename)` → `execute_file(path)` | Save to file, extract in sandbox |
+| Playwright console/network | `browser_*(filename)` → `execute_file(path)` | Save to file, analyze in sandbox |
+| MCP output (already in context) | Use directly | Don't re-index — it's already loaded |
+| MCP output (need multi-query) | `execute` to save → `index(path)` → `search` | Save to file first, index server-side |
 
 ## Automatic Triggers
 
@@ -147,6 +140,9 @@ Use context-mode for ANY of these, without being asked:
 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.
+6. **Never use `index(content: large_data)`.** Use `index(path: ...)` to read files server-side. The `content` parameter sends data through context as a tool parameter — use it only for small inline text.
+7. **Always use `filename` parameter** on Playwright tools (`browser_snapshot`, `browser_console_messages`, `browser_network_requests`). Without it, the full output enters context.
+8. **Don't re-index data already in context.** If an MCP tool returned data in a previous response, it's already loaded — use it directly or save to file first.
 
 ## Examples
 
@@ -186,6 +182,73 @@ print(f"Records: {len(data)}")
 # ... analyze and print findings
 ```
 
+## Browser & Playwright Integration
+
+**When a task involves Playwright snapshots, screenshots, or page inspection, ALWAYS route through file → sandbox.**
+
+Playwright `browser_snapshot` returns 10K–135K tokens of accessibility tree data. Calling it without `filename` dumps all of that into context. Passing the output to `index(content: ...)` sends it into context a SECOND time as a parameter. Both are wrong.
+
+**The key insight**: `browser_snapshot` has a `filename` parameter that saves to file instead of returning to context. `index` has a `path` parameter that reads files server-side. `execute_file` processes files in a sandbox. **None of these touch context.**
+
+### Workflow A: Snapshot → File → Index → Search (multiple queries)
+
+```
+Step 1: browser_snapshot(filename: "/tmp/playwright-snapshot.md")
+        → saves to file, returns ~50B confirmation (NOT 135K tokens)
+
+Step 2: index(path: "/tmp/playwright-snapshot.md", source: "Playwright snapshot")
+        → reads file SERVER-SIDE, indexes into FTS5, returns ~80B confirmation
+
+Step 3: search("login form email password", source: "Playwright")
+        → returns only matching chunks (~300B)
+```
+
+**Total context: ~430B** instead of 270K tokens. Real 99% savings.
+
+### Workflow B: Snapshot → File → Execute File (one-shot extraction)
+
+```
+Step 1: browser_snapshot(filename: "/tmp/playwright-snapshot.md")
+        → saves to file, returns ~50B confirmation
+
+Step 2: execute_file(path: "/tmp/playwright-snapshot.md", language: "javascript", code: "
+          const links = [...FILE_CONTENT.matchAll(/- link \"([^\"]+)\"/g)].map(m => m[1]);
+          const buttons = [...FILE_CONTENT.matchAll(/- button \"([^\"]+)\"/g)].map(m => m[1]);
+          const inputs = [...FILE_CONTENT.matchAll(/- textbox|- checkbox|- radio/g)];
+          console.log('Links:', links.length, '| Buttons:', buttons.length, '| Inputs:', inputs.length);
+          console.log('Navigation:', links.slice(0, 10).join(', '));
+        ")
+        → processes in sandbox, returns ~200B summary
+```
+
+**Total context: ~250B** instead of 135K tokens.
+
+### Workflow C: Console & Network (save to file if large)
+
+```
+browser_console_messages(level: "error", filename: "/tmp/console.md")
+→ execute_file(path: "/tmp/console.md", ...) or index(path: "/tmp/console.md", ...)
+
+browser_network_requests(includeStatic: false, filename: "/tmp/network.md")
+→ execute_file(path: "/tmp/network.md", ...) or index(path: "/tmp/network.md", ...)
+```
+
+### CRITICAL: Why `filename` + `path` is mandatory
+
+| Approach | Context cost | Correct? |
+|----------|-------------|----------|
+| `browser_snapshot()` → raw into context | **135K tokens** | NO |
+| `browser_snapshot()` → `index(content: raw)` | **270K tokens** (doubled!) | NO |
+| `browser_snapshot(filename)` → `index(path)` → `search` | **~430B** | YES |
+| `browser_snapshot(filename)` → `execute_file(path)` | **~250B** | YES |
+
+### Key Rule
+
+> **ALWAYS use `filename` parameter when calling `browser_snapshot`, `browser_console_messages`, or `browser_network_requests`.**
+> Then process via `index(path: ...)` or `execute_file(path: ...)` — never `index(content: ...)`.
+>
+> Data flow: **Playwright → file → server-side read → context**. Never: **Playwright → context → index(content) → context again**.
+
 ## Anti-Patterns
 
 - Using `curl http://api/endpoint` via Bash → 50KB floods context. Use `execute` with fetch instead.
@@ -193,6 +256,11 @@ print(f"Records: {len(data)}")
 - 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.
+- Calling `browser_snapshot()` WITHOUT `filename` parameter → 135K tokens flood context. **Always** use `browser_snapshot(filename: "/tmp/snap.md")`.
+- Calling `browser_console_messages()` or `browser_network_requests()` WITHOUT `filename` → entire output floods context. **Always** use the `filename` parameter.
+- Passing ANY large data to `index(content: ...)` → data enters context as a parameter. **Always** use `index(path: ...)` to read server-side. The `content` parameter should only be used for small inline text you're composing yourself.
+- Calling an MCP tool (Context7 `query-docs`, GitHub API, etc.) then passing the response to `index(content: response)` → **doubles** context usage. The response is already in context — use it directly or save to file first.
+- Ignoring `browser_navigate` auto-snapshot → navigation response includes a full page snapshot. Don't rely on it for inspection — call `browser_snapshot(filename)` separately.
 
 ## Reference Files