# Context Mode

> Keep raw tool output out of the context window, and survive compaction

- Category: App Orchestration / Context Compression & Token Budgets
- Language: TypeScript
- Licence: Elastic License 2.0 (source-available)
- Repository: https://github.com/mksglu/context-mode
- Website: https://context-mode.com
- Canonical page: https://ai-tldr.dev/tools/context-mode/

## In short

Context Mode is an MCP server aimed at the two ways an agent session runs out of room: raw tool output flooding the context window, and compaction erasing what the agent was doing. It sits in the Context Compression & Token Budgets category of the App Orchestration tools and is open-source, written in TypeScript and licensed Elastic License 2.0 (source-available).

## Overview

Context Mode is an MCP server aimed at the two ways an agent session runs out of room: raw tool output flooding the context window, and compaction erasing what the agent was doing. Its sandbox tools answer the first — `ctx_execute` runs code in an isolated subprocess and only stdout enters the conversation, `ctx_execute_file` processes files without their contents ever leaving the sandbox, and `ctx_batch_execute` collapses many commands and searches into one call. The README's benchmark table puts a 56.2 KB Playwright snapshot at 299 bytes of context and a 45.1 KB access log at 155 bytes.

The second half is a knowledge base. `ctx_index` chunks markdown by heading (keeping code blocks intact) into a SQLite FTS5 table, and `ctx_search` retrieves snippets ranked by BM25 with Porter stemming and a trigram substring pass merged through Reciprocal Rank Fusion; titles and headings are weighted 5x. `ctx_fetch_and_index` does the same for URLs, converting HTML to markdown so the raw page never lands in context. Session events — file edits, git operations, tasks, errors, decisions — are tracked in SQLite and retrieved on demand after a compaction rather than dumped back in wholesale.

The third idea the project pushes is "think in code": have the model write a script that computes the answer instead of reading fifty files into context to compute it itself. Twelve language runtimes are available in the sandbox (JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R, Elixir, C#), with Bun auto-detected for faster JS/TS, and authenticated CLIs such as `gh`, `aws` and `kubectl` work through credential passthrough. Existing permission rules are enforced inside the sandbox too — if you block `sudo`, it stays blocked. Everything runs locally with no telemetry or account; the code is source-available under the Elastic License 2.0, and a hosted Insight dashboard is offered separately for team analytics.

## What it does

- Sandbox tools (`ctx_execute`, `ctx_execute_file`, `ctx_batch_execute`) that return only stdout to the conversation
- SQLite FTS5 knowledge base with BM25 ranking, Porter stemming and trigram search fused by RRF
- `ctx_fetch_and_index` for URLs, with a TTL cache and parallel multi-URL fetches
- Session continuity: edits, git operations, tasks and errors indexed for retrieval after compaction
- Twelve sandbox language runtimes plus credential passthrough for authenticated CLIs
- Claude Code plugin with hooks, slash commands and a savings status line; plain MCP install for other hosts

## Getting started

Claude Code gets the full plugin with automatic routing hooks; every other MCP host installs the server directly.

1. Install the Claude Code plugin

   Requires Claude Code v1.0.33 or later. Restart (or `/reload-plugins`) afterwards.

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

2. Verify the install

   The doctor checks runtimes, hooks, FTS5 and plugin registration — every line should come back ticked.

```text
/context-mode:ctx-doctor
```

3. Or install as a plain MCP server

   Gives you all the tools without the routing hooks or slash commands.

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

4. Push work into the sandbox

   Instead of reading files into context, have the model script the analysis and print only the result.

```js
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'));
`);
```

## When to use it

- Stop browser snapshots, access logs and big JSON responses from eating an agent's context window
- Keep a long coding session going past the point where compaction usually loses the thread
- Index documentation or fetched pages once and retrieve only the matching passages later
- Give an agent a local sandbox for authenticated CLI work without the credentials entering the transcript