Context Mode MCP

---
name: context-mode-mcp
description: Privacy-first MCP virtualization layer that sandboxes tool calls to save context window space and maintain session continuity across compaction
triggers:
  - "set up context mode"
  - "install context-mode MCP"
  - "reduce context window usage"
  - "sandbox MCP tool calls"
  - "session continuity after compaction"
  - "context-mode not routing tools"
  - "configure context mode hooks"
  - "optimize AI agent context"
---

# Context Mode MCP

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Context Mode is a privacy-first MCP server that acts as a virtualization layer between AI coding agents and their tools. It solves two problems: (1) raw tool output floods the context window (a Playwright snapshot = 56 KB, 20 GitHub issues = 59 KB), and (2) conversation compaction causes agents to forget session state. Context Mode sandboxes tool calls in subprocesses — raw data never enters context — and tracks all activity in local SQLite with FTS5 search for retrieval after compaction. Nothing leaves your machine; no telemetry, no cloud sync.

## Installation

### Claude Code (Full Plugin — Recommended)

/plugin marketplace add mksglu/context-mode

/plugin install context-mode@context-mode

Restart Claude Code. The plugin auto-installs:
- MCP server with 6 sandbox tools
- PreToolUse/PostToolUse/PreCompact/SessionStart hooks
- `CLAUDE.md` routing instructions in your project root
- Slash commands (`/context-mode:ctx-stats`, `/context-mode:ctx-doctor`, `/context-mode:ctx-upgrade`)

### Claude Code (MCP-only, no hooks)

claude mcp add context-mode -- npx -y context-mode

### Other Platforms (Global Install)

npm install -g context-mode

### Gemini CLI

Add to `~/.gemini/settings.json`:

{

"mcpServers": {

"context-mode": {

"command": "context-mode"

}

},

"hooks": {

"BeforeTool": [

{

"matcher": "",

"hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]

}

],

"AfterTool": [

{

"matcher": "",

"hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]

}

],

"SessionStart": [

{

"matcher": "",

"hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]

}

]

}

}

### VS Code Copilot

Create `.vscode/mcp.json`:

{

"servers": {

"context-mode": {

"command": "context-mode"

}

}

}

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

{

"hooks": {

"PreToolUse": [

{ "type": "command", "command": "context-mode hook vscode-copilot pretooluse" }

],

"PostToolUse": [

{ "type": "command", "command": "context-mode hook vscode-copilot posttooluse" }

],

"SessionStart": [

{ "type": "command", "command": "context-mode hook vscode-copilot sessionstart" }

]

}

}

### Cursor

Create `.cursor/mcp.json`:

{

"mcpServers": {

"context-mode": {

"command": "context-mode"

}

}

}

Create `.cursor/hooks.json`:

{

"version": 1,

"hooks": {

"preToolUse": [

{

"command": "context-mode hook cursor pretooluse",

"matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"

}

],

"postToolUse": [

{

"command": "context-mode hook cursor posttooluse"

}

]

}

}

### OpenCode

Add to `opencode.json` in project root:

{

"$schema": "https://opencode.ai/config.json",

"mcp": {

"context-mode": {

"type": "local",

"command": ["context-mode"]

}

},

"plugin": ["context-mode"]

}

## The 6 Sandbox MCP Tools

### `ctx_execute` — Run a shell command in sandbox

// Instead of: Bash("gh issue list --limit 20") → 59 KB in context

// Use:

ctx_execute({ command: "gh issue list --limit 20" })

// Returns: indexed summary + search handle, ~1.2 KB in context

### `ctx_execute_file` — Read and index a file in sandbox

// Instead of: Read("./logs/access.log") → 45 KB in context

// Use:

ctx_execute_file({ path: "./logs/access.log" })

// Returns: file summary + FTS5 index handle

### `ctx_batch_execute` — Run multiple commands, one context entry

ctx_batch_execute({

commands: [

"git log --oneline -20",

"git diff HEAD~1",

"git status"

]

})

// All three results indexed together, single small context entry

### `ctx_fetch_and_index` — Fetch a URL and sandbox the response

// Instead of: WebFetch("https://api.github.com/repos/owner/repo/issues")

// Use:

ctx_fetch_and_index({ url: "https://api.github.com/repos/owner/repo/issues" })

// Playwright snapshots, API responses, HTML — all sandboxed

### `ctx_index` — Manually index arbitrary content

ctx_index({

content: largeRawString,

label: "deployment-logs-2026-03-18"

})

// Stores in SQLite FTS5, returns search handle

### `ctx_search` — Query indexed content via BM25

ctx_search({

query: "authentication error 401",

limit: 5

})

// Returns top BM25-ranked results from current session's index

// This is how the agent recovers state after compaction

## Slash Commands (Claude Code Only)

| Command | Purpose |
|---|---|
| `/context-mode:ctx-stats` | Per-tool savings breakdown, tokens consumed, savings ratio |
| `/context-mode:ctx-doctor` | Diagnostics — runtimes, hooks, FTS5, plugin registration, versions |
| `/context-mode:ctx-upgrade` | Pull latest, rebuild, migrate cache, fix hooks |

On other platforms these work as MCP tools — just invoke `ctx stats`, `ctx doctor`, or `ctx upgrade` by name.

## Session Continuity Pattern

Context Mode tracks file edits, git operations, tasks, errors, and decisions in SQLite. After compaction:

1. The agent calls `ctx_search` with relevant keywords
2. BM25 ranking surfaces the most relevant prior events
3. The agent resumes without re-reading files or re-running commands

// After compaction — recovering state

ctx_search({ query: "currently editing authentication middleware" })

// Returns: last known file path, recent edits, pending tasks

ctx_search({ query: "unresolved errors last session" })

// Returns: error events with file/line context

**Session lifecycle:**
- `--continue` flag: resumes previous session, keeps SQLite data
- No `--continue`: previous session data is deleted immediately (fresh slate)

## Routing Instructions Auto-Management

On SessionStart, context-mode writes routing instructions to your project:

| Platform | File |
|---|---|
| Claude Code | `CLAUDE.md` |
| Gemini CLI | `GEMINI.md` |
| VS Code Copilot | `.github/copilot-instructions.md` |
| Cursor / Codex | Project root instruction file |

**Behavior is idempotent:**
- File missing → written fresh
- File exists, no context-mode rules → rules appended, existing content preserved
- File has context-mode rules → skipped, no duplicates

## Why Hooks Matter

Without hooks, routing compliance is ~60% — the model sometimes ignores instructions and runs raw `curl`, reads large files directly, or dumps unprocessed output. One unrouted Playwright snapshot (56 KB) wipes an entire session's savings.

With hooks, every tool call is intercepted before execution:
- Dangerous commands (`curl`, `wget`, direct large file reads) are blocked
- Routing guidance is injected at the call site in real time
- Compliance reaches ~98% context savings

## Real Savings Example

Without context-mode:

Playwright snapshot: 56 KB → context

gh issue list (20): 59 KB → context

access.log read: 45 KB → context

Total after 30 min: ~315 KB consumed (~40% of context)

With context-mode:

All three sandboxed: ~5.4 KB → context

Savings: 98% reduction

## Configuration Reference

Context-mode is zero-config for most use cases. The MCP server auto-starts via `npx -y context-mode` or the global `context-mode` binary.

SQLite databases are stored in `~/.context-mode/` and scoped per session. No environment variables required. No API keys. No accounts.

## Troubleshooting

### Tools not being routed to sandbox

1. Run `/context-mode:ctx-doctor` (Claude Code) or `ctx_doctor` (other platforms)
2. Verify hooks are registered: check platform-specific hook config files exist
3. Confirm `CLAUDE.md`/`GEMINI.md`/routing file exists in project root with context-mode rules
4. Without hooks, model compliance drops to ~60% — hooks are essential for reliable routing

### MCP server not found

# Verify global install

which context-mode

context-mode --version

# Or use npx fallback

npx -y context-mode

### ctx_search returns no results

- Ensure you're in a `--continue` session (fresh sessions start with empty index)
- Verify tools were called via sandbox (not raw Bash/Read)
- Run `ctx_stats` to confirm events were indexed in current session

### Hooks not firing on Cursor

- `sessionStart` hook is not supported by Cursor's validator — routing instructions are delivered via MCP server startup instead
- Ensure `.cursor/hooks.json` uses `preToolUse`/`postToolUse` only
- Project `.cursor/hooks.json` overrides `~/.cursor/hooks.json` — check for conflicts

### Plugin upgrade

# Claude Code

/context-mode:ctx-upgrade

# Other platforms

npm update -g context-mode

## Privacy Architecture

- All raw data processed in sandboxed subprocesses
- SQLite lives in `~/.context-mode/` — local only
- No network calls, no telemetry, no cloud sync
- No account, no API key, no per-seat subscription
- Sessions are ephemeral by default — data deleted unless `--continue` is passed
- License: Elastic License v2 (ELv2)