claude-context-mode

Claude Context Mode is an MCP server that helps manage and optimize the context window by routing tool calls through sandboxed context-saving tools and indexing session events for continuity. When enabled, the server provides six sandbox tools that your model can invoke: ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_index, ctx_search, and ctx_fetch_and_index. These tools are designed to offload raw data from your context and persist session state in SQLite, with an FTS5 index and BM25 search to retrieve only relevant information when you resume a conversation. The server also includes hooks and integration points (PreToolUse, PostToolUse, SessionStart, and similar workflows) to nudge the model to prefer sandboxed tools over raw commands, improving both efficiency and continuity across sessions.

Prerequisites:

• Node.js and npm installed on your machine
• Basic familiarity with MCP (Model Context Protocol) tooling

Installation steps:

1. Ensure you have Node.js and npm installed. You can verify with:

node -v
npm -v

2. Install the MCP server via npx (as recommended in the README):

npx -y context-mode

3. If you prefer a direct MCP entry point, you can also install context-mode and run it as an MCP server:

npm install -g context-mode

Then register and run according to your MCP hosting environment (Claude’s MCP workflow can use the npx approach or an explicit server script).

4. Verify the server is available in your MCP configuration as:

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

5. Start or register the server in your Claude/MCP environment as needed and test with a simple tool invocation to confirm sandbox routing is active.

Tips and caveats:

• Context Mode relies on sandboxed tools to significantly reduce context pollution. If you don’t see improvements, ensure hooks are enabled and that the model is instructed to prefer sandboxed tools over raw commands.
• The MCP server tracks session data in SQLite and uses FTS5 indexing with BM25 search to retrieve relevant context on demand. If you experience performance issues, ensure the underlying storage is accessible and not blocked by permissions.
• The default tooling exposed by this server includes six sandbox tools: ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_index, ctx_search, ctx_fetch_and_index. Use ctx_index and ctx_fetch_and_index to build and query the context index as sessions progress.
• For Claude users, there are built-in commands (ctx-stats, ctx-doctor, ctx-upgrade) to inspect and manage the MCP server. On other platforms, use equivalent tool commands if available.
• If you need to run without the optional hooks, you can use the MCP-only install path: claude mcp add context-mode -- npx -y context-mode. This provides the sandbox tools without automatic routing enhancements.