Step 1 — Install the plugin:

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Step 2 — Restart Claude Code.

That's it. The plugin installs everything automatically:

• MCP server with 6 sandbox tools (ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_index, ctx_search, ctx_fetch_and_index)
• PreToolUse hooks that intercept Bash, Read, WebFetch, Grep, and Task calls — nudging them toward sandbox execution
• PostToolUse, PreCompact, and SessionStart hooks for session tracking and context injection
• A CLAUDE.md routing instructions file auto-created in your project root
• Slash commands for diagnostics and upgrades (Claude Code only)

Note: Slash commands are a Claude Code plugin feature. On other platforms, all three utility commands (ctx stats, ctx doctor, ctx upgrade) work as MCP tools — just type the command name and the model will invoke it. See Utility Commands.

Alternative — MCP-only install (no hooks or slash commands):

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

This gives you the 6 sandbox tools but 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.

Step 1 — Install globally:

npm install -g context-mode

Step 2 — Register the MCP server. Add to ~/.gemini/settings.json:

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

Step 3 — Add hooks. Without hooks, the model can ignore routing instructions and dump raw output into your context window. Hooks intercept every tool call and enforce sandbox routing programmatically — blocking curl, wget, and other data-heavy commands before they execute. Add to the same ~/.gemini/settings.json:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli beforetool" }]
      }
    ],
    "AfterTool": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli aftertool" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "context-mode hook gemini-cli sessionstart" }]
      }
    ]
  }
}

Step 4 — Restart Gemini CLI. On first run, a GEMINI.md routing instructions file is auto-created in your project root. This works alongside hooks as a parallel enforcement layer — hooks block dangerous commands programmatically, while GEMINI.md teaches the model to prefer sandbox tools from the start.

Why hooks matter: Without hooks, context-mode relies on GEMINI.md instructions alone (~60% compliance). The model sometimes follows them, but regularly runs raw curl, reads large files directly, or dumps unprocessed output into context — a single unrouted Playwright snapshot (56 KB) wipes out an entire session's savings. With hooks, every tool call is intercepted before execution — dangerous commands are blocked, and routing guidance is injected in real-time. This is the difference between ~60% and ~98% context savings.

Full hook config including PreCompress: configs/gemini-cli/settings.json

Step 1 — Install globally:

npm install -g context-mode

Step 2 — Register the MCP server. Create .vscode/mcp.json in your project root:

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

Step 3 — Add hooks. Without hooks, the model can bypass routing and dump raw output into your context. Hooks intercept every tool call and enforce sandbox routing programmatically. 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" }
    ]
  }
}

Step 4 — Restart VS Code. On first run, a .github/copilot-instructions.md routing instructions file is auto-created in your project. This works alongside hooks as a parallel enforcement layer — hooks intercept tool calls programmatically, while copilot-instructions.md guides the model's tool selection from session start.

Why hooks matter: Without hooks, copilot-instructions.md guides the model but can't block commands. A single unrouted Playwright snapshot (56 KB) or gh issue list (59 KB) wipes out minutes of context savings. With hooks, these calls are intercepted and redirected to the sandbox before they execute.

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

Step 1 — Install globally:

npm install -g context-mode

Step 2 — Register the MCP server and plugin. OpenCode uses a TypeScript plugin paradigm instead of JSON hooks. Add both the MCP server and the plugin to opencode.json in your project root:

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

The mcp entry gives you 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 (like raw curl) and enforcing sandbox routing.

Step 3 — Restart OpenCode. On first run, an AGENTS.md routing instructions file is auto-created in your project root. This works alongside the plugin as a parallel enforcement layer — the plugin intercepts tool calls at runtime, while AGENTS.md guides the model's tool preferences from session start.

Why the plugin matters: Without the plugin entry, context-mode has no way to intercept tool calls. The model can run raw curl, read large files directly, or dump unprocessed output into context — ignoring AGENTS.md instructions. With the plugin, tool.execute.before fires on every tool call and blocks or redirects data-heavy commands before they execute. The experimental.session.compacting hook builds and injects resume snapshots when the conversation compacts, preserving session state.

Note: OpenCode's SessionStart hook is not yet available (#14808), so startup/resume session restore is not supported — the AGENTS.md file is the primary way context-mode instructions reach the model at session start. Compaction recovery works fully via the plugin.

Step 1 — Install globally:

npm install -g context-mode

Step 2 — Register the MCP server. Add to ~/.codex/config.toml:

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

Step 3 — Restart Codex CLI. On first run, an AGENTS.md routing instructions file is auto-created in your project root. Codex CLI reads AGENTS.md automatically and learns to prefer context-mode sandbox tools.

About hooks: Codex CLI does not support hooks — PRs #2904 and #9796 were closed without merge. The AGENTS.md routing instructions file is the only enforcement method (~60% compliance). The model receives the instructions at session start and sometimes follows them, but there is no programmatic interception — it can run raw curl, read large files, or bypass sandbox tools at any time.

For stronger enforcement, you can also add the instructions globally:

cp ~/.codex/AGENTS.md  # auto-created, or copy from node_modules/context-mode/configs/codex/AGENTS.md

Global ~/.codex/AGENTS.md applies to all projects. Project-level ./AGENTS.md applies to the current project only. If both exist, Codex CLI merges them.

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.

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. The AGENTS.md routing instructions file compensates by re-teaching tool preferences at each session start.

Codex CLI — No session support. No hooks means no event capture. Each compaction or new session starts fresh. The AGENTS.md routing instructions file is the only continuity mechanism.