GitHub - mksglu/context-mode: Context window optimization for AI coding agents. Sandboxes tool output, 98% reduction. 14 platforms

The other half of the context problem. Every MCP tool call dumps raw data into your context window. A Playwright snapshot costs 56 KB. Twenty GitHub issues cost 59 KB. One access log — 45 KB. After 30 minutes, 40% of your context is gone. And when the agent compacts the conversation to free space, it forgets which files it was editing, what tasks are in progress, and what you last asked for. On top of that, the agent wastes output tokens on filler, pleasantries, and verbose explanations — burning context from both sides. Context Mode is an MCP server that solves all four sides of this problem: - Context Saving — Sandbox tools keep raw data out of the context window. 315 KB becomes 5.4 KB. 98% reduction. - Session Continuity — Every file edit, git operation, task, error, and user decision is tracked in SQLite. When the conversation compacts, context-mode doesn't dump this data back into context — it indexes events into FTS5 and retrieves only what's relevant via BM25 search. The model picks up exactly where you left off. If you don't --continue , previous session data is deleted immediately — a fresh session means a clean slate. - Think in Code — The LLM should program the analysis, not compute it. Instead of reading 50 files into context to count functions, the agent writes a script that does the counting and console.log() s only the result. One script replaces ten tool calls and saves 100x context. This is a mandatory paradigm across all 14 platforms: stop treating the LLM as a data processor, treat it as a code generator.// Before: 47 × Read() = 700 KB. After: 1 × ctx_execute() = 3.6 KB. ctx_execute("javascript", ` const files = fs.readdirSync('src').filter(f => f.endsWith('.ts')); files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\\n').length + ' lines')); `); - Output Compression — Terse like caveman. Technical substance exact. Only fluff die. Drop articles, filler (just/really/basically), pleasantries, hedging. Fragments OK. Short synonyms. Code unchanged. Pattern: [thing] [action] [reason]. [next step]. Auto-expand for security warnings, irreversible actions, and user confusion. ~65-75% output token reduction with full technical accuracy. Platforms are grouped by install complexity. Hook-capable platforms get automatic routing enforcement. Non-hook platforms need a one-time routing file copy. Claude Code — plugin marketplace, fully automatic Prerequisites: Claude Code v1.0.33+ (claude --version ). If /plugin is not recognized, update first: brew upgrade claude-code or npm update -g @anthropic-ai/claude-code . Install: /plugin marketplace add mksglu/context-mode /plugin install context-mode@context-mode Restart Claude Code (or run /reload-plugins ). Verify: /context-mode:ctx-doctor All checks should show [x] . The doctor validates runtimes, hooks, FTS5, and plugin registration. Routing: Automatic. The SessionStart hook injects routing instructions at runtime — no file is written to your project. The plugin registers all hooks (PreToolUse, PostToolUse, PreCompact, SessionStart) and 11 MCP tools — six sandbox tools (ctx_batch_execute , ctx_execute , ctx_execute_file , ctx_index , ctx_search , ctx_fetch_and_index ) plus five meta-tools (ctx_stats , ctx_doctor , ctx_upgrade , ctx_purge , ctx_insight ). | Slash Command | What it does | |---|---| /context-mode:ctx-stats | Context savings — per-tool 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. | /context-mode:ctx-purge | Permanently delete all indexed content from the knowledge base. | /context-mode:ctx-insight | Personal analytics dashboard — 90 metrics, 37 insight patterns, 4 composite scores (productivity, quality, delegation, context health) across 23 event categories. Opens a local web UI. | Note: Slash commands are a Claude Code plugin feature. On other platforms, type ctx stats ,ctx doctor ,ctx upgrade , orctx insight in the chat — the model calls the MCP tool automatically. See Utility Commands. Status line (optional): Claude Code's plugin manifest cannot declare a status line, so this is a one-time manual edit to ~/.claude/settings.json : { "statusLine": { "type": "command", "command": "context-mode statusline" } } After saving, restart Claude Code. The bar shows $ saved this session · $ saved across sessions · % efficient so you can see savings accumulate in real time. The wiring is path-free — context-mode statusline resolves through the bundled CLI regardless of where the plugin cache lives. Alternative — MCP-only install (no hooks or slash commands) claude mcp add context-mode -- npx -y context-mode This gives you all 11 MCP tools without automatic routing. The model can still use them — it just won't be nudged to prefer them over raw Bash/Read/WebFetch. Good for trying it out before committing to the full plugin. Gemini CLI — one config file, hooks included Prerequisites: Node.js 18+, Gemini CLI installed. Install: - Install context-mode globally: npm install -g context-mode - Add the following to ~/.gemini/settings.json . This single file registers the MCP server and all four hooks:{ "mcpServers": { "context-mode": { "command": "context-mode" } }, "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" }] } ] } } - Restart Gemini CLI. Verify: /mcp list You should see context-mode: ... - Connected . Routing: Automatic via SessionStart hook. Optionally copy routing instructions for full model awareness: cp node_modules/context-mode/configs/gemini-cli/GEMINI.md ./GEMINI.md Why the BeforeTool matcher? It targets only tools that produce large output ( run_shell_command ,read_file ,read_many_files ,grep_search ,search_file_content ,web_fetch ,activate_skill ) plus context-mode's own tools (mcp__plugin_context-mode ). This avoids unnecessary hook overhead on lightweight tools while intercepting every tool that could flood your context window. Full config reference: configs/gemini-cli/settings.json VS Code Copilot — hooks with SessionStart Prerequisites: Node.js 18+, VS Code with Copilot Chat v0.32+. Install: - Install context-mode globally: npm install -g context-mode - Create .vscode/mcp.json in your project root:{ "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" } ] } } - Restart VS Code. Verify: Open Copilot Chat and type ctx stats . Context-mode tools should appear and respond. Routing: Automatic via SessionStart hook. Optionally copy routing instructions for full model awareness: cp node_modules/context-mode/configs/vscode-copilot/copilot-instructions.md .github/copilot-instructions.md Full hook config including PreCompact: configs/vscode-copilot/hooks.json JetBrains Copilot — hooks with SessionStart Prerequisites: Node.js 18+, JetBrains IDE with GitHub Copilot plugin v1.5.57+. Install: - Install context-mode globally: npm install -g context-mode - Add MCP server via Settings UI: Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add Server: - Name: context-mode - Command: context-mode - Name: - Create .github/hooks/context-mode.json :{ "hooks": { "PreToolUse": [ { "type": "command", "command": "context-mode hook jetbrains-copilot pretooluse" } ], "PostToolUse": [ { "type": "command", "command": "context-mode hook jetbrains-copilot posttooluse" } ], "SessionStart": [ { "type": "command", "command": "context-mode hook jetbrains-copilot sessionstart" } ] } } - Restart the JetBrains IDE. Verify: Open Copilot Chat and type ctx stats . Context-mode tools should appear and respond. Routing: Automatic via SessionStart hook. Optionally copy routing instructions for full model awareness: cp node_modules/context-mode/configs/jetbrains-copilot/copilot-instructions.md .github/copilot-instructions.md Full hook config including PreCompact: configs/jetbrains-copilot/hooks.json Full setup guide: docs/jetbrains-copilot.md Cursor — hooks with stop support Prerequisites: Node.js 18+, Cursor with agent mode. Install: - Install context-mode globally: npm install -g context-mode - Create .cursor/mcp.json in your project root (or~/.cursor/mcp.json for global):{ "mcpServers": { "context-mode": { "command": "context-mode" } } } - Create .cursor/hooks.json (or~/.cursor/hooks.json for global):{ "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" } ], "stop": [ { "command": "context-mode hook cursor stop" } ] } } The preToolUse matcher is optional — without it, the hook fires on all tools. Thestop hook fires when the agent turn ends and can send a followup message to continue the loop.afterAgentResponse is also available (fire-and-forget, receives full response text). - Copy the routing rules file. Cursor lacks a SessionStart hook, so the model needs a rules file for routing awareness: mkdir -p .cursor/rules cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc - Restart Cursor or open a new agent session. Verify: Open Cursor Settings > MCP and confirm "context-mode" shows as connected. In agent chat, type ctx stats . Routing: Hooks enforce routing programmatically via preToolUse /postToolUse /stop . The .cursor/rules/context-mode.mdc file provides routing instructions at session start since Cursor's sessionStart hook is currently rejected by their validator (forum report). Project .cursor/hooks.json overrides ~/.cursor/hooks.json . Known limitation: Cursor accepts additional_context in hook responses but does not surface it to the model (forum #155689). Routing relies on the .mdc rules file instead of hook context injection. Full configs: configs/cursor/hooks.json | configs/cursor/mcp.json | configs/cursor/context-mode.mdc OpenCode — TypeScript plugin with hooks Prerequisites: Node.js 18+, OpenCode installed. Install: - Install context-mode globally: npm install -g context-mode - Add to opencode.json in your project root (or~/.config/opencode/opencode.json for global):{ "$schema": "https://opencode.ai/config.json", "mcp": { "context-mode": { "type": "local", "command": ["context-mode"] } }, "plugin": ["context-mode"] } The mcp entry registers all 11 MCP tools. Theplugin entry enables hooks — OpenCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing. - (Optional) Copy the routing rules file. OpenCode lacks a SessionStart hook, so the model needs an AGENTS.md file for routing awareness:cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md This tells the model which tools to use and which commands are blocked. Without it, hooks still enforce routing — but the model won't know why a command was denied. - Restart OpenCode. Verify: In the OpenCode session, type ctx stats . Context-mode tools should appear and respond. Routing: Hooks enforce routing programmatically via tool.execute.before and tool.execute.after . The optional AGENTS.md file provides routing instructions for model awareness. The experimental.session.compacting hook builds resume snapshots when the conversation compacts. Note: OpenCode's SessionStart hook is not yet available (#14808), so startup/resume session restore is not supported. Compaction recovery works fully via the plugin. Full configs: configs/opencode/opencode.json | configs/opencode/AGENTS.md KiloCode — TypeScript plugin with hooks Prerequisites: Node.js 18+, KiloCode installed. Install: - Install context-mode globally: npm install -g context-mode - Add to kilo.json in your project root (or~/.config/kilo/kilo.json for global):{ "$schema": "https://app.kilo.ai/config.json", "mcp": { "context-mode": { "type": "local", "command": ["context-mode"] } }, "plugin": ["context-mode"] } The mcp entry registers all 11 MCP tools. Theplugin entry enables hooks — KiloCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing. - (Optional) Copy the routing rules file. KiloCode shares the OpenCode plugin architecture and lacks SessionStart, so the model needs an AGENTS.md file for routing awareness:cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md - Restart KiloCode. Verify: In the KiloCode session, type ctx stats . Context-mode tools should appear and respond. Routing: Hooks enforce routing programmatically via tool.execute.before and tool.execute.after . The optional AGENTS.md file provides routing instructions for model awareness. The experimental.session.compacting hook builds resume snapshots when the conversation compacts. Note: KiloCode shares the same plugin architecture as OpenCode, using the OpenCodeAdapter with platform-specific configuration paths ( kilo.json instead ofopencode.json ,~/.config/kilo/ instead of~/.config/opencode/ ). SessionStart hook availability depends on KiloCode's implementation. OpenClaw / Pi Agent — native gateway plugin Prerequisites: OpenClaw gateway running (>2026.1.29), Node.js 22+. context-mode runs as a native OpenClaw gateway plugin, targeting Pi Agent sessions (Read/Write/Edit/Bash tools). Unlike other platforms, there's no separate MCP server — the plugin registers directly into the gateway runtime via OpenClaw's plugin API. Install: - Clone and install: git clone https://github.com/mksglu/context-mode.git cd context-mode npm run install:openclaw The installer uses $OPENCLAW_STATE_DIR from your environment (default:/openclaw ). To specify a custom path:npm run install:openclaw -- /path/to/openclaw-state Common locations: Docker — /openclaw (the default). Local —~/.openclaw or wherever you setOPENCLAW_STATE_DIR .The installer handles everything: npm install ,npm run build ,better-sqlite3 native rebuild, extension registration inruntime.json , and gateway restart via SIGUSR1. - Open a Pi Agent session. Verify: The plugin register