Context window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP + hooks.
# Context Mode
**The other half of the context problem.**
[, persists session memory, and enforces routing across 17 platforms via MCP + hooks.
# Context Mode
**The other half of the context problem.**
[, persists session memory, and enforces routing across 17 platforms via MCP + hooks
03# Context Mode
04**The other half of the context problem
05[s only the result. One script replaces ten tool calls and saves 100x context. This is a mandatory paradigm across all 17 supported clients, plus the OpenClaw gateway integration: stop treating the LLM as a data processor, treat it as a code generator.
No prose-style enforcement β context-mode keeps raw data out of context but never dictates how the model writes its final answer. Brevity, completeness, formatting β your model's call (or yours via your own CLAUDE.md / AGENTS.md). Aggressive brevity prompts have been shown to degrade coding/reasoning benchmarks (Moonshot AI on kimi-k2.5) β the routing block stays focused on where data goes, not on how the model talks.
Platforms are grouped by install complexity. Hook-capable platforms get automatic routing enforcement. Non-hook platforms need a one-time routing file copy.
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.
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).
Index a local file or directory into the persistent FTS5 knowledge base.
/context-mode:ctx-search
Search previously indexed content.
/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
Opens the hosted Insight dashboard (context-mode.com/insight) in your browser β org analytics for AI-assisted engineering teams.
Note: Slash commands are a Claude Code plugin feature. On other platforms, type ctx stats, ctx doctor, ctx index, ctx search, ctx upgrade, or ctx 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:
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.
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.
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.
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):
Install context-mode globally:
npm install -g context-mode
Register the MCP server with Copilot CLI's built-in command (writes ~/.copilot/mcp-config.json for you):
copilot mcp add context-mode -- context-mode
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:
Or let context-mode write this hooks file for you: context-mode upgrade (run from a Copilot CLI context, or with CONTEXT_MODE_PLATFORM=copilot-cli). upgrade writes the hooks file only β register the MCP server with copilot mcp add in step 2.
Restart Copilot CLI.
Plugins: Option A above uses Copilot CLI's plugin system, which registers MCP servers (.mcp.json), hooks (hooks.json), and skills (skills/) together β not just skills/agents. The shipped bundle is configs/copilot-cli/; copilot plugin install owner/repo:path installs it in one command (no clone). Option B is the equivalent without a plugin.
Version note: the hook commands run the globalcontext-mode (context-mode hook copilot-cli β¦), so they need a context-mode version with Copilot CLI support. On an older global the hooks are inert (no routing/capture) until you upgrade β but they do not block your tools (context-mode fails open). Upgrade with npm install -g context-mode@latest.
Verify: In a Copilot CLI session, type ctx stats. Context-mode tools should appear and respond. Run context-mode doctor to confirm hook + MCP registration.
Routing: Automatic via hooks (PreToolUse interception + SessionStart routing block). Auto-detected via MCP clientInfo.name (GitHub Copilot CLI) or, in a bare shell, a context-mode-written marker (~/.copilot/mcp-config.json or ~/.copilot/hooks/context-mode.json) β not a bare ~/.copilot/ dir, so a co-installed-but-unconfigured Copilot CLI is not mis-detected as context-mode-on-copilot.
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:
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)
Install context-mode globally:
npm install -g context-mode
Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):
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).
Copy the routing rules file. Cursor lacks a SessionStart hook, so the model needs a rules file for routing awareness:
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.
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.
(Optional) Copy the routing rules file. The model needs an AGENTS.md file for routing awareness:
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.
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 (#14808, #5409). The plugin uses experimental.chat.system.transform as a surrogate β it injects both the routing block and resume snapshots into the system prompt. User-prompt capture uses chat.message instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.
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.
(Optional) Copy the routing rules file. KiloCode shares the OpenCode plugin architecture, so the model needs an AGENTS.md file for routing awareness:
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, ~/.config/kilo/ instead of ~/.config/opencode/). Like OpenCode, it lacks a real SessionStart hook β the plugin uses experimental.chat.system.transform as a surrogate. User-prompt capture uses chat.message instead of the missing UserPromptSubmit hook. AGENTS.md/CLAUDE.md/CONTEXT.md rules are captured automatically on first hook fire per project.
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 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.
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).
Add the context-mode marketplace and install the plugin from Codex's plugin UI:
codex plugin marketplace add mksglu/context-mode
Enable plugin-provided hooks while the Codex feature is still gated:
[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.
ctx stats proves the plugin MCP server is installed and reachable; it does
not prove hooks are trusted or running.
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:
PreToolUse enforces deny/block routing today and is prepared for input rewrites once Codex supports them. PostToolUse captures session events. PreCompact builds the resume snapshot before compaction. SessionStart restores state after compaction. UserPromptSubmit captures user decisions and corrections. Stop records turn-end state.
Note: Codex PreToolUse routing currently supports deny rules only (blocks dangerous commands). It still needs upstream updatedInput support before context-mode can rewrite tool input; track openai/codex#18491. Context injection (additionalContext) is not supported in Codex PreToolUse β it works via PostToolUse and SessionStart instead. This is handled automatically.
PreCompact support is runtime-gated: it is present in Codex CLI 0.130.0, while the public Codex hooks docs may lag the shipped hook-event list. Older Codex builds that do not emit PreCompact will not create pre-compaction snapshots.
Copy routing instructions (recommended even with hooks for full routing awareness):
For global use: CM_ROOT="$(npm root -g)/context-mode"; cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.codex/AGENTS.md. Global applies to all projects. If both exist, Codex CLI merges them.
Restart Codex CLI.
Verify: Start a session and type ctx stats to verify MCP. To verify hook routing, confirm Codex lists/trusts the context-mode plugin hooks, then run a command that matches the routing rules.
Routing: MCP tools work after plugin install. Plugin hook routing is active only when hooks and plugin_hooks are enabled and Codex trusts the plugin hook commands. Manual hook routing is active when $CODEX_HOME/hooks.json or ~/.codex/hooks.json is configured. The AGENTS.md file provides routing instructions for model awareness.
Prerequisites: Node.js >= 22.5 (or Bun), Kimi Code CLI installed.
Install context-mode:
npm install -g context-mode
Add context-mode as an MCP server. Add to ~/.kimi-code/mcp.json:
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.
(Optional) Copy the routing instructions file for your project:
For global use: cp node_modules/context-mode/configs/qwen-code/QWEN.md ~/.qwen/QWEN.md
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 agycommand-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.
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.
The agycommand-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:
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).
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.
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.
Copy routing instructions (Zed has no hook support):
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:
Install context-mode globally:
npm install -g context-mode
Install the package into Pi:
pi install npm:context-mode
Alternative β add it manually to ~/.pi/agent/settings.json (or .pi/settings.json for project-level):
{
"packages": ["npm:context-mode"]
}
Add to ~/.pi/agent/mcp.json (or .pi/mcp.json for project-level):
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):
Run the OMP plugin install:
omp plugin install context-mode
Restart OMP.
Verify:
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.
OMP loads anything listed under ~/.omp/plugins/package.jsondependencies 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:87manifest.version = pluginPkg.version).
Install β MCP-only path (no plugin):
Install context-mode globally:
npm install -g context-mode
Add to ~/.omp/agent/mcp.json (user scope) or <project>/.omp/mcp.json (project scope):
Project-scoped alternative: cp ... .omp/SYSTEM.md. OMP also auto-discovers any AGENTS.md in the project tree.
Restart OMP.
Verify (any path): In an OMP session, type ctx stats. Context-mode tools should appear and respond.
Routing: Plugin path β programmatic enforcement via four pi.on(...) handlers (tool_call returns { block: true, reason } for curl/wget/inline-fetch per upstream hooks/types.ts:566, tool_result captures session events, session_start initializes the per-session DB row, session_before_compact persists a resume snapshot). ~98% compliance, parity with Claude Code hooks. MCP-only path β rule-based via SYSTEM.md, ~60% compliance. Auto-detected via PI_CODING_AGENT_DIR env var or presence of ~/.omp/. Storage roots at ~/.omp/context-mode/ so OMP and Pi installs never share session DBs, content indices, or stats files.
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).
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:
Upgrade to latest version from GitHub, rebuild, reconfigure hooks.
β
ctx_purge
Permanently deletes all indexed content from the knowledge base.
β
How the Sandbox Works
Each ctx_execute call spawns an isolated subprocess with its own process boundary. Scripts can't access each other's memory or state. The subprocess runs your code, captures stdout, and only that stdout enters the conversation context. The raw data β log files, API responses, snapshots β never leaves the sandbox.
Twelve language runtimes are available: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R, Elixir, and C#. Bun is auto-detected for 3-5x faster JS/TS execution.
Authenticated CLIs work through credential passthrough β gh, aws, gcloud, kubectl, docker inherit environment variables and config paths without exposing them to the conversation.
When output exceeds 5 KB and an intent is provided, Context Mode switches to intent-driven filtering: it indexes the full output into the knowledge base, searches for sections matching your intent, and returns only the relevant matches with a vocabulary of searchable terms for follow-up queries.
How the Knowledge Base Works
The ctx_index tool chunks markdown content by headings while keeping code blocks intact, then stores them in a SQLite FTS5 (Full-Text Search 5) virtual table. The SQLite backend is selected automatically at runtime: bun:sqlite on Bun, node:sqlite on Node.js >= 22.5, and better-sqlite3 everywhere else. Search uses BM25 ranking β a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and 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 for precise navigational queries.
When you call ctx_search, it returns relevant content snippets focused around matching query terms β not full documents, not approximations, the actual indexed content with smart extraction around what you're looking for. ctx_fetch_and_index extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context. Use the contentType parameter to filter results by type (e.g. code or prose).
Ranking: Reciprocal Rank Fusion
Search runs two parallel strategies and merges them with Reciprocal Rank Fusion (RRF):
Porter stemming β FTS5 MATCH with porter tokenizer. "caching" matches "cached", "caches", "cach".
RRF merges both ranked lists into a single result set, so a document that ranks well in both strategies surfaces higher than one that ranks well in only one. This replaces the old cascading fallback approach where trigram results were only used if porter returned nothing.
Proximity Reranking
Multi-term queries get an additional reranking pass. Results where query terms appear close together are boosted β "session continuity" ranks passages with adjacent terms higher than pages where "session" and "continuity" appear paragraphs apart.
Search results use intelligent extraction instead of truncation. Instead of returning the first N characters (which might miss the important part), Context Mode finds where your query terms appear in the content and returns windows around those matches.
TTL Cache
Indexed content persists in a per-project SQLite database at ~/.context-mode/content/. When ctx_fetch_and_index is called for a URL that was already indexed within its TTL window, the fetch is skipped entirely and the model searches the existing index directly.
Default TTL: 24 hours. Override per-call with ttl: <milliseconds> (PR #666). Longer for stable specs, shorter for changelogs you want re-checked often.
Cache hit (within TTL): Returns a cache hint (~0.3KB) instead of re-fetching (48KB+). Model proceeds to ctx_search.
Cache miss (TTL expired): Re-fetches silently. No user action needed.
ttl: 0 or force: true: Bypasses cache and re-fetches regardless of freshness.
14-day cleanup: Content databases and sources older than 14 days are removed on startup.
This means --continue sessions preserve indexed docs across restarts. No re-fetching, no wasted context tokens.
ctx_stats reports cache performance separately: hits, data avoided, network requests saved, and total context savings including cache.
Progressive Throttling
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
Session Continuity
When the context window fills up, the agent compacts the conversation β dropping older messages to make room. Without session tracking, the model forgets which files it was editing, what tasks are in progress, what errors were resolved, and what you last asked for.
Context Mode captures every meaningful event during your session and persists them in a per-project SQLite database. When the conversation compacts (or you resume with --continue, --resume, or /resume), your working state is rebuilt automatically β the model continues from your last prompt without asking you to repeat anything.
Resuming a non-latest session via /resume <picker> works the same way: the SessionStart hook detects the empty live-event table for the freshly issued session id and falls back to the most recent unconsumed snapshot for the project (session_resume table). The picker selects the conversation; context-mode rehydrates the prior working state.
Session continuity requires 5 hooks working together:
Hook
Role
Claude Code
Gemini CLI
VS Code Copilot
JetBrains Copilot
GitHub Copilot CLI
Cursor
OpenCode
KiloCode
OpenClaw
Codex CLI
Antigravity
Antigravity CLI (agy)
Kiro
Zed
Pi
OMP
PreToolUse
Enforces sandbox routing before tool execution
Yes
--
--
--
Yes
Yes
--
--
--
Yes
--
Bounded
Yes
--
β (via tool_call event)
β (via tool_call event)
PostToolUse
Captures events after each tool call
Yes
Yes
Yes
Yes
Yes
Yes
Plugin
Plugin
Plugin
Yes
--
Yes (capture-only)
Yes
--
β (via tool_result event)
β (via tool_result event)
UserPromptSubmit
Captures user decisions and corrections
Yes
--
--
--
Yes
--
Plugin (via chat.message)
Plugin (via chat.message)
--
Yes
--
--
--
--
--
--
Stop
Captures assistant turn-end state
Yes
--
--
--
Yes
Yes
--
--
--
Yes
--
Best-effort
--
--
--
--
PreCompact
Builds snapshot before compaction
Yes
Yes
Yes
Yes
Yes
--
Plugin
Plugin
Plugin
Yes
--
--
--
--
β (via session_before_compact)
β (via session_before_compact)
SessionStart
Restores state after compaction or resume
Yes
Yes
Yes
Yes
Yes
--
β (via experimental.chat.system.transform)
β (via experimental.chat.system.transform)
Plugin
Yes
--
--
--
--
β (via session_start event)
β (via session_start event)
Session completeness
Full
High
High
High
High
Partial
Full
Full
High
Partial
--
Partial
Partial
--
High
High
Note: Full session continuity (capture + snapshot + restore) works on Claude Code, Gemini CLI, VS Code Copilot, JetBrains Copilot, OpenCode, and KiloCode. GitHub Copilot CLI uses its own camelCase hook config keys (preToolUse, postToolUse, preCompact, sessionStart, userPromptSubmitted, agentStop) and top-level hook responses; it captures prompt, tool, compaction, session-start, and stop events when the plugin hooks are installed. OpenCode and KiloCode use experimental.chat.system.transform as a SessionStart surrogate to inject the routing block and restore prior sessions, plus chat.message for user-prompt capture; full SessionStart hook support is not yet available (#14808, #5409), but prior-session continuity and user-decision capture work fully. Cursor captures tool events via preToolUse/postToolUse, but sessionStart is currently rejected by Cursor's validator (forum report), so session restore after compaction is not available yet. OpenClaw uses native gateway plugin hooks (api.on()) for full session continuity. Pi Coding Agent provides high session continuity via extension hooks (tool_call, tool_result, session_start, session_before_compact). Codex CLI provides partial hook-based session tracking through PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit, and Stop; MCP tools work. Antigravity IDE and Zed have no hook support in the current release, so session tracking is not available there. Antigravity CLI (agy) is separate from the IDE and supports bounded PreToolUse, capture-only PostToolUse, and best-effort Stop through its plugin hooks. Kiro captures tool events via native preToolUse/postToolUse hooks, but its SessionStart equivalent (agentSpawn) is not yet wired, so session restore after compaction is unavailable. OMP (Oh My Pi) ships full plugin-based hook support β omp plugin install context-mode registers tool_call, tool_result, session_start, and session_before_compact handlers and storage roots cleanly under ~/.omp/context-mode/ so OMP and Pi installs never share state.
Every tool call passes through hooks that extract structured events:
Category
Events
Priority
Captured By
Files
read, edit, write, glob, grep
Critical (P1)
PostToolUse
Tasks
create, update, complete
Critical (P1)
PostToolUse
Plans
enter, exit, approved, rejected, file write
Critical (P1)
PostToolUse
Rules
CLAUDE.md / GEMINI.md / AGENTS.md paths + content
Critical (P1)
SessionStart
User Prompts
Every user message (for last-prompt restore)
Critical (P1)
UserPromptSubmit
Decisions
User corrections, preferences ("use X instead", "don't do Y")
High (P2)
UserPromptSubmit
Git
checkout, commit, merge, rebase, stash, push, pull, diff, status
High (P2)
PostToolUse
Errors
Tool failures, non-zero exit codes
High (P2)
PostToolUse
Error Resolution
Error β fix pairs detected across sequential tool calls
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)
User Role β behavioral directives set during the session
Detailed event data is also indexed into FTS5 for on-demand retrieval via ctx_search().
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).
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 require [features].hooks = true. Hook scripts (PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit, Stop) are implemented and tested; PreCompact remains runtime-gated on Codex builds that emit the event. PreToolUse deny routing works; input rewriting still depends on upstream updatedInput support (openai/codex#18491).
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).
Antigravity CLI (agy) β Partial coverage. The standalone CLI is separate from the IDE and supports bounded native PreToolUse enforcement for mapped high-flood tools, capture-only PostToolUse, and best-effort Stop through the shipped plugin hooks. It does not currently provide PreCompact/SessionStart/UserPromptSubmit coverage.
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.
Tool call output can be collapsed/expanded with the default Pi's default keybinding (Ctrl+O)
OMP (Oh My Pi) β High coverage. The plugin (installed via omp plugin install context-mode) registers all key lifecycle events: tool_call (PreToolUse), tool_result (PostToolUse), session_start (SessionStart), and session_before_compact (PreCompact). Storage roots cleanly under ~/.omp/context-mode/ so OMP and Pi installs never share state (issue #473). Auto-detected via PI_CODING_AGENT_DIR env var or presence of ~/.omp/.
Platform Compatibility
Feature
Claude Code
Qwen Code
Gemini CLI
VS Code Copilot
JetBrains Copilot
GitHub Copilot CLI
Cursor
OpenCode
KiloCode
OpenClaw
Codex CLI
Kimi Code
Antigravity
Antigravity CLI (agy)
Kiro
Zed
Pi
OMP
MCP Server / Native Tools
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Native plugin
Native plugin
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
PreToolUse Hook
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Plugin
Plugin
Plugin
Yes
Yes
--
Bounded
Yes
--
Yes (extension)
Plugin
PostToolUse Hook
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Plugin
Plugin
Plugin
Yes
Yes
--
Yes (capture-only)
Yes
--
Yes (extension)
Plugin
SessionStart Hook
Yes
Yes
Yes
Yes
Yes
Yes
--
β (via experimental.chat.system.transform)
β (via experimental.chat.system.transform)
Plugin
Yes
Yes
--
--
--
--
Yes (extension)
Plugin
PreCompact Hook
Yes
Yes
Yes
Yes
Yes
Yes
--
Plugin
Plugin
Plugin
Yes
Yes
--
--
--
--
Yes (extension)
Plugin
Can Modify Args
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Plugin
Plugin
Plugin
--
Yes
--
--
--
--
Yes (extension)
--
Can Block Tools
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Plugin
Plugin
Plugin
Yes
Yes
--
Bounded
Yes
--
Yes (extension)
Plugin
Utility Commands (ctx)
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes (/ctx-stats, /ctx-doctor)
Yes
Slash Commands
Yes
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
Plugin Marketplace
Yes
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
OpenCode uses a TypeScript plugin paradigm β hooks run as in-process functions via tool.execute.before, tool.execute.after, experimental.session.compacting, experimental.chat.system.transform, and chat.message, providing full routing enforcement, session continuity, and user-prompt capture. The experimental.chat.system.transform hook acts as a SessionStart surrogate to inject the routing block and restore prior sessions. The chat.message hook captures user prompts and decisions (UserPromptSubmit equivalent).
KiloCode shares the same TypeScript plugin architecture as OpenCode via the OpenCodeAdapter, with platform-specific configuration paths (kilo.json instead of opencode.json, ~/.config/kilo/ instead of ~/.config/opencode/). Hook capabilities match OpenCode, including SessionStart surrogate via experimental.chat.system.transform and user-prompt capture via chat.message.
OpenClaw runs context-mode as a native gateway plugin targeting Pi Agent sessions. Hooks register via api.on() (tool/lifecycle) and api.registerHook() (commands). All tool interception and compaction hooks are supported. See docs/adapters/openclaw.md.
Codex CLI hooks require [features].hooks = true. MCP tools work, and hook scripts activate through $CODEX_HOME/hooks.json or ~/.codex/hooks.json. PreToolUse supports permissionDecision: "deny" only; input modification still needs upstream updatedInput support (openai/codex#18491). additionalContext is not supported in PreToolUse (context injection works via PostToolUse and SessionStart instead; the codex formatter handles this automatically). PreCompact stores resume snapshots before compaction on Codex builds that emit the event, SessionStart restores them, and UserPromptSubmit/Stop capture prompt and turn-end continuity events. See the Codex install section for setup. Antigravity and Zed do not support hooks. They rely solely on manually-copied routing instruction files (AGENTS.md / GEMINI.md) for enforcement (~60% compliance). See each platform's install section for copy instructions. Antigravity and Zed are auto-detected via MCP protocol handshake β no manual platform configuration needed.
Antigravity CLI (agy) supports bounded PreToolUse blocking for mapped Bash/Read/Grep/WebFetch surfaces, plus PostToolUse capture and best-effort Stop capture through its plugin hooks.json. The routing rule and routing skill remain the broader instruction layer; PreInvocation/PostInvocation are not wired until their payload/response semantics are verified.
Kiro supports native preToolUse and postToolUse hooks for routing enforcement and tool event capture. agentSpawn (SessionStart equivalent) and stop are not yet wired. Requires manually copying KIRO.md to your project root. Kiro is auto-detected via MCP protocol handshake (clientInfo.name).
Pi Coding Agent runs context-mode as an extension with full hook support. The extension registers tool_call, tool_result, session_start, and session_before_compact events, providing high session continuity coverage. The MCP server provides all 11