Context Mode: The MCP Server That Solves Claude Code's Context Bloat

Core Sandbox Tools

Utility Tools

How the Sandbox Works

Scripts run in isolated subprocesses. The subprocess captures stdout, and only that enters the conversation context. Raw data — log files, API responses, snapshots — never leaves the sandbox.

Supported runtimes: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R, and Elixir. Bun is auto-detected for 3-5x faster JS/TS execution.

Intent-driven filtering: When output exceeds 5 KB and an intent is provided, Context Mode:

1. Indexes full output into FTS5 knowledge base
2. Searches for sections matching the intent
3. Returns only relevant matches
4. Provides vocabulary of searchable terms for follow-up queries

Storage

BM25 ranking scores documents based on:

• Term frequency
• Inverse document frequency
• Document length normalization

Porter stemming is applied at index time so “running”, “runs”, and “ran” match the same stem. Titles and headings are weighted 5x in BM25 scoring.

Three-Layer Fuzzy Search

Layer 1 is tried first. If no results, Layer 2 activates. If still no results, Layer 3 corrects typos and retries.

Smart Snippets

Instead of truncating to first N characters, Context Mode finds where query terms appear and returns windows around those matches with heading context, preserving code blocks intact.

Progressive Throttling

Prevents the model from exhausting the knowledge base in a single turn:

• Calls 1-3: Normal results (2 per query)
• Calls 4-8: Reduced results (1 per query) + warning
• Calls 9+: Blocked — redirects to ctx_batch_execute

Source Scoping

Search can target a specific indexed source, so React docs don’t interfere with API references.

Event Capture

Context Mode captures 15 event categories in per-project SQLite:

How Sessions Survive Compaction

1
PreCompact fires
2
  → Read all session events from SQLite
3
  → Build priority-tiered XML snapshot (≤2 KB)
4
  → Store snapshot in session_resume table
5

6
SessionStart fires (source: "compact")
7
  → Retrieve stored snapshot
8
  → Write structured events file → auto-indexed into FTS5
9
  → Build Session Guide with 15 categories
10
  → Inject <session_knowledge> directive into context

Lower-priority events (intent, MCP tool counts) are dropped first if the 2 KB budget is tight. Critical state (files, tasks, rules, decisions) is always preserved.

Session Guide Categories

After compaction, the model receives a structured narrative:

• Last Request — user’s last prompt, so the model continues without asking “what were we doing?”
• Tasks — checkbox format with completion status ([x] completed, [ ] pending)
• Key Decisions — user corrections and preferences
• Files Modified — all files touched during session
• Unresolved Errors — errors that haven’t been fixed
• Git — operations performed (checkout, commit, push, status)
• Project Rules — CLAUDE.md / GEMINI.md / AGENTS.md paths
• MCP Tools Used — tool names with call counts
• Subagent Tasks — delegated work summaries
• Skills Used — slash commands invoked
• Environment — working directory, env variables
• Data References — large data pasted during session
• Session Intent — mode classification (implement, investigate, review)
• User Role — behavioral directives set during session

Routing Enforcement

Hook enforcement is critical: One unrouted Playwright snapshot (56 KB) can wipe an entire session’s savings. Without hooks, compliance is ~60%. With hooks, ~98%.

Claude Code (recommended)

1
/plugin marketplace add mksglu/context-mode
2
/plugin install context-mode@context-mode

Restart Claude Code. Includes: MCP server, hooks (PreToolUse, PostToolUse, PreCompact, SessionStart), CLAUDE.md routing, slash commands (/ctx-stats, /ctx-doctor, /ctx-upgrade).

Verify: /context-mode:ctx-doctor — all checks should show [x].

OpenCode

Add to opencode.json in your project root:

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "mcp": {
4
    "context-mode": {
5
      "type": "local",
6
      "command": ["context-mode"]
7
    }
8
  },
9
  "plugin": ["context-mode"]
10
}

The plugin entry enables TypeScript hooks via tool.execute.before, tool.execute.after, and experimental.session.compacting.

Gemini CLI

Add to ~/.gemini/settings.json:

1
{
2
  "mcpServers": {
3
    "context-mode": {
4
      "command": "context-mode"
5
    }
6
  },
7
  "hooks": {
8
    "BeforeTool": [
9
      {
10
        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode",
11
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
12
      }
13
    ],
14
    "AfterTool": [
15
      {
16
        "matcher": "",
17
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]
18
      }
19
    ],
20
    "PreCompress": [
21
      {
22
        "matcher": "",
23
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli precompress" }]
24
      }
25
    ],
26
    "SessionStart": [
27
      {
28
        "matcher": "",
29
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]
30
      }
31
    ]
32
  }
33
}

Restart Gemini CLI after editing. Verify: /mcp list — you should see context-mode: ... - Connected.

VS Code Copilot

Create .vscode/mcp.json in your project root:

1
{
2
  "servers": {
3
    "context-mode": {
4
      "command": "context-mode"
5
    }
6
  }
7
}

Create .github/hooks/context-mode.json for hooks:

1
{
2
  "hooks": {
3
    "PreToolUse": [
4
      { "type": "command", "command": "context-mode hook vscode-copilot pretooluse" }
5
    ],
6
    "PostToolUse": [
7
      { "type": "command", "command": "context-mode hook vscode-copilot posttooluse" }
8
    ],
9
    "SessionStart": [
10
      { "type": "command", "command": "context-mode hook vscode-copilot sessionstart" }
11
    ]
12
  }
13
}

Restart VS Code.

Cline (VS Code Extension)

1. Open VS Code Settings > search “cline.mcpServers”
2. Add to settings.json:

1
{
2
  "cline.mcpServers": [
3
    {
4
      "name": "context-mode",
5
      "command": "context-mode"
6
    }
7
  ]
8
}

Cline doesn’t support hooks. Sandbox tools work for context savings, but session continuity requires manual management.