context-mode

context-mode

Context window optimization plugin for Claude Code in Cowork. Sandboxes tool output, compresses what returns with a self-learning 3-stage pipeline, indexes content into a local knowledge base, and tracks session state to reduce context consumption by 30–60% in typical developer sessions and more in research-heavy ones (run /context-mode:ctx-stats to see your actual savings in tokens and dollars). Current version: 1.6.0.

What It Does

Long Claude Code sessions consume context rapidly. Every file read, web fetch, and shell command dumps raw output into the context window. Context-mode solves this with seven capabilities:

1. Automatic Tool Routing — PreToolUse hooks intercept Bash, Read, Grep, WebFetch, and Agent calls before they execute and redirect them through the context-mode sandbox. 9 new matchers (v1.3.0) cover git log/diff, npm test/install, pytest, pip, cargo, docker, and make. You get the result; the raw output stays out of context. See Automatic Tool Routing below.
2. Sandbox Execution — Runs code in isolated subprocesses, capturing only stdout. Raw file contents and command output never enter context. Supports 11 languages.
3. Token Compression — A 3-stage pipeline compresses tool output that returns to context: (1) deterministic ANSI/terminal stripping, (2) pattern-based matchers that understand 10 tool output formats (jest, pytest, git log, cargo build, etc.) and collapse passing tests, compile steps, and progress bars while preserving failures verbatim, (3) session-aware relevance filtering that keeps content related to your current work. Errors, warnings, and tracebacks are never compressed away.
4. Self-Learning — A feedback loop tracks what compressed content Claude later searches for. If compressed content is frequently retrieved, the learner raises retention for that tool pattern. Run ctx_stats to see learner accuracy and lifetime savings.
5. Knowledge Base — Chunks and indexes content into a local SQLite FTS5 database with BM25 + trigram dual-strategy search. Retrieves only the relevant snippets.
6. Session Continuity — Captures session events via hooks and rebuilds a structured Session Guide after context compaction, so Claude resumes from exactly where it left off. The start.js bootstrapper handles version self-healing, ABI dependency checks, and pure-JS package installation before starting the server on every session.
7. Main Skill + CLAUDE.md — The context-mode skill provides an in-session decision tree, tool-selection patterns, and anti-patterns so Claude consistently picks the right tool. A CLAUDE.md file (shipped with the plugin) gives Claude the "Think in Code" directive and tool-selection rules. A .claude/settings.json ships deny/allow permission rules so Claude Code behaves safely out of the box.

Install

Quickest — one command:

npx --yes --package=github:scottconverse/context-mode context-mode

The installer runs 7 steps automatically: copies the plugin to cache, creates a marketplace entry, registers the plugin, enables it in settings, installs native dependencies, verifies FTS5, and probes the MCP server to confirm all 9 tools respond. After it completes, start a new Claude Code session.

In Claude Code or Cowork:

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

Start a new session. Verify with /context-mode:ctx-doctor.

Manual install:

git clone https://github.com/scottconverse/context-mode.git
cd context-mode
node install.js

Quick Start

Once installed, Claude automatically prefers context-saving tools. You can also use them directly:

• ctx_execute — run code in a sandbox instead of reading files into context
• ctx_search — search indexed content instead of re-reading files
• ctx_fetch_and_index — fetch and index a web page instead of raw WebFetch

Automatic Tool Routing

Context-mode registers PreToolUse hooks that intercept 18 tool and command patterns before they execute. Every rule is defined declaratively in hooks/core/routing-rules.js — the table below is auto-generated from that file on every release.