Context Mode README

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, UserPromptSubmit, PreCompact, SessionStart, Stop) 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).

Prerequisites: Node.js >= 22.5 (or Bun), Gemini CLI installed.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

2. Add the following to ~/.gemini/settings.json. This single file registers the MCP server and all four hooks:

   config.jsonCopy

   {
     "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|mcp__context-mode|mcp__(?!.*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 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

Prerequisites: Node.js >= 22.5 (or Bun), VS Code with Copilot Chat v0.32+.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

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

   config.jsonCopy

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

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

   config.jsonCopy

   {
     "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 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

Prerequisites: Node.js >= 22.5 (or Bun), JetBrains IDE with GitHub Copilot plugin v1.5.57+.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

2. Add MCP server via Settings UI: Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add Server:

   • Name: context-mode
   • Command: context-mode

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

   config.jsonCopy

   {
     "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" }
       ]
     }
   }
   

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

Prerequisites: Node.js >= 22.5 (or Bun), GitHub Copilot CLI (copilot) installed. Set COPILOT_HOME first if you use an isolated Copilot home.

Install — Option A (plugin, one command — recommended):

npm install -g context-mode                                     # the plugin's MCP server runs the global binary
copilot plugin install mksglu/context-mode:configs/copilot-cli  # registers MCP + hooks + routing skill

The bundle's .mcp.json pins CONTEXT_MODE_PLATFORM=copilot-cli, so context-mode self-identifies as Copilot — ctx_upgrade and platform detection resolve copilot-cli even when Claude Code is co-installed (whose ~/.claude/ would otherwise win). No context-mode upgrade / agent call needed. To try it from a local clone before it lands on the default branch, point Copilot at the bundle directory: copilot --plugin-dir /path/to/context-mode/configs/copilot-cli.

Install — Option B (manual, no plugin):

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

2. Register the MCP server with Copilot CLI's built-in command (writes ~/.copilot/mcp-config.json for you):

   bashCopy

   copilot mcp add context-mode -- context-mode
   

3. Configure hooks in ~/.copilot/hooks/context-mode.json (or $COPILOT_HOME/hooks/context-mode.json). The config uses flat { "type": "command", "command": "..." } entries; context-mode also writes a top-level "version": 1, but that field is optional — the Copilot CLI accepts hook configs that omit it (it is pinned only for self-documentation). Copilot CLI fires six events context-mode uses:

   config.jsonCopy

   {
     "version": 1,
     "hooks": {
      "preToolUse":          [{ "type": "command", "command": "context-mode hook copilot-cli pretooluse" }],
      "postToolUse":         [{ "type": "command", "command": "context-mode hook copilot-cli posttooluse" }],
      "preCompact":          [{ "type": "command", "command": "context-mode hook copilot-cli precompact" }],
      "sessionStart":        [{ "type": "command", "command": "context-mode hook copilot-cli sessionstart" }],
      "userPromptSubmitted": [{ "type": "command", "command": "context-mode hook copilot-cli userpromptsubmit" }],
      "agentStop":           [{ "type": "command", "command": "context-mode hook copilot-cli stop" }]
     }
   }
   

   Or let context-mode write this hooks file for you: context-mode upgrade (run from a Copilot CLI context, or with ). writes the — register the MCP server with in step 2.

Prerequisites: Node.js >= 22.5 (or Bun), Cursor with agent mode.

🚧 Work in progress — the Marketplace plugin is awaiting Cursor team review. Until it's listed, install via the local-folder path described in Option A. Tracking in #485 / #489.

Option A — Marketplace plugin (recommended once published)

After Cursor lists context-mode in the Marketplace, install with one click. The plugin auto-registers MCP, hooks (preToolUse, postToolUse, sessionStart, stop, afterAgentResponse), rules, and skills. No manual config required.

Until then, use the local-folder path:

Windows (PowerShell) — Cursor does not follow Windows symlinks/junctions, so use robocopy:

git clone https://github.com/mksglu/context-mode.git
cd context-mode
robocopy . "$env:USERPROFILE\.cursor\plugins\local\context-mode" /MIR `
  /XD node_modules .git build web tests scripts .vscode `
  /XF *.log .gitignore *.bundle.mjs.map

macOS / Linux:

git clone https://github.com/mksglu/context-mode.git
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

Restart Cursor. The plugin appears in Settings → Plugins as "Context Mode (Local)". To pull updates, re-run the same robocopy / ln -s line.

Note: if .cursor/hooks.json already contains context-mode entries from a prior Option B install, context-mode doctor will warn about duplicate hook firings. Remove one configuration to keep events single-fire.

Option B — Manual install (existing path)

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

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

Prerequisites: Node.js >= 22.5 (or Bun), OpenCode installed.

Install:

1. Add to opencode.json in your project root (or ~/.config/opencode/opencode.json for global):

   config.jsonCopy

   {
     "$schema": "https://opencode.ai/config.json",
     "plugin": ["context-mode"]
   }
   

   The plugin entry registers all 11 ctx_* tools natively and enables hooks — OpenCode calls context-mode's TypeScript plugin in-process, so there is no redundant stdio MCP child per session.

2. (Optional) Copy the routing rules file. The model needs an AGENTS.md file for routing awareness:

   bashCopy

   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.

3. Restart OpenCode.

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

Upgrade note: If an existing config has BOTH plugin: ["context-mode"] AND mcp.context-mode, OpenCode will register zero ctx_* tools — the plugin path correctly suppresses MCP duplicates, but the legacy MCP entry confuses the loader. Run context-mode upgrade to remove the legacy mcp.context-mode entry; your other MCP servers are preserved. v1.0.140+ emits a stderr diagnostic with the same guidance when this happens.

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. The experimental.chat.system.transform hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The chat.message hook captures user prompts and decisions (UserPromptSubmit equivalent).

Note: OpenCode lacks a real SessionStart hook (, ). The plugin uses as a surrogate — it injects both the routing block and resume snapshots into the system prompt. User-prompt capture uses instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.

Prerequisites: Node.js >= 22.5 (or Bun), KiloCode installed.

Install:

1. Add to kilo.json in your project root (or ~/.config/kilo/kilo.json for global):

   config.jsonCopy

   {
     "$schema": "https://app.kilo.ai/config.json",
     "plugin": ["context-mode"]
   }
   

   The plugin entry registers all 11 ctx_* tools natively and enables hooks — KiloCode calls context-mode's TypeScript plugin in-process, so there is no redundant stdio MCP child per session.

2. (Optional) Copy the routing rules file. KiloCode shares the OpenCode plugin architecture, so the model needs an AGENTS.md file for routing awareness:

   bashCopy

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

3. Restart KiloCode.

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

Upgrade note: If an existing config has BOTH plugin: ["context-mode"] AND mcp.context-mode, KiloCode will register zero ctx_* tools — the plugin path correctly suppresses MCP duplicates, but the legacy MCP entry confuses the loader. Run context-mode upgrade to remove the legacy mcp.context-mode entry; your other MCP servers are preserved. v1.0.140+ emits a stderr diagnostic with the same guidance when this happens.

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. The experimental.chat.system.transform hook injects the routing block and prior-session snapshots at session start, enabling session continuity across restarts. The chat.message hook captures user prompts and decisions (UserPromptSubmit equivalent).

Note: KiloCode shares the same plugin architecture as OpenCode, using the OpenCodeAdapter with platform-specific configuration paths (kilo.json instead of opencode.json, instead of ). Like OpenCode, it lacks a real SessionStart hook — the plugin uses as a surrogate. User-prompt capture uses instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.

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:

   bashCopy

   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:

   TerminalCopy

   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 lifecycle fix from . On older versions, lifecycle hooks silently fail. The adapter falls back to DB snapshot reconstruction (less precise but preserves critical state).

Prerequisites: Node.js >= 22.5 (or Bun), Codex CLI installed.

Install:

1. Add the context-mode marketplace and install the plugin from Codex's plugin UI:

   bashCopy

   codex plugin marketplace add mksglu/context-mode
   

2. Enable plugin-provided hooks while the Codex feature is still gated:

   tomlCopy

   [features]
   plugin_hooks = true
   hooks = true
   

   Feature flag note: Current Codex builds expose hooks under [features].hooks (or codex --enable hooks). Prefer [features].hooks; [features].codex_hooks remains accepted as a legacy alias in current Codex builds. Bundled plugin hooks additionally require plugin_hooks until Codex enables plugin hooks by default.

   Custom storage location: if Codex cannot write the adapter default storage directory, set CONTEXT_MODE_DIR to an absolute writable root in the environment that launches Codex. Sessions and stats use <root>/sessions; indexed content uses <root>/content.

   bashCopy

   CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex
   

3. Restart Codex CLI and verify MCP with ctx stats.

   ctx stats proves the plugin MCP server is installed and reachable; it does not prove hooks are trusted or running.

4. Review and trust the context-mode plugin hooks if Codex prompts for hook approval. Plugin hooks are only active after both feature flags are enabled and Codex has accepted the hook commands.

The Codex plugin manifest provides MCP via .codex-plugin/mcp.json, skills via skills/, and bundled hooks via .codex-plugin/hooks.json. No manual [mcp_servers.context-mode] block or $CODEX_HOME/hooks.json is needed when plugin_hooks is enabled and the plugin hooks are trusted.

Node/PATH note: context-mode still needs node visible to the Codex process. The plugin removes manual Codex config, but it does not vendor Node or inherit login-shell PATH fixes automatically.

Manual fallback for Codex builds without plugin_hooks:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

2. Add to :

Prerequisites: Node.js >= 22.5 (or Bun), Kimi Code CLI installed.

1. Install context-mode:

   TerminalCopy

   npm install -g context-mode
   

2. Add context-mode as an MCP server. Add to ~/.kimi-code/mcp.json:

   config.jsonCopy

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode",
         "args": []
       }
     }
   }
   

3. Add hooks to ~/.kimi-code/config.toml:

   tomlCopy

   [[hooks]]
   event = "PreToolUse"
   matcher = "Bash|Shell|Read|Edit|Write|WebFetch|Agent|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__"
   command = "context-mode hook kimi pretooluse"
   timeout = 30
   
   [[hooks]]
   event = "PostToolUse"
   command = "context-mode hook kimi posttooluse"
   timeout = 30
   
   [[hooks]]
   event = "SessionStart"
   command = "context-mode hook kimi sessionstart"
   timeout = 30
   
   [[hooks]]
   event = "PreCompact"
   command = "context-mode hook kimi precompact"
   timeout = 30
   
   [[hooks]]
   event = "UserPromptSubmit"
   command = "context-mode hook kimi userpromptsubmit"
   timeout = 30
   
   [[hooks]]
   event = "Stop"
   command = "context-mode hook kimi stop"
   timeout = 30
   

4. Restart Kimi Code CLI and verify MCP with ctx stats.

   Note: Kimi Code uses the same JSON stdin/stdout wire protocol as Codex, but accepts additionalContext, updatedInput, and permissionDecision: "ask" in PreToolUse responses (Codex rejects these). The kimi hook normalizes ContentPart[] prompt arrays to strings for downstream extractors.

5. (Optional) Copy the routing instructions file for your project:

   bashCopy

   cp "$(npm root -g)/context-mode/configs/codex/AGENTS.md" ./AGENTS.md
   

   Or for global use:

   bashCopy

   CM_ROOT="$(npm root -g)/context-mode"; cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.kimi-code/AGENTS.md
   

Full documentation: docs/adapters/kimi-code.md

Prerequisites: Node.js >= 22.5 (or Bun), Qwen Code installed (npm install -g @qwen-code/qwen-code).

1. Install context-mode:

   TerminalCopy

   npm install -g context-mode
   

2. Add context-mode as an MCP server. Add to ~/.qwen/settings.json:

   config.jsonCopy

   {
     "mcpServers": {
       "context-mode": {
         "command": "context-mode",
         "args": []
       }
     }
   }
   

3. Add hooks for routing enforcement and session tracking. Add to ~/.qwen/settings.json:

   config.jsonCopy

   {
     "hooks": {
       "PreToolUse": [{ "matcher": "run_shell_command|read_file|read_many_files|grep_search|web_fetch|agent|mcp__plugin_context-mode_context-mode__ctx_execute|mcp__plugin_context-mode_context-mode__ctx_execute_file|mcp__plugin_context-mode_context-mode__ctx_batch_execute|mcp__(?!.*context-mode)", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code pretooluse" }] }],
       "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code posttooluse" }] }],
       "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code sessionstart" }] }],
       "PreCompact": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code precompact" }] }],
       "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "context-mode hook qwen-code userpromptsubmit" }] }]
     }
   }
   

4. Copy routing instructions (recommended for full routing awareness):

   bashCopy

   cp node_modules/context-mode/configs/qwen-code/QWEN.md ./QWEN.md
   

   For global use: cp node_modules/context-mode/configs/qwen-code/QWEN.md ~/.qwen/QWEN.md

5. Restart Qwen Code.

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

Note: Qwen Code uses the same hook wire protocol as Claude Code (JSON stdin/stdout, same event names). Auto-detected via MCP clientInfo (qwen-cli-mcp-client-*) or QWEN_PROJECT_DIR env var.

This is the Antigravity desktop IDE. For the agy command-line tool, see Antigravity CLI (agy) below — it installs as a full plugin with hooks.

Prerequisites: Node.js >= 22.5 (or Bun), the Antigravity IDE installed.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

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

   config.jsonCopy

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

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

   bashCopy

   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

The agy command-line tool, not the Antigravity desktop IDE above.

Prerequisites: Node.js >= 22.5 (or Bun), Antigravity CLI (agy) ≥ 1.0.7 (agy update to upgrade). Verified on agy 1.0.10.

Install:

npm install -g context-mode                                                                  # the plugin's MCP server + hooks run the global binary
agy plugin install https://github.com/mksglu/context-mode/tree/main/configs/antigravity-cli  # registers MCP + rule + skill + hooks

Restart agy.

MCP-only (no plugin, no hooks): if you only want the ctx_* tools, skip the plugin and add context-mode to agy's global MCP profile ~/.gemini/config/mcp_config.json (distinct from the Antigravity IDE's ~/.gemini/antigravity/ path), then restart agy:

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

Verify: type ctx stats in an agy session, or run any prompt from Try It and check the savings. context-mode doctor confirms MCP + hook registration. Remove with agy plugin uninstall context-mode.

Routing: the routing rule and skill provide the instruction layer; bounded PreToolUse blocks high-flood tools and PostToolUse captures sessions. The bundle pins CONTEXT_MODE_PLATFORM=antigravity-cli so agy is detected even when Claude Code is co-installed (#774).

Prerequisites: Node.js >= 22.5 (or Bun), Kiro with MCP enabled (Settings > search "MCP").

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

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

   config.jsonCopy

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

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

   config.jsonCopy

   {
     "name": "context-mode",
     "description": "Context-mode hooks for context window protection",
     "hooks": {
       "preToolUse": [
         { "matcher": "execute_bash|fs_read|@context-mode/ctx_execute|@context-mode/ctx_execute_file|@context-mode/ctx_batch_execute|@(?!context-mode/)", "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:

   bashCopy

   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 >= 22.5 (or Bun), Zed installed.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

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

   config.jsonCopy

   {
     "context_servers": {
       "context-mode": {
         "command": "context-mode",
         "args": [],
         "env": {}
       }
     }
   }
   

   Note: Zed uses "context_servers" instead of "mcpServers". args and env are optional for context-mode, but are shown here to match Zed's custom MCP server shape.

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

   bashCopy

   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 >= 22.5 (or Bun), Pi Coding Agent installed.

Install:

1. Install context-mode globally:

   TerminalCopy

   npm install -g context-mode
   

2. Install the package into Pi:

   bashCopy

   pi install npm:context-mode
   

   Alternative — add it manually to ~/.pi/agent/settings.json (or .pi/settings.json for project-level):

   config.jsonCopy

   {
     "packages": ["npm:context-mode"]
   }
   

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

   config.jsonCopy

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

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

Prerequisites: Node.js >= 22.5 (or Bun), Oh My Pi installed.

Install — plugin path (recommended):

1. Run the OMP plugin install:

   bashCopy

   omp plugin install context-mode
   

2. Restart OMP.

3. Verify:

   bashCopy

   omp plugin list
   omp plugin doctor
   

   Both should show context-mode as enabled.

   The plugin self-registers its MCP server in ~/.omp/agent/mcp.json on first load (spawned as node <plugin>/server.bundle.mjs, since the plugin-install package directory is not on PATH), so the 11 ctx_* tools become reachable after the restart in step 2 — no manual mcp.json edit needed (#677). An existing context-mode entry is never overwritten; remove it if you want the plugin to re-register the bundled path.

Install — manual plugin path (if omp plugin install is unavailable):

OMP loads anything listed under ~/.omp/plugins/package.json dependencies whose own package.json carries an omp (or pi) field. New plugins default to enabled — the lock file at ~/.omp/plugins/omp-plugins.lock.json is only consulted when a plugin needs to be explicitly disabled (loader skips runtimeState && !runtimeState.enabled per extensibility/plugins/loader.ts:89-94). So the manual install is two commands:

cd ~/.omp/plugins
bun add context-mode    # or: npm install context-mode

Then restart OMP. No lock file edit, no version pin — version is read from the freshly-installed package each time the loader runs (see loader.ts:87 manifest.version = pluginPkg.version).

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.5: 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. Linux + Node < 22.5 is unsupported (#564) — npm install will fail with remediation instructions.

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.

Windows / missing binding self-heal: if better_sqlite3.node ends up missing after install (e.g. prebuild-install not on cmd.exe PATH, no MSVC toolchain), the postinstall script and the runtime hook automatically re-fetch the prebuild and repair the binding — no manual npm rebuild needed (#408).

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'

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)
• Plans — plan mode entries, exits, approvals, and rejections
• 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, plus error→fix resolution pairs
• Constraints — discovered limitations and boundaries
• Blockers — open and resolved blockers ("blocked on X", "waiting for Y")
• 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 + agent findings
• Skills Used — slash commands invoked
• Rejected Approaches — tool calls the user denied
• External References — URLs and GitHub issue references
• Environment — working directory, env variables, worktrees
• 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 .

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

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.

JetBrains Copilot — High coverage. Same capabilities as VS Code Copilot — PostToolUse, PreCompact, and SessionStart all fire. Uses the same hook wire protocol and response format. User decisions aren't captured but all tool-level events are.

GitHub Copilot CLI — High coverage. Native plugin hooks use camelCase config keys (preToolUse, postToolUse, preCompact, sessionStart, userPromptSubmitted, agentStop) and top-level hook response fields. The plugin captures user prompts, tool events, compaction snapshots, session start restore, and stop events.

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 — Full session support. The TypeScript plugin captures PostToolUse events via tool.execute.after, user prompts and decisions via chat.message, builds compaction snapshots via experimental.session.compacting, and restores prior sessions via experimental.chat.system.transform (SessionStart surrogate). Routing block is injected on first chat.system.transform per session. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire.

KiloCode — Full session support. Shares the same plugin architecture as OpenCode via the OpenCodeAdapter. The TypeScript plugin captures PostToolUse events via tool.execute.after, user prompts and decisions via chat.message, builds compaction snapshots via experimental.session.compacting, and restores prior sessions via experimental.chat.system.transform (SessionStart surrogate).