context-mode 0.4.0 → 0.4.1

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.4.1",
+      "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.4.1",
   "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
@@ -264,6 +271,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+**

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.4.1",
 });
 const executor = new PolyglotExecutor({ runtimes });
 // Lazy singleton — no DB overhead unless index/search is used

package/package.json

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