context-compress

Keep your context window lean. Let the sandbox do the heavy lifting.

A context-aware MCP server for Claude Code that compresses tool output by processing it in isolated subprocesses. Raw data stays in the sandbox — only concise summaries enter your context window.

Quickstart for Agents · Getting Started · How It Works · Token Reduction · Configuration · CLI · Changelog

Quickstart for Agents

Install context-compress — an MCP server that compresses tool output for Claude Code.
Raw data stays in sandboxed subprocesses, only concise summaries enter your context window.
Saves ~99% of tokens on large outputs while keeping everything searchable via FTS5.

npm install -g context-compress
claude mcp add context-compress -- node $(which context-compress)
context-compress doctor

More info: https://github.com/Open330/context-compress

Why?

Every byte of tool output that enters your Claude Code context window reduces quality and speed. A single git log or npm test can dump 50KB+ into context — that's ~12,000 tokens gone.

context-compress intercepts these tools, processes output in a sandbox, and returns only what matters:

Before:  git log --oneline -100  →  8.2KB into context
After:   execute("git log ...")  →  0.3KB summary + full data searchable in FTS5

Based on context-mode by Mert Koseoğlu — rewritten in TypeScript with security hardening, architectural improvements, and better DX.

Getting Started

Install

npm install -g context-compress

Add to Claude Code

claude mcp add context-compress -- node $(which context-compress)

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "context-compress": {
      "command": "node",
      "args": ["/path/to/context-compress/dist/index.js"]
    }
  }
}

Verify

context-compress doctor

How It Works

┌─────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                                                          │
│  "Run tests"  ──→  PreToolUse Hook intercepts            │
│                          │                               │
│                          ▼                               │
│               ┌──────────────────┐                       │
│               │  context-compress │                      │
│               │   MCP Server      │                      │
│               └────────┬─────────┘                       │
│                        │                                 │
│            ┌───────────┼───────────┐                     │
│            ▼           ▼           ▼                     │
│     ┌──────────┐ ┌──────────┐ ┌──────────┐              │
│     │ Executor │ │  Store   │ │  Stats   │              │
│     │ (11 lang)│ │  (FTS5)  │ │ Tracker  │              │
│     └──────────┘ └──────────┘ └──────────┘              │
│            │           │                                 │
│            ▼           ▼                                 │
│     Raw output    Indexed &     Only summary             │
│     stays here    searchable    enters context           │
└─────────────────────────────────────────────────────────┘

7 MCP Tools

| Tool | What it does | |:-----|:-------------| | execute | Run code in 11 languages. Only stdout enters context. | | execute_file | Process a file via FILE_CONTENT variable — file never enters context. | | index | Chunk markdown/text into FTS5 knowledge base for search. | | search | BM25 search with Porter stemming → trigram → fuzzy fallback. | | fetch_and_index | Fetch URL → HTML-to-markdown → auto-index. Preview only in context. | | batch_execute | Run N commands + search in ONE call. Replaces 30+ tool calls. | | stats | Real-time session statistics: bytes saved, tokens avoided, savings ratio. |

Supported Languages

javascript · typescript · python · shell · ruby · go · rust · php · perl · r · elixir

Bun auto-detected for 3-5x faster JS/TS execution.

Token Reduction

context-compress achieves 99.2% token reduction across a typical 12-operation coding session.

| Operation | Before | After | Reduction | |:--|--:|--:|--:| | Read bundled file (776KB) | 194,076 tok | 105 tok | 99.9% | | Playwright snapshot (56KB) | 14,000 tok | 75 tok | 99.5% | | Read CSV/JSON data (100KB) | 25,000 tok | 125 tok | 99.5% | | Read source file (21KB) | 5,250 tok | 88 tok | 98.3% | | npm install log (15KB) | 3,750 tok | 50 tok | 98.7% | | curl API response (12KB) | 3,000 tok | 88 tok | 97.1% | | npm test (42 tests) | 935 tok | 45 tok | 95.2% | | batch_execute (5 cmds) | 6,250 tok | 375 tok | 94.0% | | fetch_and_index (45KB page) | 11,250 tok | 750 tok | 93.3% | | grep (small output) | 361 tok | 361 tok | 0% | | Session Total | 267,121 tok | 2,223 tok | 99.2% |

Without context-compress, 12 operations consume 133% of the 200K context window — overflowing it entirely. With context-compress, the same operations use 1.1%, leaving 98.9% free for actual conversation.

Data isn't deleted — it's indexed in FTS5 and searchable on demand. Small outputs (<5KB) pass through uncompressed.

Read the full Token Reduction Report — includes cost analysis, architecture deep-dive, and FAQ on context loss trade-offs.

What Changed from context-mode

| | context-mode | context-compress | |:--|:------------|:-----------------| | Credentials | 20+ auth env vars passed by default | Opt-in only (passthroughEnvVars: []) | | Hook writes | Self-modifies settings.json | Zero filesystem writes | | Rust compile | Shell string → injection risk | execFileSync with array args | | Upgrade | git clone arbitrary code | Removed entirely | | FTS5 indexing | Always dual-table (Porter + trigram) | Lazy trigram — 50% fewer writes | | Runtime detect | Sequential execSync ~250ms | Parallel Promise.all ~40ms | | batch_execute | Sequential commands | Promise.allSettled parallel | | Config | None | ENV + file + defaults | | Errors | 23 silent catch blocks | CONTEXT_COMPRESS_DEBUG=1 logs all | | Uninstall | None | context-compress uninstall |

Configuration

Loaded in order: ENV vars → .context-compress.json → defaults

Environment Variables

# Enable debug logging (stderr)
CONTEXT_COMPRESS_DEBUG=1

# Pass specific env vars to subprocesses (default: none)
CONTEXT_COMPRESS_PASSTHROUGH_ENV=GH_TOKEN,AWS_PROFILE

# Disable curl/wget blocking
CONTEXT_COMPRESS_BLOCK_CURL=0

# Disable WebFetch blocking
CONTEXT_COMPRESS_BLOCK_WEBFETCH=0

# Disable Read/Grep nudges
CONTEXT_COMPRESS_NUDGE_READ=0
CONTEXT_COMPRESS_NUDGE_GREP=0

Config File

Create .context-compress.json in your project root or home directory:

{
  "passthroughEnvVars": ["GH_TOKEN", "AWS_PROFILE", "KUBECONFIG"],
  "blockCurl": true,
  "blockWebFetch": true,
  "debug": false
}

CLI

context-compress            # Start MCP server (stdio)
context-compress setup      # Detect runtimes, show install instructions
context-compress doctor     # Diagnose: runtimes, hooks, FTS5, version
context-compress uninstall  # Clean removal: hooks, MCP reg, stale DBs

Doctor Output Example

  context-compress doctor

  [PASS] Performance: FAST — Bun detected
  [PASS] Language coverage: 7/11 (64%)
  [PASS] Server test: OK
  [PASS] PreToolUse hook configured
  [PASS] FTS5 / better-sqlite3 works

  Version: v2026.3.3
  All checks passed.

Project Structure

context-compress/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server (7 tools)
│   ├── executor.ts           # SubprocessExecutor
│   ├── store.ts              # ContentStore (FTS5)
│   ├── config.ts             # Config system
│   ├── logger.ts             # Debug logger
│   ├── snippet.ts            # FTS5 snippet extraction
│   ├── stats.ts              # Session tracker
│   ├── types.ts              # Shared types
│   ├── runtime/
│   │   ├── plugin.ts         # LanguagePlugin interface
│   │   ├── index.ts          # Registry + parallel detection
│   │   └── languages/        # 11 language plugins
│   ├── hooks/
│   │   └── pretooluse.ts     # PreToolUse hook (no self-mod)
│   └── cli/
│       ├── index.ts          # CLI entry
│       ├── setup.ts          # Interactive setup
│       ├── doctor.ts         # Diagnostics
│       └── uninstall.ts      # Clean removal
├── tests/
│   ├── unit/                 # 7 unit test files
│   └── integration/          # 3 integration test files
├── hooks/
│   └── hooks.json            # Hook matcher config
├── skills/                   # Slash command definitions
└── dist/                     # Compiled output

Security

| Threat | Mitigation | |:-------|:-----------| | Credential leakage | passthroughEnvVars defaults to [] — zero env vars passed unless opted in | | Shell injection (Rust) | execFileSync with array arguments — no string interpolation | | Hook self-modification | No fs.writeFileSync in hooks — zero filesystem side effects | | Arbitrary code execution | No upgrade command — no git clone or npm install at runtime | | Silent failures | Debug mode surfaces all catch block errors to stderr |

Contributing

git clone https://github.com/Open330/context-compress
cd context-compress
npm install
npm run typecheck     # Type checking
npm run lint          # Biome linting
npm run test:unit     # Unit tests
npm run test          # All tests (unit + integration)
npm run build         # Compile + bundle

License

MIT — Based on context-mode by Mert Koseoğlu.