context-mode 0.5.10 → 0.5.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "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,21 @@ 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.
+│
+├── 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 +77,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 +131,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 +173,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 +247,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