Skip to content
/

Context Mode

context-mode · mksglu/context-mode · ★ 16k · last commit 2026-05-26

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context consumption by up to 98% while providing selective BM25-based session continuity after compaction.

Best whenThe LLM should be a code generator, not a data processor — agents should write scripts that return only results, not read files into context; this 'Think in …
Skip ifReading files into context to analyze them, Dumping full session history back into context after compaction
vs seeds
superpowersin the entire research corpus.
Primitive shape 22 total
Commands 5 Skills 1 Hooks 5 MCP tools 11
00

Summary

Context Mode — Summary

Context Mode is a TypeScript MCP server + Claude Code plugin that attacks the context window consumption problem from four angles: (1) sandbox execution tools that redirect raw data output out of the context window (98% reduction demonstrated), (2) SQLite+FTS5+BM25 session continuity that resumes exactly where the agent left off after compaction, (3) a "Think in Code" paradigm that trains agents to generate scripts rather than read files into context, and (4) no prose enforcement — it routes data, not language. With 15,710 stars, it is by far the most-starred framework in this batch. It supports 15 platforms via hooks (Claude Code, Gemini CLI, VS Code Copilot, Cursor, Windsurf, Codex, JetBrains, Kiro, OpenCode, OpenClaw, Antigravity, Zed, Continue, Pi, OMP) and ships an analytics web UI (ctx_insight) with 90 metrics, 37 insight patterns, and 4 composite scores across 23 event categories.

Compared to seeds: closest to ccmemory (session persistence + MCP tools for Claude Code) but dramatically broader — context-mode focuses on context window efficiency rather than knowledge graph memory, supports 15 platforms vs 1, ships a local analytics dashboard, and uses SQLite+FTS5+BM25 search (not Neo4j). The "Think in Code" paradigm (agent writes scripts instead of reading files) is unique in the entire corpus.

01

Overview

Context Mode — Origin & Philosophy

Origin

Created by Mert Koseoğlu (@mksglu), 30 contributors, Elastic License v2 (ELv2). TypeScript codebase. 15,710 GitHub stars. Last commit 2026-05-26 (active). npm package context-mode v1.0.151.

Reached Hacker News #1 with 570+ points.

Core Problem Statement

"Every MCP tool call dumps raw data into your context window. A Playwright snapshot costs 56 KB. Twenty GitHub issues cost 59 KB. One access log — 45 KB. After 30 minutes, 40% of your context is gone."

"And when the agent compacts the conversation to free space, it forgets which files it was editing, what tasks are in progress, and what you last asked for."

Four-Axis Solution

Axis 1 — Context Saving: Sandbox tools redirect data to indexed SQLite, not the context window. 315 KB → 5.4 KB (98% reduction).

Axis 2 — Session Continuity: SQLite + FTS5 + BM25 tracks all events. After compaction, BM25 search retrieves only relevant context. --continue flag resumes previous session; without it, previous session data is deleted (fresh session = clean slate).

Axis 3 — Think in Code: Agents should generate scripts, not read files. ctx_execute("javascript", script) runs code and returns only the result.

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

Axis 4 — No Prose Enforcement: Context Mode routes data decisions, not language style. Aggressive brevity prompts degrade coding/reasoning benchmarks (Moonshot AI data cited).

Philosophy Quote

"Context Mode is an MCP server that solves all four sides of this problem."

Hacker News Reception

#1 with 570+ points — confirmed strong practitioner demand for context window efficiency tooling.

02

Architecture

Context Mode — Architecture

Distribution

  • Type: npm-package + Claude Code plugin
  • npm: context-mode v1.0.151
  • License: Elastic License v2 (ELv2) — source-available, not OSS
  • Language: TypeScript (Node.js)
  • Storage: SQLite with FTS5 extension + BM25 search

Install Methods

# Claude Code (recommended)
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

# npm (for other platforms)
npm install -g context-mode

# MCP-only (no hooks or slash commands)
claude mcp add context-mode -- npx -y context-mode

Required Runtime

  • Node.js >= 22.5 (uses built-in node:sqlite) OR
  • Node.js (older, uses better-sqlite3) OR
  • Bun (uses built-in bun:sqlite)
  • Note: Linux + Node < 22.5 is unsupported

Directory Structure

context-mode/
├── .claude-plugin/
│   ├── context-mode/     # Plugin metadata
│   ├── hooks/
│   │   ├── hooks.json    # Claude Code hook configuration
│   │   ├── posttooluse.mjs
│   │   ├── pretooluse.mjs
│   │   ├── precompact.mjs
│   │   ├── sessionstart.mjs
│   │   ├── userpromptsubmit.mjs
│   │   ├── routing-block.mjs
│   │   └── session-*.mjs (session management modules)
│   └── skills/
│       └── context-mode-ops/  # Skill for mode ops
├── .claude/
│   └── skills/           # Claude Code skills
├── insight/              # Analytics web UI (Vite + React + Tailwind)
│   ├── src/
│   ├── server.mjs
│   └── vite.config.ts
├── web/                  # Simple web page
├── hooks/                # Platform hook configs
│   ├── core/
│   ├── cursor/
│   ├── gemini-cli/
│   ├── kiro/
│   ├── codex/
│   └── vscode-copilot/
├── configs/              # Per-platform configuration files
├── src/                  # TypeScript source
├── bin/
│   └── statusline.mjs    # CLI status line command
├── cli.bundle.mjs        # Bundled CLI
└── server.bundle.mjs     # Bundled MCP server

Storage

  • SQLite with FTS5 extension for full-text search
  • BM25 ranking algorithm for relevance
  • better-sqlite3 (older Node) / node:sqlite (Node >= 22.5) / bun:sqlite (Bun)
  • Session data deleted on session start unless --continue flag used

Target AI Tools

Claude Code, Gemini CLI, VS Code Copilot, Cursor, Windsurf, Codex, JetBrains Copilot, Kiro, OpenCode, OpenClaw, Antigravity, Zed, Continue, Pi, OMP (15 platforms)

03

Components

Context Mode — Components

MCP Server with 11 Tools

6 Sandbox Tools (data stays out of context)

Tool Purpose
ctx_execute Execute JavaScript/Python/shell script, return only console output
ctx_batch_execute Execute multiple scripts in sequence
ctx_execute_file Execute a script file by path
ctx_index Index content (files, URLs, text) into SQLite FTS5 knowledge base
ctx_search BM25 search over indexed content
ctx_fetch_and_index Fetch URL and index content — keeps web data out of context

5 Meta-Tools

Tool Purpose
ctx_stats Context savings: per-tool breakdown, tokens consumed, savings ratio
ctx_doctor Diagnostics: runtimes, hooks, FTS5, plugin registration, versions
ctx_upgrade Pull latest, rebuild, migrate cache, fix hooks
ctx_purge Permanently delete all indexed content from knowledge base
ctx_insight Personal analytics dashboard (opens local web UI at port 3000)

Slash Commands (5, Claude Code plugin)

Command Purpose
/context-mode:ctx-stats Context savings stats
/context-mode:ctx-doctor Diagnostics
/context-mode:ctx-upgrade Pull latest and rebuild
/context-mode:ctx-purge Delete knowledge base
/context-mode:ctx-insight Open analytics dashboard

Claude Code Hooks (5 events)

Event Matcher Purpose
PreToolUse Bash, WebFetch, Read, Grep, ... Routing block — redirect to sandbox tools
PostToolUse Bash|Read|Write|Edit|...mcp__ Session event capture, FTS5 indexing
PreCompact (all) Snapshot current session state before compaction
SessionStart (all) Inject routing instructions, restore session state
UserPromptSubmit (all) Capture user decisions and corrections

Skills (1)

Skill Purpose
context-mode-ops Core context mode operations skill

Analytics Web UI

ctx_insight opens a local web UI built with:

  • Vite + React + Tailwind CSS
  • @tanstack/react-router
  • Server at port 3000 (dev) / dynamic in production

Features:

  • 90 metrics
  • 37 insight patterns
  • 4 composite scores: productivity, quality, delegation, context health
  • 23 event categories

CLI Binary

context-mode statusline — outputs status line showing:

  • $ saved this session · $ saved across sessions · % efficient

Platform Configs (15 platforms)

Per-platform routing config files in configs/ directory:

  • gemini-cli/settings.json
  • vscode-copilot/hooks.json
  • cursor/ hooks and rules
  • kiro/ config
  • codex/ config
  • configs/zed/, antigravity/, continue/ etc.
05

Prompts

Context Mode — Prompt Files (Verbatim Excerpts)

Excerpt 1: PreToolUse Hook — Routing Block

Source: hooks/pretooluse.mjs

Prompting technique: Hook-injected routing decision — the hook analyzes the incoming tool call and can return a decision object with deny, allow, or redirect to guide the agent toward sandbox tools. This is a programmatic routing block, not a text prompt.

/**
 * Unified PreToolUse hook for context-mode (Claude Code)
 * Redirects data-fetching tools to context-mode MCP tools
 *
 * Routing is delegated to core/routing.mjs (shared across platforms).
 * This file retains the Claude Code-specific self-heal block.
 *
 * Crash-resilience: wrapped via runHook (#414)
 */
await runHook(async () => {
  const { routePreToolUse, initSecurity } = await import("./core/routing.mjs");
  const { formatDecision } = await import("./core/formatters.mjs");
  // ... routing logic ...
});

Excerpt 2: README — "Think in Code" Paradigm (Core Prompt Design Principle)

Source: README.md

Prompting technique: Mandatory paradigm shift — agents are instructed to generate code that produces results, not to read data into context. The routing block enforces this at the hook level.

### How Context Mode Solves It

3. **Think in Code** — The LLM should program the analysis, not compute it. 
   Instead of reading 50 files into context to count functions, the agent writes 
   a script that does the counting and `console.log()`s only the result. 
   One script replaces ten tool calls and saves 100x context. 
   This is a mandatory paradigm across all 15 platforms: 
   stop treating the LLM as a data processor, treat it as a code generator.

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

## Excerpt 3: SessionStart Hook — Context Injection (Session Continuity)

Source: `hooks/sessionstart.mjs` (conceptual — from README description)

**Prompting technique**: Selective context injection at session start — instead of dumping full session history into context after compaction, the SessionStart hook uses BM25 search to retrieve only relevant prior events and injects them as `additionalContext`. This is the anti-pattern of "context dump after compaction."

From README:
```markdown
2. **Session Continuity** — Every file edit, git operation, task, error, and user 
   decision is tracked in SQLite. When the conversation compacts, context-mode 
   doesn't dump this data back into context — it indexes events into FTS5 and 
   retrieves only what's relevant via BM25 search. The model picks up exactly 
   where you left off. If you don't `--continue`, previous session data is 
   deleted immediately — a fresh session means a clean slate.

Excerpt 4: Hooks Configuration — PostToolUse Matchers

Source: hooks/hooks.json

Technique: Exhaustive tool-use capture — the PostToolUse hook matches all significant tool types to build a complete session event log.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Read|Write|Edit|NotebookEdit|Glob|Grep|TodoWrite|TaskCreate|TaskUpdate|EnterPlanMode|ExitPlanMode|Skill|Agent|AskUserQuestion|EnterWorktree|mcp__",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse.mjs\""
          }
        ]
      }
    ]
  }
}
09

Uniqueness

Context Mode — Uniqueness & Positioning

differs_from_seeds

Context-mode is closest to ccmemory (MCP-anchored session persistence for Claude Code) but differs on every engineering dimension: ccmemory uses Neo4j graph for knowledge, context-mode uses SQLite+FTS5+BM25; ccmemory targets Claude Code only, context-mode targets 15 platforms; ccmemory's value is "remember decisions across sessions," context-mode's primary value is "keep raw data out of the context window to reduce consumption by 98%." The "Think in Code" paradigm (agent generates analysis scripts rather than reading files) is unique in the entire catalog — no seed framework proposes this as a mandatory architectural pattern. The analytics web UI with 90 metrics and 4 composite scores is the most sophisticated observability surface in any framework analyzed. At 15,710 stars, it is more starred than every seed framework except superpowers.

Positioning

Context-mode attacks the context window problem from a different angle than all other memory frameworks:

  • RLM / ccmemory / Nemp: focus on remembering things across sessions
  • Context-mode: focus on not wasting tokens within a session

The "98% context reduction" claim is the strongest quantitative efficiency claim in the corpus. The HN #1 placement validates practitioner demand.

Observable Failure Modes

  • ELv2 license: Not OSS — cannot be modified for commercial use without a license. Enterprise forks are blocked.
  • SQLite dependency complexity: better-sqlite3 native binary causes complex install issues on Linux (SIGSEGV crashes, glibc version mismatches, Alpine musl complications). The README documents multiple workarounds.
  • Routing false positives: The PreToolUse hook might intercept tool calls that should run inline, adding overhead. The routing block makes decisions based on tool name patterns, not content size.
  • "Think in Code" adoption friction: The paradigm requires agents to generate scripts rather than use their default tool patterns. Without the routing block actively enforcing this, agents revert to direct reads.
  • Session delete-by-default: The clean-slate default (no --continue) means all session data is lost unless the user explicitly enables continuation. Easy to forget.

Cross-References

  • Most starred framework in this batch by 5x margin
  • "Think in Code" paradigm is the most novel agent architecture insight in this batch
  • Analytics web UI is unique across all 350+ frameworks analyzed in this project
04

Workflow

Context Mode — Workflow

Phase 1: Install

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode
# Restart Claude Code or /reload-plugins

Verify: /context-mode:ctx-doctor — all checks must show [x]

Artifact: MCP server running, 5 hooks registered, 11 tools available

Phase 2: Active Session — Sandbox Routing

The PreToolUse hook intercepts data-heavy tool calls and suggests sandbox alternatives:

  • Read 50 filesctx_execute("javascript", script)
  • WebFetch large pagectx_fetch_and_index then ctx_search
  • Bash grep across codebasectx_execute script that returns summary

The PostToolUse hook captures every event (file edit, git operation, task, error, user decision) into SQLite FTS5.

Artifact: SQLite session database; context window usage dramatically reduced

Phase 3: Compaction Gate

PreCompact hook fires before compaction:

  • Saves current session snapshot to SQLite
  • Records active files, tasks in progress, recent errors

Artifact: Compaction snapshot in SQLite

Phase 4: Session Continuation (after compaction)

SessionStart hook:

  • Checks --continue flag
  • If continuing: BM25 searches FTS5 index for relevant context; injects only relevant items (not full history)
  • If new session: deletes previous session data (clean slate)

Artifact: Agent resumes with contextually relevant prior state, not a dump of full history

Phase 5: Analytics

/context-mode:ctx-insight
# or
ctx insight

Opens local web UI showing session analytics.

Artifact: Visual dashboard with productivity/quality metrics

Approval Gates

None — all operations are automatic via hooks.

Artifacts Summary

Artifact Path
SQLite database Local (managed by context-mode)
Session snapshot SQLite
FTS5 index SQLite
Analytics Local web UI (port 3000)
06

Memory Context

Context Mode — Memory & Context

Storage Model

SQLite with FTS5 (Full-Text Search) extension + BM25 ranking.

All session events tracked:

  • File edits
  • Git operations
  • Tasks in progress
  • Errors encountered
  • User decisions and corrections

Session Lifecycle

Fresh session (no --continue): Previous session data is deleted immediately. Clean slate.

Continued session (--continue): Previous data indexed in FTS5; BM25 search retrieves only relevant items at SessionStart. Not a full dump — selective retrieval based on relevance.

Memory Type

Two distinct stores:

  1. Session events: SQLite FTS5 indexed events (PostToolUse captures everything)
  2. Indexed content: ctx_index stores files/URLs/text for ctx_search queries

Both in local SQLite, not cloud.

After compaction, the SessionStart hook uses BM25 (Okapi BM25) over the FTS5 index to:

  1. Identify which prior events are most relevant to the current context
  2. Inject only those events as additionalContext
  3. Discard the rest

This is the key difference from naive context dumps: BM25 prioritizes relevance, not recency.

Context Compaction Handling

YesPreCompact hook snapshots current state; SessionStart hook selectively restores relevant context via BM25 search.

Cross-Session Handoff

Yes (optional) — requires explicit --continue flag. Default is clean-slate sessions.

State Files

File Contents
SQLite database (local) Session events, FTS5 index, content index
No path documented Path managed internally by context-mode

Context Savings Metrics

From README examples:

  • Playwright snapshot: 56 KB → out of context window
  • GitHub issues (20): 59 KB → out of context window
  • Access log: 45 KB → out of context window
  • Code analysis (47 reads): 700 KB → ctx_execute returns 3.6 KB
  • General: "315 KB becomes 5.4 KB" (98% reduction)
07

Orchestration

Context Mode — Orchestration

Multi-Agent

No — single-agent tool. Context-mode is infrastructure for one agent's context window management.

Orchestration Pattern

none

Execution Mode

event-driven — all 5 hooks fire on Claude Code lifecycle events (PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit).

Isolation Mechanism

none for agents. Data isolation via SQLite database per session.

Multi-Model

No — works with whatever model the agent runs on.

Crash Recovery

Yes — the runHook wrapper provides crash resilience for all hook modules. Plugin includes a self-heal mechanism that repairs hook configurations, package version mismatches, and missing SQLite bindings automatically.

Cross-Tool Portability

High — 15 platforms supported with platform-specific hook configurations.

Consensus Mechanism

None.

08

Ui Cli Surface

Context Mode — UI & CLI Surface

Dedicated CLI Binary

Yes — context-mode binary (npm package).

Subcommand Purpose
context-mode statusline Outputs real-time status: $ saved this session · $ saved across sessions · % efficient
context-mode hook <platform> <event> Platform-specific hook entry points

The binary is NOT a thin wrapper — it runs the full MCP server and hook logic.

Local Web Dashboard

Yes — analytics web UI via ctx_insight.

Property Value
Type web-dashboard
Port 3000 (dev; dynamic in production)
Tech stack Vite + React + Tailwind CSS + TanStack Router
Features 90 metrics, 37 insight patterns, 4 composite scores, 23 event categories

Composite scores:

  1. Productivity — task completion rate, context efficiency
  2. Quality — error rate, code review metrics
  3. Delegation — how much work is delegated to sandbox vs inline
  4. Context Health — window usage, compaction frequency, recovery quality

Slash Commands

5 commands in Claude Code: ctx-stats, ctx-doctor, ctx-upgrade, ctx-purge, ctx-insight

Status Line Integration

Optional ~/.claude/settings.json entry:

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

Shows real-time savings in Claude Code's status bar.

IDE Integration (15 platforms)

Each platform has a configs subdirectory with hook configurations:

  • Claude Code (full plugin + 5 hooks)
  • Gemini CLI (4 hooks via ~/.gemini/settings.json)
  • VS Code Copilot (PreToolUse + PostToolUse + SessionStart)
  • Cursor (hooks + .cursor/rules/context-mode.mdc)
  • Windsurf, Codex, JetBrains Copilot, Kiro, OpenCode, OpenClaw, Antigravity, Zed, Continue, Pi, OMP

Observability

  • ctx_stats: per-tool breakdown, tokens consumed, savings ratio
  • ctx_doctor: runtimes, hooks, FTS5, plugin registration
  • ctx_insight: full analytics dashboard
  • Status line: real-time savings display

Related frameworks

same archetype · same primary tool · same memory type

lean-ctx ★ 2.2k

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

cursor-coding-agent-os (Mugiwara555343) ★ 3

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

rtk (Real Token Killer) ★ 55k

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…

Code-Mode Library ★ 1.5k

Replaces traditional tool-calling with TypeScript code execution in a sandbox, collapsing N sequential tool calls into 1 code…