context-compress MCP server
Commit Sep 12, 2026Compresses tool output to reduce context window token usage while retaining searchable data through an indexed knowledge base.
Also known as Open330/context-compress
- Stars
- 14
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 12, 2026
- License
- MIT
What is context-compress MCP?
context-compress compresses tool output to reduce context window token usage while retaining searchable data through an indexed knowledge base.
Summary generated from the project's README
About context-compress MCP server
Developers working with AI agents can reduce token consumption by compressing large tool outputs before they enter the context window. This server intercepts heavy command outputs, such as long git logs or test results, and replaces them with concise summaries while keeping the full data searchable in an indexed knowledge base. It is designed for use with Claude Code and Codex, supporting local installation via npm and providing a standalone CLI for wrapping shell commands.
The system offers four compression modes: conservative, balanced, aggressive, and auto. Users can choose between these modes via environment variables or CLI flags to balance detail against token savings. The server includes eight specialized tools including execute, search, batch_execute, and fetch_and_index. It supports running code in eleven different languages, including Python, TypeScript, and Rust, and uses FTS5 with BM25 for efficient data retrieval from its internal index.
What you can do with it
- 1Reduce token usage from shell commandsAn agent can run a large command and receive a compressed summary instead of thousands of tokens of raw text.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
CONTEXT_COMPRESS_BINCONTEXT_COMPRESS_BLOCK_CURLCONTEXT_COMPRESS_BLOCK_WEBFETCHCONTEXT_COMPRESS_FILTER_BASHCONTEXT_COMPRESS_MODECONTEXT_COMPRESS_NUDGE_GREPCONTEXT_COMPRESS_NUDGE_READCONTEXT_COMPRESS_ROUTE_SUBAGENTSRTK_BIN
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableopen330/context-compress is public and reachablegithub.com/open330/context-compress ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-12github.com/open330/context-compress ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcontext-compress
Stop drowning your AI agent in shell output. Large tool output stays searchable in index-backed flows — not stuffed into the context window. Use it through an MCP server, a drop-in CLI, agent plugins, or all three.
Quickstart · Plugin Support · Compression Modes · vs RTK · How It Works · Configuration · CLI · Changelog
93% token reduction aggressive mode
Searchable indexed data retained FTS5 + BM25
4 modes incl. LLM-judged auto • aggressive • balanced • conservative
Plugins Codex + Claude MCP • hooks • skills
Quickstart
# 1. Install
npm install -g context-compress
# 2. One-line setup — registers the MCP server, installs the hook,
# enables transparent Bash compression
context-compress setup --auto
# 3. (optional) Pick a mode for the session
export CONTEXT_COMPRESS_MODE=balanced # or: aggressive, conservative, auto
That's it. Restart Claude Code and shell output is now compressed before it enters context.
Prefer no MCP at all?
context-compress wrap "<cmd>"compresses any shell command's output — drop-in for RTK. See CLI.
Install context-compress — an MCP server that compresses tool output for Claude Code.
Only the printed or filtered response enters your context window.
For searchable retention, use index, fetch_and_index, batch_execute, or intent on a large execute call.
npm install -g context-compress
context-compress setup --auto
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(..., intent: "recent changes") → 0.3KB summary + bounded pre-filter data searchable in FTS5
It works in two modes that compose freely:
- MCP server — registers as a Claude Code MCP server with 8 tools (
execute,search,batch_execute,fetch_and_index,index,execute_file,stats,discover). Agents call them directly when output would be large. - Standalone CLI —
context-compress wrap "<cmd>"runs any shell command and pipes the output through the same compression pipeline. Drop-in for RTK and friends. The PreToolUse hook can routeBashcalls through it transparently whenCONTEXT_COMPRESS_FILTER_BASH=1. This is response-only compression: detail omitted by a filter is not indexed or available tosearch.
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
Plugin Support
context-compress now ships plugin metadata for agent hosts:
| Host | Files | What they enable |
|---|---|---|
| Codex | .codex-plugin/plugin.json, .mcp.json, skills/ |
MCP server registration plus skills in plugin-aware Codex flows. |
| Claude Code | .claude-plugin/plugin.json, .claude-plugin/marketplace.json, hooks/claude-codex-hooks.json |
PreToolUse routing, skills, and MCP config from a plugin install. |
| Manual / fallback | context-compress setup --auto |
Writes ~/.claude/settings.json directly when plugin installation is not available. |
The plugin manifests are designed for built package/archive installs where dist/, hooks/, and skills/ are present together. For a raw source checkout, run npm install && npm run build before testing the plugin locally, or use the global npm setup above.
One-line setup
context-compress setup --auto
Writes ~/.claude/settings.json for you: registers the MCP server, installs the PreToolUse hook, enables transparent Bash compression. Idempotent — re-running with the same paths makes zero changes. Preserves any unrelated user settings.
Manual setup
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 │
└─────────────────────────────────────────────────────────┘
The Store path applies only when a tool indexes content: index, fetch_and_index,
batch_execute, and large execute calls with intent. Ordinary execute calls
without intent and CLI wrap return compressed responses only; anything omitted
from those responses is not searchable later.
8 MCP Tools
| Tool | What it does |
|---|---|
execute |
Run code in 11 languages. With intent, large executor-capped pre-filter output is indexed; without it, omitted response detail is not searchable. |
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 |
Session + cumulative statistics: bytes saved, tokens avoided, savings ratio. |
discover |
Lists indexed sources, top searchable terms, and suggests next actions. |
Supported Languages
javascript · typescript · python · shell · ruby · go · rust · php · perl · r · elixir
Bun auto-detected for 3-5x faster JS/TS execution.
MCP protocol surface
Every tool is registered through registerTool() and advertises a human-readable title plus behavior annotations, so clients can gate them without guessing from the name:
| Tool | readOnlyHint |
destructiveHint |
openWorldHint |
|---|---|---|---|
execute, execute_file, batch_execute |
false | true | true |
fetch_and_index |
false | false | true |
index |
false | false | false |
search, stats, discover |
true | false | false |
No tool declares an outputSchema — that is deliberate. A tool with an output schema must return structuredContent and a serialized text copy for backwards compatibility, so the same payload is billed to the context window twice. For a server whose entire purpose is to shrink that window, text-only responses are the correct trade. tests/integration/tool-manifest.test.ts enforces both halves of this contract.
PreToolUse hook contract
The hook speaks the current hookSpecificOutput shape — permissionDecision paired with permissionDecisionReason, updatedInput to rewrite arguments, additionalContext to append guidance. The deprecated top-level decision / reason fields are never emitted. Blocked curl/wget/inline-HTTP calls are denied with the redirect in the reason rather than rewritten into an echo, which saves a shell round-trip and puts the alternative directly in front of the agent.
Compression Modes
context-compress offers four compression modes that trade fidelity for compactness. Pass --mode to the CLI, set CONTEXT_COMPRESS_MODE in your environment, or let the default (balanced) just work.
| Mode | Strategy | Use when |
|---|---|---|
conservative |
ANSI strip only — preserves every byte of meaningful content | You need full fidelity, debugging output, archival logs |
balanced (default) |
Strip noise (progress bars, deprecation warnings, hint lines) — keep metadata (commit bodies, file dates, full test failures) | Day-to-day agent work where context might be re-read |
aggressive |
Drop metadata too — git log → oneline, ls -la → name+size, find lower threshold, grep grouped | Maximum token savings; agent will rarely need the dropped detail |
auto |
An LLM (Anthropic API or claude -p) picks one of the above per command, based on a 500-byte sample of the output. Decisions cached for 24h |
You don't want to think about it — let the model judge per output |
Privacy note for
automode: the command line and a 500-byte output sample are sent to the Anthropic API (or the localclaudeCLI) — it is the only context-compress feature that sends your data anywhere. Common secret shapes (API keys, tokens,password=..., private keys, URL credentials) are scrubbed from both before sending, best-effort. If either may contain credentials, prefer a fixed mode.
# CLI flag (per-call override)
context-compress wrap --mode aggressive "git log -50"
# Env var (set once for the session)
export CONTEXT_COMPRESS_MODE=aggressive
The PreToolUse hook also forwards CONTEXT_COMPRESS_MODE automatically when wrapping Bash commands, so agents transparently get whatever mode you've configured.
Beyond mode selection
Three capabilities layer on top of the modes above. All are grounded in the 2026 agent-compression literature, whose central finding is that token-level extractive compression (LLMLingua-2, Selective Context) breaks agents by destroying action grammar — so context-compress only ever operates on whole structural units, never partial tokens.
- Format-aware compression — when no command-specific filter matches, output is compressed by its shape. Pretty-printed JSON is minified losslessly (balanced) or collapsed to a schema + sample (aggressive); NDJSON folds into per-shape summaries; repetitive logs fold into
template ×countvia variable masking (Drain-style). Error/warning lines are always kept verbatim, and balanced-mode JSON stays parseable. Typical wins: JSON −41% (still valid) to −96%, logs −98%. - Intent-conditioned summaries — pass
intenttoexecuteand large output is indexed from the executor-capped copy captured before lossy command, format, deduplication, and response-truncation filters. The top query-ranked sections are then inlined up to a byte budget (CONTEXT_COMPRESS_INTENT_BUDGET_BYTES, default 1800) instead of only listing section titles — fewer follow-upsearch()round-trips. Error lines are surfaced as a safety net. Withoutintent,executeonly returns its compressed response and does not retain omitted detail. - Self-tuning
automode (ACON-style) — when a command is compressed aggressively and then re-run fast (≤30s) repeatedly,autorecords the "regret" and downgrades that command one step to preserve fidelity. Downgrades only ever reduce compression, so a false positive costs tokens, never correctness. See the self-tuning table instats.
Verify fidelity yourself with the quality-regression benchmark, which measures survival of task-critical information, not just token ratio:
npm run bench:quality # report at docs/quality-regression-report.md
Head-to-head with RTK
Reproduce locally:
git clone https://github.com/rtk-ai/rtk /tmp/rtk && (cd /tmp/rtk && cargo build --release)
RTK_BIN=/tmp/rtk/target/release/rtk tsx scripts/benchmark-vs-rtk.ts
Result on this repository (RTK 0.39.0 vs context-compress 2026.5.0):
| Command | Raw | RTK | CC conservative |
CC balanced |
CC aggressive |
CC auto (LLM) |
|---|---|---|---|---|---|---|
git status |
577 B | 241 B (58%) | 577 B (0%) | 375 B (35%) | 187 B (68%) | balanced (35%) |
git log -10 (full) |
21.3 KB | 3.2 KB (85%) | 21.3 KB (0%) | 4.6 KB (79%) | 947 B (96%) | balanced (79%) |
git log -50 (full) |
36.9 KB | 10.1 KB (73%) | 36.9 KB (0%) | 12.3 KB (67%) | 3.2 KB (91%) | balanced (67%) |
git diff --stat |
425 B | 424 B (0%) | 425 B (0%) | 425 B (0%) | 425 B (0%) | balanced (0%) |
ls src/ |
149 B | 229 B (-54%) | 149 B (0%) | 149 B (0%) | 149 B (0%) | conservative (0%) |
ls -laR src/ |
3.8 KB | 229 B (94%) | 3.8 KB (0%) | 3.1 KB (19%) | 877 B (78%) | aggressive (78%) |
find *.ts |
1.0 KB | 589 B (44%) | 1.0 KB (0%) | 183 B (83%) | 183 B (83%) | aggressive (83%) |
npm test |
21.8 KB | 114 B (99%) | 16.7 KB (24%) | 120 B (99%) | 120 B (99%) | balanced (99%) |
The
npm testrow was measured onnode --testoutput. Jest and Vitest indent theirPASS/FAILbadges by one space; that shape was not compressed at all until v2026.7.2 — it came back marginally larger than the input. | Overall (byte-weighted) | 85.9 KB | 15.0 KB (82.5%) | 80.8 KB (6.0%) | 21.2 KB (75.4%) | 6.0 KB (93.0%) | 19.0 KB (77.9%) |
Three things to take from this table:
balancedis competitive on its own. The default mode hits ~75% reduction without dropping any metadata — agents get full commit headers, file perms/dates, and complete test failure detail. Only 7pp behind RTK while making a different fidelity trade-off.aggressivedecisively wins on raw compression — 93.0%, beating RTK by 10.5pp. Pick this when you want maximum token savings and the agent will rarely re-read the dropped detail.autolets the model pick. Per-command LLM judgment landed at 77.9% overall — between balanced and aggressive. The interesting result is what it picked:balancedfor git/test outputs (where commit bodies and failure detail matter),aggressiveforls -laRandfind(where the question is "what's there?", not "show me everything"),conservativefor tiny outputs where compression is pointless.
Aggressive mode covers a wider command surface than the table above hints — it also handles df (drops pseudo-filesystems), du (top-N by size), ps aux (PID/%CPU/%MEM/CMD only, drops kernel threads), npm ls (strips tree-drawing chars + deduped/extraneous markers), and grep/rg (groups by file, truncates long lines).
What balanced now does (over conservative):
ls -l*dropstotal N,./..entries (universal noise) but keeps perms/datesgit logkeeps headers + first 3 body lines per commit, replacing the rest with[+N lines omitted]find/ls -Rkeeps the first 20 entries verbatim, then summarizes the remainder per-directorykubectl get(>30 rows) folds healthy rows into per-namespace/status counts but keeps non-healthy rows verbatim; output with noSTATUScolumn (get svc,get events) keeps the first 20 rows verbatim instead, since there is nothing to fold on- Generic dedup/progress/group runs at 5KB instead of 10KB
RTK has a single fixed compression strategy — comparable to context-compress
aggressive. context-compress lets the agent choose: reach foraggressivewhen the question is "what changed",balancedwhen the question is "explain why".
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.
Searchable retention applies to
index,fetch_and_index,batch_execute, and largeexecutecalls withintent. Ordinaryexecuteandwrapcalls only compress the response, so filtered-out detail is not available tosearch. Small intent-filter inputs (≤5KB by default) pass through without indexing.
Read the full Token Reduction Report — includes cost analysis, architecture deep-dive, and FAQ on context loss trade-offs.
Read the Agentic Benchmark Plan — defines the fair on/off benchmark for real Claude Code sessions, including baseline isolation, task success checks, and reporting limits.
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
The MCP server loads its settings in this order: ENV vars → project
.context-compress.json → home .context-compress.json → defaults.
The standalone PreToolUse hook does not load that file; hook controls are
environment-only.
Server Environment Variables
Every server setting has an environment override. All of them are optional.
| Variable | Default | What it does |
|---|---|---|
CONTEXT_COMPRESS_DEBUG |
0 |
Log to stderr, including otherwise-silent catch blocks |
CONTEXT_COMPRESS_PASSTHROUGH_ENV |
(none) | Comma-separated env vars copied into subprocesses |
CONTEXT_COMPRESS_LEVEL |
normal |
normal | compact | ultra — scales every budget below |
CONTEXT_COMPRESS_MAX_OUTPUT_BYTES |
102400 |
Max bytes returned to the caller per execution |
CONTEXT_COMPRESS_HARD_CAP_BYTES |
16777216 |
Capture ceiling; the process is killed past it |
CONTEXT_COMPRESS_SEARCH_MAX_BYTES |
40960 |
Byte budget for a whole search response |
CONTEXT_COMPRESS_BATCH_MAX_BYTES |
81920 |
Byte budget for a whole batch_execute response |
CONTEXT_COMPRESS_SEARCH_LIMIT |
3 |
Results per query |
CONTEXT_COMPRESS_SEARCH_WINDOW_MS |
60000 |
Throttling window |
CONTEXT_COMPRESS_SEARCH_REDUCE_AFTER |
3 |
Calls in the window before results are reduced to 1 |
CONTEXT_COMPRESS_SEARCH_BLOCK_AFTER |
8 |
Calls in the window before search is refused |
CONTEXT_COMPRESS_INTENT_SEARCH_THRESHOLD |
5000 |
Output size above which intent triggers indexing |
CONTEXT_COMPRESS_INTENT_BUDGET_BYTES |
1800 |
Byte budget for content inlined into an intent summary |
CONTEXT_COMPRESS_PERSIST_DB |
0 |
Keep the knowledge base across restarts — see below |
CONTEXT_COMPRESS_DB_DIR |
(none) | Where the persistent database lives; implies persistence |
CONTEXT_COMPRESS_MODE |
balanced |
Default compression mode for filter/wrap |
The knowledge base is ephemeral by default
persistDb defaults to false: the database lives in a private temporary
directory and is deleted when the MCP server exits. Indexed content is
searchable for the life of that server process, not across restarts.
To keep it, set CONTEXT_COMPRESS_PERSIST_DB=1 (or dbDir), which stores it
under .context-compress/ in your project. A persistent store retains the most
recent maxIndexedSources (default 500) and prunes older ones, so it does not
grow without bound.
context-compress MCP questions
Is the compressed data still searchable?
Yes, large tool outputs can stay searchable in index-backed flows using FTS5 and BM25.