Context Mode

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 6 sandbox tools (ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_index, ctx_search, ctx_fetch_and_index) plus meta-tools (ctx_stats, ctx_doctor, ctx_upgrade, ctx_purge, ctx_insight).

Note: Slash commands are a Claude Code plugin feature. On other platforms, type ctx stats, ctx doctor, ctx upgrade, or ctx insight in the chat — the model calls the MCP tool automatically. See Utility Commands.

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

Prerequisites: Node.js 18+, Gemini CLI installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. 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" }]
         }
       ]
     }
   }

3. Restart Gemini CLI.

Verify:

/mcp list

You should see context-mode: ... - Connected.

Routing: Automatic. The SessionStart hook injects routing instructions at runtime — no GEMINI.md file is written to your project. All four hooks (BeforeTool, AfterTool, PreCompress, SessionStart) handle enforcement programmatically.

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

Prerequisites: Node.js 18+, VS Code with Copilot Chat v0.32+.

Install:

1. Install context-mode globally:

   npm install -g context-mode

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

   {
     "servers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }

3. 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" }
       ]
     }
   }

4. Restart VS Code.

Verify: Open Copilot Chat and type ctx stats. Context-mode tools should appear and respond.

Routing: Automatic. The SessionStart hook injects routing instructions at runtime — no copilot-instructions.md file is written to your project.

Full hook config including PreCompact: configs/vscode-copilot/hooks.json

Prerequisites: Node.js 18+, Cursor with agent mode.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }

3. 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. The stop 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).

4. 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

5. 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

Prerequisites: Node.js 18+, OpenCode installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. 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 the 6 sandbox tools. The plugin entry enables hooks — OpenCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.

3. (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.

4. 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

Prerequisites: Node.js 18+, KiloCode installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. 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 the 6 sandbox tools. The plugin entry enables hooks — KiloCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.

3. (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

4. 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 of opencode.json, ~/.config/kilo/ instead of ~/.config/opencode/). SessionStart hook availability depends on KiloCode's implementation.

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:

1. 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 set OPENCLAW_STATE_DIR.

   The installer handles everything: npm install, npm run build, better-sqlite3 native rebuild, extension registration in runtime.json, and gateway restart via SIGUSR1.

2. Open a Pi Agent session.

Verify: The plugin registers 8 hooks via api.on() (lifecycle) and api.registerHook() (commands). Type ctx stats to confirm tools are loaded.

Routing: Automatic. All tool interception, session tracking, and compaction recovery hooks activate automatically — no manual hook configuration or routing file needed.

Minimum version: OpenClaw >2026.1.29 — this includes the api.on() lifecycle fix from PR #9761. On older versions, lifecycle hooks silently fail. The adapter falls back to DB snapshot reconstruction (less precise but preserves critical state).

Full documentation: docs/adapters/openclaw.md

Prerequisites: Node.js 18+, Codex CLI installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. Add to ~/.codex/config.toml:

   [mcp_servers.context-mode]
   command = "context-mode"

3. (Waiting for upstream) Enable the hooks feature flag. Add to ~/.codex/config.toml:

   [features]
   codex_hooks = true

   Status: Codex CLI's hook system is implemented in source (codex-rs/hooks/) but hook dispatch is not yet wired into the tool execution pipeline (Stage::UnderDevelopment). The feature flag is accepted but hooks don't fire during sessions as of v0.118.0. Our hook scripts are ready — they'll work immediately once Codex enables dispatch. Track progress: openai/codex#16685.

4. (Prepare for when dispatch is enabled) Add hooks for routing enforcement and session tracking. Create ~/.codex/hooks.json:

   {
     "hooks": {
       "PreToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex pretooluse" }] }],
       "PostToolUse": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex posttooluse" }] }],
       "SessionStart": [{ "hooks": [{ "type": "command", "command": "context-mode hook codex sessionstart" }] }]
     }
   }

   PreToolUse enforces sandbox routing (blocks dangerous commands, redirects to MCP tools). PostToolUse captures session events. SessionStart restores state after compaction.

   Note: PreToolUse routing supports deny rules only (blocks dangerous commands). Context injection (additionalContext) is not supported in Codex PreToolUse — it works via PostToolUse and SessionStart instead. This is handled automatically.

5. Copy routing instructions (recommended even with hooks for full routing awareness):

   cp node_modules/context-mode/configs/codex/AGENTS.md ./AGENTS.md

   For global use: cp node_modules/context-mode/configs/codex/AGENTS.md ~/.codex/AGENTS.md. Global applies to all projects. If both exist, Codex CLI merges them.

6. Restart Codex CLI.

Verify: Start a session and type ctx stats. Context-mode tools should appear and respond.

Routing: MCP tools work. Hook-based routing is ready but waiting for Codex to enable hook dispatch. The AGENTS.md file provides routing instructions for model awareness in the meantime.

Exec mode regression (v0.118.0): codex exec cancels all MCP tool calls with "user cancelled MCP tool call". The tool_call_mcp_elicitation flag went stable in 0.118.0, adding an approval prompt that exec-mode can't handle. Pin to Codex ≤0.116.0 for exec-mode MCP. Confirmed by upstream: openai/codex#16685. Interactive mode (codex / codex --full-auto) is not affected.

Prerequisites: Node.js 18+, Antigravity installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. Add to ~/.gemini/antigravity/mcp_config.json:

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }

3. Copy routing instructions (Antigravity has no hook support):

   cp node_modules/context-mode/configs/antigravity/GEMINI.md ./GEMINI.md

4. Restart Antigravity.

Verify: In an Antigravity session, type ctx stats. Context-mode tools should appear and respond.

Routing: Manual. The GEMINI.md file is the only enforcement method (~60% compliance). There is no programmatic interception. Auto-detected via MCP protocol handshake (clientInfo.name) — no manual platform configuration needed.

Full configs: configs/antigravity/mcp_config.json | configs/antigravity/GEMINI.md

Prerequisites: Node.js 18+, Kiro with MCP enabled (Settings > search "MCP").

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. Add to .kiro/settings/mcp.json in your project (or ~/.kiro/settings/mcp.json for global):

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode"
       }
     }
   }

3. Create .kiro/hooks/context-mode.json:

   {
     "name": "context-mode",
     "description": "Context-mode hooks for context window protection",
     "hooks": {
       "preToolUse": [
         { "matcher": "*", "command": "context-mode hook kiro pretooluse" }
       ],
       "postToolUse": [
         { "matcher": "*", "command": "context-mode hook kiro posttooluse" }
       ]
     }
   }

4. Copy routing instructions. Kiro's agentSpawn (SessionStart) is not yet implemented, so the model needs a routing file at session start:

   cp node_modules/context-mode/configs/kiro/KIRO.md ./KIRO.md

5. Restart Kiro.

Verify: Open the Kiro panel > MCP Servers tab and confirm "context-mode" shows a green status indicator. In chat, type ctx stats.

Routing: Hooks enforce routing programmatically via preToolUse/postToolUse. The KIRO.md file provides routing instructions since agentSpawn (SessionStart equivalent) is not yet wired. Tool names appear as @context-mode/ctx_batch_execute, @context-mode/ctx_search, etc. Auto-detected via MCP protocol handshake.

Full configs: configs/kiro/mcp.json | configs/kiro/agent.json | configs/kiro/KIRO.md

Prerequisites: Node.js 18+, Zed installed.

Install:

1. Install context-mode globally:

   npm install -g context-mode

2. Add to ~/.config/zed/settings.json (Windows: %APPDATA%\Zed\settings.json):

   {
     "context_servers": {
       "context-mode": {
         "command": {
           "path": "context-mode"
         }
       }
     }
   }

   Note: Zed uses "context_servers" and "command": { "path": "..." } syntax, not "mcpServers" or "command": "..." like other platforms.

3. Copy routing instructions (Zed has no hook support):

   cp node_modules/context-mode/configs/zed/AGENTS.md ./AGENTS.md

4. Restart Zed (or save settings.json — Zed auto-restarts context servers on config change).

Verify: Open the Agent Panel (Cmd+Shift+A), go to settings, and check the indicator dot next to "context-mode" — green means active. Type ctx stats in the agent chat.

Routing: Manual. The AGENTS.md file is the only enforcement method (~60% compliance). There is no programmatic interception. Tool names appear as mcp:context-mode:ctx_batch_execute, mcp:context-mode:ctx_search, etc. Auto-detected via MCP protocol handshake.

Prerequisites: Node.js 18+, Pi Coding Agent installed.

Install:

1. Clone the extension:

   git clone https://github.com/mksglu/context-mode.git ~/.pi/extensions/context-mode
   cd ~/.pi/extensions/context-mode
   npm install
   npm run build

2. Add to ~/.pi/agent/mcp.json (or .pi/mcp.json for project-level):

   {
     "mcpServers": {
       "context-mode": {
         "command": "node",
         "args": ["/home/youruser/.pi/extensions/context-mode/node_modules/context-mode/start.mjs"]
       }
     }
   }

   Note: JSON does not expand ~. Replace /home/youruser with your actual home directory (run echo $HOME to find it).

3. Restart Pi.

Verify: In a Pi session, type ctx stats. Context-mode tools should appear and respond.

Routing: Automatic. The extension registers all key lifecycle events (tool_call, tool_result, session_start, session_before_compact), providing full session continuity and routing enforcement.

Context Mode uses better-sqlite3 on Node.js, which ships prebuilt native binaries for most platforms. On glibc >= 2.31 systems (Ubuntu 20.04+, Debian 11+, Fedora 34+, macOS, Windows), npm install works without any build tools.

Linux + Node.js >= 22.13: Context Mode automatically uses the built-in node:sqlite module instead of better-sqlite3. This eliminates the native addon entirely, avoiding sporadic SIGSEGV crashes caused by V8's madvise(MADV_DONTNEED) corrupting the addon's .got.plt section on Linux. No configuration needed — detection is automatic. Falls back to better-sqlite3 on older Node.js versions.

Bun users: No native compilation needed. Context Mode automatically detects Bun and uses the built-in bun:sqlite module via a compatibility adapter. better-sqlite3 and all its build dependencies are skipped entirely.

On older glibc systems (CentOS 7/8, RHEL 8, Debian 10), prebuilt binaries don't load and better-sqlite3 automatically falls back to compiling from source via prebuild-install || node-gyp rebuild --release. This requires a C++20 compiler (GCC 10+), Make, and Python with setuptools.

CentOS 8 / RHEL 8 (glibc 2.28):

dnf install -y gcc-toolset-10-gcc gcc-toolset-10-gcc-c++ make python3 python3-setuptools
scl enable gcc-toolset-10 'npm install -g context-mode'

CentOS 7 / RHEL 7 (glibc 2.17):

yum install -y centos-release-scl
yum install -y devtoolset-10-gcc devtoolset-10-gcc-c++ make python3
pip3 install setuptools
scl enable devtoolset-10 'npm install -g context-mode'

Alpine Linux:

Alpine prebuilt binaries (musl) are available in better-sqlite3 v12.8.0+. With the ^12.6.2 dependency range, npm install resolves to the latest 12.x and works without build tools on Alpine. If you pin an older version:

apk add build-base python3 py3-setuptools
npm install -g context-mode

Every tool call passes through hooks that extract structured events:

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

SessionStart fires (source: "compact")
  → Retrieve stored snapshot
  → Write structured events file → auto-indexed into FTS5
  → Build Session Guide with 15 categories
  → Inject <session_knowledge> directive into context
  → Model continues from last user prompt with full working state

The snapshot is built in priority tiers — if the 2 KB budget is tight, lower-priority events (intent, MCP tool counts) are dropped first while critical state (active files, tasks, rules, decisions) is always preserved.

After compaction, the model receives a Session Guide — a structured narrative with actionable sections:

• 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 ("use X instead", "don't do Y")
• Files Modified — all files touched during the 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 the session
• Session Intent — mode classification (implement, investigate, review, discuss)
• User Role — behavioral directives set during the session

Detailed event data is also indexed into FTS5 for on-demand retrieval via search().

Claude Code — Full session support. All 5 hook types fire, capturing tool events, user decisions, building compaction snapshots, and restoring state after compaction or --continue.

Gemini CLI — High coverage. PostToolUse (AfterTool), PreCompact (PreCompress), and SessionStart all fire. Missing UserPromptSubmit, so user decisions and corrections aren't captured — but file edits, git ops, errors, and tasks are fully tracked.

VS Code Copilot — High coverage. Same as Gemini CLI — PostToolUse, PreCompact, and SessionStart all fire. User decisions aren't captured but all tool-level events are.

Cursor — Partial coverage. Native preToolUse and postToolUse hooks capture tool events. sessionStart is documented by Cursor but currently rejected by their validator, so session restore is not available. Routing instructions are delivered via MCP server startup instead.

OpenCode — Partial. The TypeScript plugin captures PostToolUse events via tool.execute.after, but SessionStart is not yet available (#14808). Events are stored but not automatically restored after compaction.

KiloCode — Partial. Shares the same plugin architecture as OpenCode via the OpenCodeAdapter. The TypeScript plugin captures PostToolUse events via tool.execute.after, but SessionStart availability depends on KiloCode's implementation. Events are stored but may not be automatically restored after compaction.

OpenClaw / Pi Agent — High coverage. All tool lifecycle hooks (after_tool_call, before_compaction, session_start) fire via the native gateway plugin. User decisions aren't captured but file edits, git ops, errors, and tasks are fully tracked. Falls back to DB snapshot reconstruction if compaction hooks fail on older gateway versions. See docs/adapters/openclaw.md.

Codex CLI — MCP active, hooks ready. Hook scripts (PreToolUse, PostToolUse, SessionStart) are implemented and tested but Codex CLI doesn't dispatch them yet (Stage::UnderDevelopment). MCP tools work. Track: openai/codex#16685.

Antigravity — No session support. No hooks, no event capture. Requires manually copying GEMINI.md to your project root. Auto-detected via MCP protocol handshake (clientInfo.name).

Zed — No session support. No hooks, no event capture. Requires manually copying AGENTS.md to your project root. Auto-detected via MCP protocol handshake (clientInfo.name).

Kiro — Partial coverage. Native preToolUse and postToolUse hooks capture tool events and enforce sandbox routing. agentSpawn (the Kiro equivalent of SessionStart) is not yet implemented, so session restore after compaction is not available. Requires manually copying KIRO.md to your project root. Auto-detected via MCP protocol handshake (clientInfo.name).

Pi Coding Agent — High coverage. The extension registers all key lifecycle events: tool_call (PreToolUse), tool_result (PostToolUse), session_start (SessionStart), and session_before_compact (PreCompact). File edits, git ops, errors, and tasks are fully tracked. Session restore after compaction works via the extension's event hooks.