context-mode 0.6.0 → 0.6.1

package/.claude-plugin/hooks/hooks.json

@@ -1,13 +1,22 @@
 {
-  "description": "Context-mode tool routing — injects MCP tool instructions into subagent prompts",
+  "description": "Context-mode PreToolUse — intercepts Bash data-fetching and injects subagent routing",
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.sh"
+          }
+        ]
+      },
       {
         "matcher": "Task",
         "hooks": [
           {
             "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/task-inject.sh"
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.sh"
           }
         ]
       }

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -10,6 +10,8 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode-mcp/)
 
 Context Mode is an MCP server that sits between Claude Code and these outputs. **315 KB becomes 5.4 KB. 98% reduction.**
 
+https://github.com/user-attachments/assets/07013dbf-07c0-4ef1-974a-33ea1207637b
+
 ## Install
 
 ```bash
@@ -19,14 +21,14 @@ claude mcp add context-mode -- npx -y context-mode
 Restart Claude Code. Done.
 
 <details>
-<summary><strong>Plugin install</strong> (includes auto-routing skill)</summary>
+<summary><strong>Plugin install</strong> (includes auto-routing skill + subagent hook)</summary>
 
 ```bash
 /plugin marketplace add mksglu/claude-context-mode
 /plugin install context-mode@claude-context-mode
 ```
 
-Installs the MCP server + a skill that automatically routes large outputs through Context Mode. No prompting needed.
+Installs the MCP server + a skill that automatically routes large outputs through Context Mode + a PreToolUse hook that injects context-mode routing into subagent prompts. No prompting needed.
 
 </details>
 
@@ -51,11 +53,13 @@ Code Mode showed that tool definitions can be compressed by 99.9%. Context Mode
 
 | Tool | What it does | Context saved |
 |---|---|---|
+| `batch_execute` | Run multiple commands + search multiple queries in ONE call. | 986 KB → 62 KB |
 | `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 |
+| `search` | Query indexed content with multiple queries in one call. | On-demand retrieval |
 | `fetch_and_index` | Fetch URL, convert to markdown, index. | 60 KB → 40 B |
+| `stats` | Session token tracking with per-tool breakdown. | — |
 
 ## How the Sandbox Works
 
@@ -71,11 +75,46 @@ When output exceeds 5 KB and an `intent` is provided, Context Mode switches to i
 
 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.
 
-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.
+When you call `search`, it returns relevant content snippets focused around matching query terms — not full documents, not approximations, the actual indexed content with smart extraction around what you're looking for. `fetch_and_index` extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context.
+
+## Smart Snippets
+
+Search results use intelligent extraction instead of truncation. Instead of returning the first N characters (which might miss the important part), Context Mode finds where your query terms appear in the content and returns windows around those matches. If your query is "authentication JWT token", you get the paragraphs where those terms actually appear — not an arbitrary prefix.
+
+## Progressive Search Throttling
+
+The `search` tool includes progressive throttling to prevent context flooding from excessive individual calls:
+
+- **Calls 1-3:** Normal results (2 per query)
+- **Calls 4-8:** Reduced results (1 per query) + warning
+- **Calls 9+:** Blocked — redirects to `batch_execute`
+
+This encourages batching queries via `search(queries: ["q1", "q2", "q3"])` or `batch_execute` instead of making dozens of individual calls.
+
+## Session Stats
+
+The `stats` tool tracks context consumption in real-time. Useful for debugging context usage during long sessions.
+
+| Metric | Value |
+|---|---|
+| Session uptime | 2.6 min |
+| Tool calls | 5 |
+| Bytes returned to context | 62.0 KB (~15.9k tokens) |
+| Bytes indexed (stayed in sandbox) | 140.5 KB |
+| Context savings ratio | 2.3x (56% reduction) |
+
+| Tool | Calls | Context used |
+|---|---|---|
+| batch_execute | 4 | 58.2 KB |
+| search | 1 | 3.8 KB |
+
+## Subagent Routing
+
+When installed as a plugin, Context Mode includes a PreToolUse hook that automatically injects routing instructions into subagent (Task tool) prompts. Subagents learn to use `batch_execute` as their primary tool and `search(queries: [...])` for follow-ups — without any manual configuration.
 
 ## The Numbers
 
-Measured across 11 real-world scenarios. Every operation under 1 KB output.
+Measured across real-world scenarios:
 
 **Playwright snapshot** — 56.2 KB raw → 299 B context (99% saved)
 **GitHub Issues (20)** — 58.9 KB raw → 1.1 KB context (98% saved)
@@ -84,6 +123,7 @@ Measured across 11 real-world scenarios. Every operation under 1 KB output.
 **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)
+**Repo research (subagent)** — 986 KB raw → 62 KB context (94% saved, 5 calls vs 37)
 
 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%.
 
@@ -91,38 +131,38 @@ Over a full session: 315 KB of raw output becomes 5.4 KB. Session time before sl
 
 ## Try It
 
-These prompts work out of the box. Claude routes through Context Mode automatically.
+These prompts work out of the box. Run `/context-mode stats` after each to see the savings.
 
-**Git history analysis**
+**Deep repo research** — 5 calls, 62 KB context (raw: 986 KB, 94% saved)
 ```
-Clone https://github.com/modelcontextprotocol/servers and analyze its git history:
-top contributors, commit types (feat/fix/docs/chore), and busiest weeks.
+Research https://github.com/modelcontextprotocol/servers — architecture, tech stack,
+top contributors, open issues, and recent activity. Then run /context-mode stats.
 ```
 
-**Web page extraction**
+**Git history analysis** — 1 call, 5.6 KB context
 ```
-Fetch the Hacker News front page and extract: top 15 posts with titles, scores,
-comment counts, and domains. Group them by domain.
+Clone https://github.com/facebook/react and analyze the last 500 commits:
+top contributors, commit frequency by month, and most changed files.
+Then run /context-mode stats.
 ```
 
-**Documentation lookup**
+**Web scraping** — 1 call, 3.2 KB context
 ```
-Fetch the React useEffect docs and find the cleanup pattern.
+Fetch the Hacker News front page, extract all posts with titles, scores,
+and domains. Group by domain. Then run /context-mode stats.
 ```
 
-**Monorepo dependency audit**
+**Large JSON API** — 7.5 MB raw → 0.9 KB context (99% saved)
 ```
-Analyze package-lock.json: find the 10 largest dependencies,
-which packages share the most common deps, and the heaviest package by count.
+Create a local server that returns a 7.5 MB JSON with 20,000 records and a secret
+hidden at index 13000. Fetch the endpoint, find the hidden record, and show me
+exactly what's in it. Then run /context-mode stats.
 ```
 
-**Parallel browser + docs analysis**
+**Documentation search** — 2 calls, 1.8 KB context
 ```
-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.
+Fetch the React useEffect docs, index them, and find the cleanup pattern
+with code examples. Then run /context-mode stats.
 ```
 
 ## Requirements

package/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "description": "Context-mode PreToolUse — intercepts Bash data-fetching and injects subagent routing",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pretooluse.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Unified PreToolUse hook for context-mode
+# - Bash: blocks data-fetching commands (curl, wget, inline fetch)
+# - Task: injects context-mode routing into subagent prompts
+
+INPUT=$(cat /dev/stdin)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# ─── Bash: block data-fetching commands ───
+if [ "$TOOL" = "Bash" ]; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+  # curl/wget
+  if echo "$COMMAND" | grep -qiE '(^|\s|&&|\||\;)(curl|wget)\s'; then
+    cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "BLOCKED: curl/wget floods context window. Use context-mode execute instead.\n\nExample:\nmcp__context-mode__execute(language: \"javascript\", code: \"const resp = await fetch('http://...'); const data = await resp.json(); console.log(JSON.stringify(data, null, 2));\")\n\nThis runs in sandbox — only stdout enters context."
+}
+EOF
+    exit 0
+  fi
+
+  # inline fetch (node -e, python -c, etc.)
+  if echo "$COMMAND" | grep -qiE 'fetch\s*\(\s*['"'"'"](https?://|http)' || \
+     echo "$COMMAND" | grep -qiE 'requests\.(get|post|put)\s*\(' || \
+     echo "$COMMAND" | grep -qiE 'http\.(get|request)\s*\('; then
+    cat <<'EOF'
+{
+  "decision": "block",
+  "reason": "BLOCKED: Inline HTTP fetch via Bash floods context window. Use context-mode execute instead.\n\nExample:\nmcp__context-mode__execute(language: \"javascript\", code: \"const resp = await fetch('http://...'); const data = await resp.json(); console.log(JSON.stringify(data, null, 2));\")\n\nThis runs in sandbox — only stdout enters context."
+}
+EOF
+    exit 0
+  fi
+
+  # allow all other Bash commands
+  exit 0
+fi
+
+# ─── Task: inject context-mode routing into subagent prompts ───
+if [ "$TOOL" = "Task" ]; then
+  ROUTING_BLOCK='
+
+---
+CONTEXT WINDOW PROTECTION — USE CONTEXT-MODE MCP TOOLS
+
+Raw Bash/Read/WebFetch output floods your context. You have context-mode tools that keep data in sandbox.
+
+STEP 1 — GATHER: mcp__context-mode__batch_execute(commands, queries)
+  commands: [{label: "Name", command: "shell cmd"}, ...]
+  queries: ["query1", "query2", ...] — put 5-8 queries covering everything you need.
+  Runs all commands, indexes output, returns search results. ONE call, no follow-ups.
+
+STEP 2 — FOLLOW-UP: mcp__context-mode__search(queries: ["q1", "q2", "q3", ...])
+  Pass ALL follow-up questions as queries array. ONE call, not separate calls.
+
+OTHER: execute(language, code) | execute_file(path, language, code) | fetch_and_index(url) + search
+
+FORBIDDEN: Bash for output, Read for files, WebFetch. Bash is ONLY for git/mkdir/rm/mv.
+---'
+
+  echo "$INPUT" | jq --arg routing "$ROUTING_BLOCK" '{
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "updatedInput": (.tool_input + { "prompt": (.tool_input.prompt + $routing) })
+    }
+  }'
+  exit 0
+fi
+
+# Unknown tool — pass through
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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",
+    "hooks",
     "server.bundle.mjs",
     "skills",
     ".claude-plugin",