Context Mode: An MCP Plugin That Reduces AI Agent Context Window Usage by 98%

The Context Window Problem Context Mode Solves

Raw tool output is the primary source of context pressure in a long AI coding session. The README quantifies the problem concretely: a Playwright snapshot costs 56 KB, twenty GitHub issues cost 59 KB, and a single access log costs 45 KB. After 30 minutes of work, the README states, 40 percent of the context window is consumed by raw data the agent does not need to keep in memory. When the agent compacts the conversation to free space, it loses track of which files were being edited, what tasks were in progress, and what decisions the user had made.

Context Mode attacks four parts of this problem: it keeps raw data out of context via sandbox tools, it preserves session state in SQLite so the agent can recover after compaction, it shifts data analysis from token-heavy file reads to lightweight code execution, and it does not impose brevity rules on the model's prose output. The fourth point is explicit in the README: the plugin controls where data goes, not how the model talks.

Sandboxed Code Execution and the Think-in-Code Approach

The central mechanism is ctx_execute, which runs a script in a sandboxed environment and returns only the console output to context. The README gives this example comparing the old approach to the new one:

// Before: 47 × Read() = 700 KB.  After: 1 × ctx_execute() = 3.6 KB.
ctx_execute("javascript", `
  const files = fs.readdirSync('src').filter(f => f.endsWith('.ts'));
  files.forEach(f => console.log(f + ': ' + fs.readFileSync('src/'+f,'utf8').split('\\n').length + ' lines'));
`);

Instead of reading 47 files into context (700 KB), the agent writes a script that counts lines and logs only the results (3.6 KB). The README calls this the mandatory paradigm across all 17 supported clients: the LLM should program the analysis, not compute it by reading raw data. The six sandbox tools are ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_index, ctx_search, and ctx_fetch_and_index. The largest single-event example the README gives is 315 KB reduced to 5.4 KB, the 98 percent reduction figure in the project description.

Installing Context Mode on Claude Code

Claude Code is the simplest install path. The README requires Claude Code v1.0.33 or later. To check your installed version:

claude --version

If the /plugin command is not recognized, the README gives two upgrade paths: `brew upgrade claude-code` for Homebrew users, or `npm update -g @anthropic-ai/claude-code`. With a compatible version, install with:

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

Restart Claude Code or run `/reload-plugins`, then confirm the install:

/context-mode:ctx-doctor

All checks should show [x]. The doctor validates runtimes, hooks, FTS5, and plugin registration. For an MCP-only install without automatic routing or slash commands, the README provides an alternative that works for trying the tool before committing to the full plugin:

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

For Gemini CLI and most other non-Claude-Code platforms, install globally with npm:

npm install -g context-mode

Session Memory: SQLite, FTS5, and What the --continue Flag Does

Every file edit, git operation, task, error, and user decision is written to a SQLite database as the session progresses. When the conversation compacts, the plugin does not dump the full history back into context. Instead, it queries the FTS5 index using BM25 relevance ranking and retrieves only the events relevant to the current operation. The README states this lets the agent pick up exactly where it left off.

The --continue flag is critical to understand: if you do not pass it when starting a session, the README states that the previous session data is deleted immediately. A fresh session always starts with a clean slate. This is by design, not an oversight. The ctx_purge tool permanently deletes all indexed content when called explicitly.

The five meta tools handle session management and diagnostics: ctx_stats shows per-tool context savings and savings ratio; ctx_doctor runs the health check; ctx_upgrade pulls the latest version, rebuilds, migrates the cache, and fixes hooks; ctx_purge removes all indexed content; and ctx_insight opens the hosted analytics dashboard at context-mode.com/insight.

The Status Line and Slash Commands on Claude Code

On Claude Code, all 11 tools are also accessible as slash commands under the /context-mode: namespace. The README notes that the plugin manifest cannot declare a status line automatically, so displaying real-time savings requires a one-time manual edit to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "context-mode statusline"
  }
}

After saving and restarting Claude Code, the status bar shows tokens saved in the current session, total tokens saved across sessions, and the efficiency ratio. The wiring resolves through the bundled CLI regardless of where the plugin cache lives.

On platforms other than Claude Code, the same operations are invoked by typing the tool name in the chat (ctx stats, ctx doctor, ctx index, ctx search, ctx upgrade, or ctx insight). The model calls the MCP tool automatically rather than requiring a slash command syntax.

License, Platform Coverage, and What the README Leaves Undocumented

The package.json lists the license as Elastic-2.0. This is the Elastic License 2.0, not an OSI-approved open-source license. It permits internal use and modification but prohibits providing the software to third parties as a managed service. Teams building a product that exposes context-mode as a hosted service should review the license before shipping.

The README describes 17 supported platforms in the project description, but the install instructions visible in the README cover Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI explicitly. Platforms are grouped by install complexity: hook-capable platforms get automatic routing enforcement, while non-hook platforms require a one-time routing file copy. The README does not specify which of the 17 are in each group beyond the examples shown.

The BENCHMARK.md file at the repository root is listed in the directory but its contents are not in the README. Claims about savings ratios in the README are supported by examples rather than by pointing to that file.

Maintenance and Version History

The package.json shows version 1.0.169. The three most recent releases are v1.0.169 (2026-06-29), v1.0.168 (2026-06-26), and v1.0.167 (2026-06-26). The last push to the repository was on 2026-09-27, three months after those releases. The high version number reflects a long release history with frequent incremental updates rather than major version jumps.

The ctx_upgrade tool handles self-updating: it pulls the latest release, rebuilds, migrates the cache, and fixes hooks. This means a developer does not need to reinstall the plugin to receive updates. The repository includes a tests/ directory and a vitest.config.ts, indicating an automated test suite, though the test coverage is not described in the README. Node.js version 22.5 or later is listed as a prerequisite for Gemini CLI and similar platforms.

Editorial conclusion

Context Mode is the right tool for developers who run long AI coding sessions and regularly hit context limits or lose session state during compaction. It is not a general-purpose AI tool: it targets developers using one of 17 supported AI coding clients, and its deepest integration is with Claude Code. Before deploying it in a team setting, read the Elastic-2.0 license in package.json: hosting context-mode as a managed service for others is explicitly excluded.

Frequently asked questions

Official sources

1. Issues
2. mksglu/context-mode on GitHub
3. Project website
4. README
5. Releases