context-mode 0.9.21 → 1.0.0

package/build/truncate.js

@@ -0,0 +1,157 @@
+/**
+ * truncate — Pure string and output truncation utilities for context-mode.
+ *
+ * These helpers are used by both the core ContentStore (chunking) and the
+ * PolyglotExecutor (smart output truncation). They are extracted here so
+ * SessionDB and any other future consumer can import them without pulling
+ * in the full store or executor.
+ */
+// ─────────────────────────────────────────────────────────
+// String truncation
+// ─────────────────────────────────────────────────────────
+/**
+ * Truncate a string to at most `maxChars` characters, appending an ellipsis
+ * when truncation occurs.
+ *
+ * @param str     - Input string.
+ * @param maxChars - Maximum character count (inclusive). Must be >= 3.
+ * @returns The original string if short enough, otherwise a truncated string
+ *          ending with "...".
+ */
+export function truncateString(str, maxChars) {
+    if (str.length <= maxChars)
+        return str;
+    return str.slice(0, Math.max(0, maxChars - 3)) + "...";
+}
+// ─────────────────────────────────────────────────────────
+// Byte-aware smart truncation (head + tail)
+// ─────────────────────────────────────────────────────────
+/**
+ * Smart truncation that keeps the head (60%) and tail (40%) of output,
+ * preserving both initial context and final error messages.
+ * Snaps to line boundaries and handles UTF-8 safely via `Buffer.byteLength`.
+ *
+ * Used by PolyglotExecutor to cap stdout/stderr before returning to context.
+ *
+ * @param raw - Raw output string.
+ * @param maxBytes - Soft cap in bytes. Output below this threshold is returned as-is.
+ * @returns The original string if within budget, otherwise head + separator + tail.
+ */
+export function smartTruncate(raw, maxBytes) {
+    if (Buffer.byteLength(raw) <= maxBytes)
+        return raw;
+    const lines = raw.split("\n");
+    // Budget: 60% head, 40% tail (errors/results are usually at the end)
+    const headBudget = Math.floor(maxBytes * 0.6);
+    const tailBudget = maxBytes - headBudget;
+    // Collect head lines
+    const headLines = [];
+    let headBytes = 0;
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line) + 1; // +1 for \n
+        if (headBytes + lineBytes > headBudget)
+            break;
+        headLines.push(line);
+        headBytes += lineBytes;
+    }
+    // Collect tail lines (from end)
+    const tailLines = [];
+    let tailBytes = 0;
+    for (let i = lines.length - 1; i >= headLines.length; i--) {
+        const lineBytes = Buffer.byteLength(lines[i]) + 1;
+        if (tailBytes + lineBytes > tailBudget)
+            break;
+        tailLines.unshift(lines[i]);
+        tailBytes += lineBytes;
+    }
+    const skippedLines = lines.length - headLines.length - tailLines.length;
+    const skippedBytes = Buffer.byteLength(raw) - headBytes - tailBytes;
+    const separator = `\n\n... [${skippedLines} lines / ${(skippedBytes / 1024).toFixed(1)}KB truncated` +
+        ` — showing first ${headLines.length} + last ${tailLines.length} lines] ...\n\n`;
+    return headLines.join("\n") + separator + tailLines.join("\n");
+}
+// ─────────────────────────────────────────────────────────
+// JSON truncation
+// ─────────────────────────────────────────────────────────
+/**
+ * Serialize a value to JSON, then truncate the result to `maxBytes` bytes.
+ * If truncation occurs, the string is cut at a UTF-8-safe boundary and
+ * "... [truncated]" is appended. The result is NOT guaranteed to be valid
+ * JSON after truncation — it is suitable only for display/logging.
+ *
+ * @param value    - Any JSON-serializable value.
+ * @param maxBytes - Maximum byte length of the returned string.
+ * @param indent   - JSON indentation spaces (default 2). Pass 0 for compact.
+ */
+export function truncateJSON(value, maxBytes, indent = 2) {
+    const serialized = JSON.stringify(value, null, indent) ?? "null";
+    if (Buffer.byteLength(serialized) <= maxBytes)
+        return serialized;
+    // Find the largest character slice that stays within maxBytes once encoded.
+    // Buffer.byteLength is O(n) but we only call it once per truncation.
+    const marker = "... [truncated]";
+    const markerBytes = Buffer.byteLength(marker);
+    const budget = maxBytes - markerBytes;
+    // Binary-search for the right character count — avoids O(n²) scanning.
+    let lo = 0;
+    let hi = serialized.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (Buffer.byteLength(serialized.slice(0, mid)) <= budget) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return serialized.slice(0, lo) + marker;
+}
+// ─────────────────────────────────────────────────────────
+// XML / HTML escaping
+// ─────────────────────────────────────────────────────────
+/**
+ * Escape a string for safe embedding in an XML or HTML attribute or text node.
+ * Replaces the five XML-reserved characters: `&`, `<`, `>`, `"`, `'`.
+ *
+ * Used by the resume snapshot template builder to embed user content in
+ * `<tool_response>` and `<user_message>` XML tags without breaking the
+ * structured prompt format.
+ */
+export function escapeXML(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+// ─────────────────────────────────────────────────────────
+// maxBytes guard
+// ─────────────────────────────────────────────────────────
+/**
+ * Return `str` unchanged if it fits within `maxBytes`, otherwise return a
+ * byte-safe slice with an ellipsis appended. Useful for single-value fields
+ * (e.g., tool response strings) where head+tail splitting is not needed.
+ *
+ * @param str      - Input string.
+ * @param maxBytes - Hard byte cap.
+ */
+export function capBytes(str, maxBytes) {
+    if (Buffer.byteLength(str) <= maxBytes)
+        return str;
+    const marker = "...";
+    const markerBytes = Buffer.byteLength(marker);
+    const budget = maxBytes - markerBytes;
+    let lo = 0;
+    let hi = str.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (Buffer.byteLength(str.slice(0, mid)) <= budget) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return str.slice(0, lo) + marker;
+}

package/build/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * types — Shared type definitions for context-mode packages.
+ *
+ * Contains interfaces that are genuinely shared between the core (ContentStore,
+ * PolyglotExecutor) and the session domain (SessionDB, event extraction).
+ * Import from "./types.js".
+ */
+/** Tool call representation used during event extraction from Claude messages. */
+export interface ToolCall {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolResponse?: string;
+    isError?: boolean;
+}
+/** User message representation used during event extraction. */
+export interface UserMessage {
+    content: string;
+    timestamp?: string;
+}
+/**
+ * Session event as stored in SessionDB.
+ * Each event captures a discrete unit of session activity (tool use, user
+ * message, assistant response summary, etc.) for later resume-snapshot
+ * reconstruction.
+ */
+export interface SessionEvent {
+    type: string;
+    category: string;
+    data: string;
+    priority: number;
+    data_hash: string;
+}
+/**
+ * Result returned by PolyglotExecutor after running a code snippet.
+ * Shared here so SessionDB can record execution outcomes without importing
+ * the full executor module.
+ */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+    /** Process was detached and continues running in the background. */
+    backgrounded?: boolean;
+}
+/**
+ * Result returned after indexing content into the knowledge base.
+ * Shared so session tooling can record what was indexed without importing
+ * ContentStore.
+ */
+export interface IndexResult {
+    sourceId: number;
+    label: string;
+    totalChunks: number;
+    codeChunks: number;
+}
+/**
+ * A single search result returned from FTS5 BM25-ranked lookup.
+ * Shared for consumers that display or log results outside of ContentStore.
+ */
+export interface SearchResult {
+    title: string;
+    content: string;
+    source: string;
+    rank: number;
+    contentType: "code" | "prose";
+    matchLayer?: "porter" | "trigram" | "fuzzy";
+    highlighted?: string;
+}
+/**
+ * Aggregate statistics for a ContentStore instance.
+ */
+export interface StoreStats {
+    sources: number;
+    chunks: number;
+    codeChunks: number;
+}
+/**
+ * Structured representation of a session resume snapshot, suitable for
+ * injecting into a new conversation as context. Generated from stored
+ * SessionEvents by the snapshot builder.
+ */
+export interface ResumeSnapshot {
+    /** ISO-8601 timestamp of when the snapshot was generated. */
+    generatedAt: string;
+    /** Human-readable summary of the session to this point. */
+    summary: string;
+    /** Ordered list of events selected for the snapshot (priority-filtered). */
+    events: SessionEvent[];
+}
+/**
+ * Priority levels for SessionEvent records. Higher numbers are more important
+ * and are retained when the snapshot budget is tight.
+ */
+export declare const EventPriority: {
+    readonly LOW: 1;
+    readonly NORMAL: 2;
+    readonly HIGH: 3;
+    readonly CRITICAL: 4;
+};
+export type EventPriorityLevel = (typeof EventPriority)[keyof typeof EventPriority];

package/build/types.js

@@ -0,0 +1,20 @@
+/**
+ * types — Shared type definitions for context-mode packages.
+ *
+ * Contains interfaces that are genuinely shared between the core (ContentStore,
+ * PolyglotExecutor) and the session domain (SessionDB, event extraction).
+ * Import from "./types.js".
+ */
+// ─────────────────────────────────────────────────────────
+// Priority constants
+// ─────────────────────────────────────────────────────────
+/**
+ * Priority levels for SessionEvent records. Higher numbers are more important
+ * and are retained when the snapshot budget is tight.
+ */
+export const EventPriority = {
+    LOW: 1,
+    NORMAL: 2,
+    HIGH: 3,
+    CRITICAL: 4,
+};

package/configs/claude-code/CLAUDE.md

@@ -0,0 +1,62 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
+Instead use:
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` is intercepted and replaced with an error message. Do NOT retry with Bash.
+Instead use:
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch — BLOCKED
+WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead.
+Instead use:
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Bash (>20 lines output)
+Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### Read (for analysis)
+If you are reading a file to **Edit** it → Read is correct (Edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context. The raw file content stays in the sandbox.
+
+### Grep (large results)
+Grep results can flood context. Use `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Subagent routing
+
+When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |

package/configs/codex/AGENTS.md

@@ -0,0 +1,58 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session. Codex CLI does NOT have hooks, so these instructions are your ONLY enforcement mechanism. Follow them strictly.
+
+## BLOCKED commands — do NOT use these
+
+### curl / wget — FORBIDDEN
+Do NOT use `curl` or `wget` in any shell command. They dump raw HTTP responses directly into your context window.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `mcp__context-mode__ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — FORBIDDEN
+Do NOT run inline HTTP calls via `node -e "fetch(..."`, `python -c "requests.get(..."`, or similar patterns. They bypass the sandbox and flood context.
+Instead use:
+- `mcp__context-mode__ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### Direct web fetching — FORBIDDEN
+Do NOT use any direct URL fetching tool. Raw HTML can exceed 100 KB.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Shell (>20 lines output)
+Shell is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `mcp__context-mode__ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `mcp__context-mode__ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### File reading (for analysis)
+If you are reading a file to **edit** it → reading is correct (edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `mcp__context-mode__ctx_execute_file(path, language, code)` instead. Only your printed summary enters context. The raw file stays in the sandbox.
+
+### grep / search (large results)
+Search results can flood context. Use `mcp__context-mode__ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `mcp__context-mode__ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `mcp__context-mode__ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `mcp__context-mode__ctx_execute(language, code)` | `mcp__context-mode__ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `mcp__context-mode__ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `upgrade` MCP tool, run the returned shell command, display as checklist |

package/configs/codex/config.toml

@@ -0,0 +1,5 @@
+# Codex CLI — context-mode MCP server configuration
+# Add this to ~/.codex/config.toml
+
+[mcp_servers.context-mode]
+command = "context-mode"

package/configs/gemini-cli/GEMINI.md

@@ -0,0 +1,58 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any shell command containing `curl` or `wget` will be intercepted and blocked. Do NOT retry.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `mcp__context-mode__ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any shell command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` will be intercepted and blocked. Do NOT retry with shell.
+Instead use:
+- `mcp__context-mode__ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch / web browsing — BLOCKED
+Direct web fetching is blocked. Use the sandbox equivalent.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Shell (>20 lines output)
+Shell is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `mcp__context-mode__ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `mcp__context-mode__ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### read_file (for analysis)
+If you are reading a file to **edit** it → read_file is correct (edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `mcp__context-mode__ctx_execute_file(path, language, code)` instead. Only your printed summary enters context.
+
+### grep / search (large results)
+Search results can flood context. Use `mcp__context-mode__ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `mcp__context-mode__ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `mcp__context-mode__ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `mcp__context-mode__ctx_execute(language, code)` | `mcp__context-mode__ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `mcp__context-mode__ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `upgrade` MCP tool, run the returned shell command, display as checklist |

package/configs/gemini-cli/mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "context-mode": {
+      "command": "context-mode"
+    }
+  }
+}

package/configs/gemini-cli/settings.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://raw.githubusercontent.com/google-gemini/gemini-cli/main/packages/core/src/schema/settings-schema.json",
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "context-mode hook gemini-cli beforetool"
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "context-mode hook gemini-cli aftertool"
+          }
+        ]
+      }
+    ],
+    "PreCompress": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "context-mode hook gemini-cli precompress"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "context-mode hook gemini-cli sessionstart"
+          }
+        ]
+      }
+    ]
+  }
+}

package/configs/opencode/AGENTS.md

@@ -0,0 +1,58 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any shell command containing `curl` or `wget` will be intercepted and blocked by the context-mode plugin. Do NOT retry.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `mcp__context-mode__ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any shell command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` will be intercepted and blocked. Do NOT retry with shell.
+Instead use:
+- `mcp__context-mode__ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### Direct web fetching — BLOCKED
+Do NOT use any direct URL fetching tool. Use the sandbox equivalent.
+Instead use:
+- `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Shell (>20 lines output)
+Shell is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `mcp__context-mode__ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `mcp__context-mode__ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### File reading (for analysis)
+If you are reading a file to **edit** it → reading is correct (edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `mcp__context-mode__ctx_execute_file(path, language, code)` instead. Only your printed summary enters context.
+
+### grep / search (large results)
+Search results can flood context. Use `mcp__context-mode__ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `mcp__context-mode__ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `mcp__context-mode__ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `mcp__context-mode__ctx_execute(language, code)` | `mcp__context-mode__ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `mcp__context-mode__ctx_fetch_and_index(url, source)` then `mcp__context-mode__ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `mcp__context-mode__ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `upgrade` MCP tool, run the returned shell command, display as checklist |

package/configs/opencode/opencode.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context-mode": {
+      "type": "local",
+      "command": ["context-mode"]
+    }
+  },
+  "plugin": ["context-mode"]
+}

package/configs/vscode-copilot/copilot-instructions.md

@@ -0,0 +1,58 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any terminal command containing `curl` or `wget` will be intercepted and blocked. Do NOT retry.
+Instead use:
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any terminal command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` will be intercepted and blocked. Do NOT retry with terminal.
+Instead use:
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch / fetch — BLOCKED
+Direct web fetching tools are blocked. Use the sandbox equivalent.
+Instead use:
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Terminal / run_in_terminal (>20 lines output)
+Terminal is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### read_file (for analysis)
+If you are reading a file to **edit** it → read_file is correct (edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context.
+
+### grep / search (large results)
+Search results can flood context. Use `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |