context-compress 2026.3.22 → 2026.6.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "context-compress",
+  "description": "MCP server and hook toolkit that keeps large tool output searchable instead of dumping it into context.",
+  "owner": {
+    "name": "Open330",
+    "url": "https://github.com/Open330"
+  },
+  "plugins": [
+    {
+      "name": "context-compress",
+      "description": "Compress Bash, Read, WebFetch, logs, tests, and API output before it reaches the context window.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "context-compress",
+  "version": "2026.6.0",
+  "description": "Keep large tool output searchable without flooding the agent context window.",
+  "author": {
+    "name": "Open330",
+    "url": "https://github.com/Open330"
+  },
+  "skills": "./skills/",
+  "hooks": "./hooks/claude-codex-hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "context-compress",
+  "version": "2026.6.0",
+  "description": "Keep large tool output searchable without flooding the agent context window.",
+  "author": {
+    "name": "Open330",
+    "url": "https://github.com/Open330"
+  },
+  "homepage": "https://github.com/Open330/context-compress",
+  "repository": "https://github.com/Open330/context-compress",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "context-window",
+    "token-optimization",
+    "developer-tools"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Context Compress",
+    "shortDescription": "Compress tool output before it enters context.",
+    "longDescription": "Run commands, fetch pages, index large outputs, and search the retained data through an MCP server so agents see concise answers instead of raw logs.",
+    "developerName": "Open330",
+    "category": "Productivity",
+    "capabilities": [
+      "MCP",
+      "Skills",
+      "Token optimization"
+    ],
+    "websiteURL": "https://github.com/Open330/context-compress",
+    "brandColor": "#2563EB",
+    "defaultPrompt": [
+      "Run tests through context-compress and summarize failures.",
+      "Index this large output and search it for root causes.",
+      "Audit this session for raw tool output waste."
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "context-compress": {
+      "cwd": ".",
+      "command": "node",
+      "args": [
+        "./dist/index.js"
+      ]
+    }
+  }
+}

package/README.md

@@ -2,22 +2,76 @@
 
 # context-compress
 
-**Keep your context window lean. Let the sandbox do the heavy lifting.**
+**Stop drowning your AI agent in shell output.**
+Large tool output stays searchable — not stuffed into the context window.
+Use it through an MCP server, a drop-in CLI, agent plugins, or all three.
 
-[![CI](https://github.com/Open330/context-compress/actions/workflows/ci.yml/badge.svg)](https://github.com/Open330/context-compress/actions)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![CI](https://github.com/Open330/context-compress/actions/workflows/ci.yml/badge.svg)](https://github.com/Open330/context-compress/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/context-compress?color=cb3837&logo=npm)](https://www.npmjs.com/package/context-compress)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-brightgreen?logo=nodedotjs&logoColor=white)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](tsconfig.json)
+[![Tests](https://img.shields.io/badge/tests-unit%20%2B%20integration-success)](#contributing)
 
-A context-aware **MCP server** for [Claude Code](https://claude.ai/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](#quickstart-for-agents) · [Getting Started](#getting-started) · [How It Works](#how-it-works) · [Token Reduction](#token-reduction) · [Configuration](#configuration) · [CLI](#cli) · [Changelog](CHANGELOG.md)
+[Quickstart](#quickstart) · [Plugin Support](#plugin-support) · [Compression Modes](#compression-modes) · [vs RTK](#head-to-head-with-rtk) · [How It Works](#how-it-works) · [Configuration](#configuration) · [CLI](#cli) · [Changelog](CHANGELOG.md)
 
 </div>
 
+<table align="center">
+<tr>
+<td align="center" width="25%">
+
+**93%**
+<br>token reduction
+<br><sub>aggressive mode</sub>
+
+</td>
+<td align="center" width="25%">
+
+**Searchable**
+<br>raw data retained
+<br><sub>FTS5 + BM25</sub>
+
+</td>
+<td align="center" width="25%">
+
+**4 modes**
+<br>incl. LLM-judged
+<br><sub>auto • aggressive • balanced • conservative</sub>
+
+</td>
+<td align="center" width="25%">
+
+**Plugins**
+<br>Codex + Claude
+<br><sub>MCP • hooks • skills</sub>
+
+</td>
+</tr>
+</table>
+
 ---
 
-## Quickstart for Agents
+## Quickstart
+
+```bash
+# 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](https://github.com/rtk-ai/rtk). See [CLI](#cli).
+
+<details>
+<summary><b>Quickstart for AI agents</b> — paste this prompt and your agent will install it</summary>
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/header.svg?theme=claude-code&title=context-compress&lang=Agents&mascot=thinking" width="100%" /></div>
 
@@ -27,7 +81,7 @@ Raw data stays in sandboxed subprocesses, only concise summaries enter your cont
 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 setup --auto
 context-compress doctor
 
 More info: https://github.com/Open330/context-compress
@@ -35,6 +89,8 @@ More info: https://github.com/Open330/context-compress
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/footer.svg?theme=claude-code&project=context-compress" width="100%" /></div>
 
+</details>
+
 ---
 
 ## Why?
@@ -49,6 +105,11 @@ Before:  git log --oneline -100  →  8.2KB into context
 After:   execute("git log ...")  →  0.3KB summary + full 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](https://github.com/rtk-ai/rtk) and friends. The PreToolUse hook can route `Bash` calls through it transparently when `CONTEXT_COMPRESS_FILTER_BASH=1`.
+
 > Based on [context-mode](https://github.com/mksglu/claude-context-mode) by Mert Koseoğlu — rewritten in TypeScript with security hardening, architectural improvements, and better DX.
 
 ---
@@ -61,7 +122,27 @@ After:   execute("git log ...")  →  0.3KB summary + full data searchable in FT
 npm install -g context-compress
 ```
 
-### Add to Claude Code
+### 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
+
+```bash
+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
 
 ```bash
 claude mcp add context-compress -- node $(which context-compress)
@@ -115,7 +196,7 @@ context-compress doctor
 └─────────────────────────────────────────────────────────┘
 ```
 
-### 7 MCP Tools
+### 8 MCP Tools
 
 | Tool | What it does |
 |:-----|:-------------|
@@ -125,7 +206,8 @@ context-compress doctor
 | **`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. |
+| **`stats`** | Session + cumulative statistics: bytes saved, tokens avoided, savings ratio. |
+| **`discover`** | Lists indexed sources, top searchable terms, and suggests next actions. |
 
 ### Supported Languages
 
@@ -135,6 +217,68 @@ context-compress doctor
 
 ---
 
+## 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 |
+
+```bash
+# 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.
+
+### Head-to-head with [RTK](https://github.com/rtk-ai/rtk)
+
+Reproduce locally:
+
+```bash
+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%) |
+| **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:
+
+1. **`balanced` is 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.
+2. **`aggressive` decisively 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.
+3. **`auto` lets the model pick.** Per-command LLM judgment landed at 77.9% overall — between balanced and aggressive. The interesting result is *what* it picked: `balanced` for git/test outputs (where commit bodies and failure detail matter), `aggressive` for `ls -laR` and `find` (where the question is "what's there?", not "show me everything"), `conservative` for 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*` drops `total N`, `.`/`..` entries (universal noise) but keeps perms/dates
+- `git log` keeps headers + first 3 body lines per commit, replacing the rest with `[+N lines omitted]`
+- `find` / `ls -R` summarizes per-directory once output exceeds 20 entries
+- 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 for `aggressive` when the question is "what changed", `balanced` when the question is "explain why".
+
+---
+
 ## Token Reduction
 
 context-compress achieves **99.2% token reduction** across a typical 12-operation coding session.
@@ -159,6 +303,8 @@ Without context-compress, 12 operations consume **133% of the 200K context windo
 
 **[Read the full Token Reduction Report](docs/token-reduction-report.md)** — includes cost analysis, architecture deep-dive, and FAQ on context loss trade-offs.
 
+**[Read the Agentic Benchmark Plan](docs/agentic-benchmark.md)** — 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
@@ -200,6 +346,18 @@ CONTEXT_COMPRESS_BLOCK_WEBFETCH=0
 # Disable Read/Grep nudges
 CONTEXT_COMPRESS_NUDGE_READ=0
 CONTEXT_COMPRESS_NUDGE_GREP=0
+
+# Compression mode: conservative | balanced (default) | aggressive | auto
+CONTEXT_COMPRESS_MODE=balanced
+
+# Auto mode prefers the Anthropic API when ANTHROPIC_API_KEY is set
+# in your shell or secret manager (faster than `claude -p` fallback)
+
+# RTK-style transparent Bash wrapping (default: off)
+CONTEXT_COMPRESS_FILTER_BASH=1
+
+# Override path to the context-compress binary used by the hook
+CONTEXT_COMPRESS_BIN=/usr/local/bin/context-compress
 ```
 
 ### Config File
@@ -220,12 +378,24 @@ Create `.context-compress.json` in your project root or home directory:
 ## CLI
 
 ```bash
-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
+context-compress                            # Start MCP server (stdio)
+context-compress setup                      # Detect runtimes, show install instructions
+context-compress setup --auto               # One-line: write ~/.claude/settings.json
+context-compress init --auto                # Alias for setup --auto
+context-compress doctor                     # Diagnose: runtimes, hooks, FTS5, version
+context-compress uninstall                  # Clean removal: hooks, MCP reg, stale DBs
+
+# RTK-style transparent compression — use anywhere, agent doesn't need MCP
+context-compress wrap "npm test"                       # default = balanced
+context-compress wrap --mode aggressive "git log -50"  # max compression
+context-compress wrap --stream "tail -f /var/log/app.log"  # line-by-line for long-running cmds
+context-compress filter --cmd "git push" < captured.log    # pipe filter
 ```
 
+### Bash auto-wrap (transparent mode)
+
+Set `CONTEXT_COMPRESS_FILTER_BASH=1` and the PreToolUse hook will route output-heavy `Bash` calls through `context-compress wrap` automatically — the agent doesn't need to call `execute()` to benefit. Combine with `CONTEXT_COMPRESS_MODE=aggressive` for maximum compression.
+
 ### Doctor Output Example
 
 ```
@@ -235,9 +405,10 @@ context-compress uninstall  # Clean removal: hooks, MCP reg, stale DBs
   [PASS] Language coverage: 7/11 (64%)
   [PASS] Server test: OK
   [PASS] PreToolUse hook configured
+  [PASS] Hook integrity: SHA-256 verified (a3f1c8d2e4...)
   [PASS] FTS5 / better-sqlite3 works
 
-  Version: v2026.3.3
+  Version: v2026.5.0
   All checks passed.
 ```
 
@@ -248,46 +419,79 @@ context-compress uninstall  # Clean removal: hooks, MCP reg, stale DBs
 ```
 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
+│   ├── index.ts              # MCP server entry
+│   ├── server.ts             # Wires deps, registers tools (132 lines, was 845)
+│   ├── executor.ts           # SubprocessExecutor + ANSI/dedup pipeline
+│   ├── filters.ts            # Command-aware filters (git, npm, ls, find, ps, ...)
+│   ├── store.ts              # ContentStore (FTS5 + BM25 + Porter + trigram + Levenshtein)
+│   ├── network.ts            # SSRF / DNS rebinding protection
+│   ├── stats.ts              # Session + cumulative session tracker
+│   ├── config.ts             # Config: ENV → file → defaults
 │   ├── snippet.ts            # FTS5 snippet extraction
-│   ├── stats.ts              # Session tracker
+│   ├── logger.ts             # Debug logger
 │   ├── types.ts              # Shared types
+│   ├── utils.ts              # detectInjectionPatterns, limitConcurrency, formatBytes
 │   ├── runtime/
+│   │   ├── index.ts          # Parallel runtime detection + registry
 │   │   ├── plugin.ts         # LanguagePlugin interface
-│   │   ├── index.ts          # Registry + parallel detection
-│   │   └── languages/        # 11 language plugins
+│   │   └── languages/        # 11 language plugins (js, ts, py, sh, rb, go, rs, php, pl, r, ex)
+│   ├── tools/                # MCP tool handlers (one file per tool)
+│   │   ├── context.ts        # Shared ToolContext interface
+│   │   ├── execute.ts
+│   │   ├── execute-file.ts
+│   │   ├── index-content.ts
+│   │   ├── search.ts
+│   │   ├── fetch-and-index.ts
+│   │   ├── batch-execute.ts
+│   │   ├── stats.ts
+│   │   └── discover.ts
+│   ├── util/                 # Pure utilities (extracted from server.ts for testability)
+│   │   ├── path.ts           # isWithinProject (path-traversal safe)
+│   │   ├── fetch-code.ts     # buildFetchCode (HTML→md sandbox script)
+│   │   ├── intent-filter.ts  # createIntentFilter factory
+│   │   ├── label.ts          # compactLabel (compression levels)
+│   │   ├── version.ts        # getVersion (deduped across CLI commands)
+│   │   ├── stream-compress.ts# Line-by-line StreamCompressor for `wrap --stream`
+│   │   └── auto-mode.ts      # LLM-driven mode selection (Anthropic API + claude CLI)
 │   ├── hooks/
-│   │   └── pretooluse.ts     # PreToolUse hook (no self-mod)
+│   │   └── pretooluse.ts     # PreToolUse hook (curl/Bash/Read/Grep/WebFetch/Task)
 │   └── cli/
-│       ├── index.ts          # CLI entry
-│       ├── setup.ts          # Interactive setup
-│       ├── doctor.ts         # Diagnostics
-│       └── uninstall.ts      # Clean removal
+│       ├── index.ts          # CLI dispatcher
+│       ├── lite.ts           # Single-binary entry (filter+wrap only, no MCP)
+│       ├── filter.ts         # `filter` (stdin) + `wrap` (spawn) commands
+│       ├── setup.ts          # `setup` / `init` — interactive + --auto
+│       ├── doctor.ts         # `doctor` — diagnostics
+│       └── uninstall.ts      # `uninstall` — clean removal
 ├── tests/
-│   ├── unit/                 # 7 unit test files
+│   ├── unit/                 # 18 unit test files
 │   └── integration/          # 3 integration test files
-├── hooks/
-│   └── hooks.json            # Hook matcher config
+├── scripts/
+│   ├── benchmark.ts          # Synthetic compression benchmark
+│   ├── benchmark-real.ts     # Real-command benchmark on this repo
+│   └── benchmark-vs-rtk.ts   # Head-to-head vs RTK with --auto support
+├── hooks/                    # Pre-built hook bundle (shipped in npm package)
 ├── skills/                   # Slash command definitions
-└── dist/                     # Compiled output
+├── docs/                     # Token reduction report + architecture docs
+└── dist/                     # Compiled output (build artifact)
 ```
 
+> `server.ts` is now thin (132 lines) — it constructs deps, builds a `ToolContext`, registers the 8 tool modules, and wires shutdown. All tool handlers live under `src/tools/`, all reusable helpers under `src/util/`.
+
 ---
 
 ## 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 |
+| Credential leakage | `passthroughEnvVars` defaults to `[]` — zero env vars passed to subprocesses unless opted in |
+| Shell injection | `execFileSync` with array arguments throughout — no string interpolation into shells |
+| SSRF / private-IP fetch | `fetch_and_index` blocks RFC1918, link-local, loopback, IPv4-mapped IPv6 (incl. hex form `::ffff:HHHH:HHHH`), CGNAT |
+| DNS rebinding (TOCTOU) | `resolveAndValidate` + URL pinning to the resolved IP with original `Host` header preserved |
+| Path traversal | `isWithinProject` uses `realpathSync` to defeat symlink escapes; falls back to string-prefix for not-yet-existing paths |
+| Hook self-modification | Hooks are read-only — no `fs.writeFileSync` in `src/hooks/`. Hook integrity SHA-256 verified by `doctor` |
+| Arbitrary code execution | No `upgrade` command — no `git clone` or `npm install` at runtime. Setup writes only to `~/.claude/settings.json` |
+| Silent failures | `CONTEXT_COMPRESS_DEBUG=1` surfaces all catch-block errors to stderr |
+| Subprocess sandboxing | OS-level sandboxing not enforced (by design for the MCP trust model). See [SECURITY.md](SECURITY.md) for the full trust model. |
 
 ---
 
@@ -297,15 +501,42 @@ context-compress/
 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
+
+npm run typecheck        # Strict TS
+npm run lint             # Biome
+npm test                 # All tests (unit + integration)
+npm run test:unit        # Unit tests only
+
+npm run build            # Compile + bundle MCP server + CLI
+npm run build:hooks      # Bundle the PreToolUse hook (with SHA-256)
+npm run build:bin        # Cross-compile single binaries via Bun (4 targets)
 ```
 
+### Reproducing the benchmarks
+
+```bash
+# Synthetic — fast, reproducible, includes RTK-style commands
+tsx scripts/benchmark.ts
+
+# Real-world — runs actual commands in your repo
+tsx scripts/benchmark-real.ts            # full
+tsx scripts/benchmark-real.ts --quick    # skip npm test
+
+# Head-to-head with RTK (build it first)
+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
+RTK_BIN=... tsx scripts/benchmark-vs-rtk.ts --auto    # also run LLM-judged auto mode
+RTK_BIN=... tsx scripts/benchmark-vs-rtk.ts --json    # machine-readable
+```
+
+For real agent sessions, use [docs/agentic-benchmark.md](docs/agentic-benchmark.md) to compare baseline, MCP-only, hook-balanced, and hook-aggressive arms with isolated settings.
+
 ---
 
 ## License
 
 [MIT](LICENSE) — Based on [context-mode](https://github.com/mksglu/claude-context-mode) by Mert Koseoğlu.
+
+> **Inspired by [RTK](https://github.com/rtk-ai/rtk)** for the command-aware filtering tactic. context-compress builds on the same idea with multi-mode trade-offs, an LLM-judged `auto` mode, MCP integration, sandbox execution, and a searchable knowledge base.

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA8BA,wBAAsB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAiI9C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAsBA,wBAAsB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAiI9C"}

package/dist/cli/doctor.js

@@ -7,16 +7,8 @@ import Database from "better-sqlite3";
 import { loadConfig } from "../config.js";
 import { SubprocessExecutor } from "../executor.js";
 import { detectRuntimes, getRuntimeSummary, hasBun } from "../runtime/index.js";
+import { getVersion } from "../util/version.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-function getVersion() {
-    try {
-        const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "..", "package.json"), "utf-8"));
-        return pkg.version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
 function readSettings() {
     try {
         const path = resolve(homedir(), ".claude", "settings.json");
@@ -138,7 +130,7 @@ export async function doctor() {
         console.log(`  [FAIL] FTS5: ${msg}`);
     }
     // 6. Version
-    const version = getVersion();
+    const version = getVersion("unknown");
     console.log(`\n  Version: v${version}`);
     // Summary
     console.log();

package/dist/cli/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/filter.d.ts

@@ -0,0 +1,52 @@
+import { type FilterMode, type RequestedMode } from "../filters.js";
+/**
+ * Apply the full context-compress output pipeline to a buffer.
+ *
+ *   conservative: ANSI strip only — preserve everything else.
+ *   balanced:     ANSI strip → command filter (drops universal noise:
+ *                 progress bars, hint lines, ./.., 'total N', truncates
+ *                 git log bodies past 3 lines) → dedup/group (if >5KB).
+ *                 Preserves all metadata (perms, dates, commit headers).
+ *   aggressive:   balanced + aggressive command filters that drop metadata
+ *                 (git log → oneline, ls -la → name+size, etc.) and lower
+ *                 the dedup threshold to 2KB.
+ *
+ * Mirrors what SubprocessExecutor does internally so the same compression
+ * is available to standalone shell commands or other agents that don't
+ * route through the MCP execute() tool.
+ */
+export declare function compressOutput(stdout: string, originalCmd?: string, mode?: FilterMode): string;
+/**
+ * Async variant that handles the "auto" meta-mode by asking an LLM to
+ * pick conservative/balanced/aggressive for the given command + output.
+ * Concrete modes route to the synchronous compressOutput.
+ */
+export declare function compressOutputAsync(stdout: string, originalCmd: string | undefined, mode?: RequestedMode): Promise<{
+    output: string;
+    resolvedMode: FilterMode;
+    autoSource?: string;
+}>;
+/**
+ * `context-compress filter [--cmd '<orig>'] [--mode conservative|balanced|aggressive|auto]`
+ * Reads stdin, applies the pipeline, writes to stdout. Exits 0.
+ */
+export declare function runFilter(args: string[]): Promise<number>;
+/**
+ * `context-compress wrap [--stream] -- <cmd ...>`
+ *
+ * Default (buffered): spawn cmd, capture all stdout, apply full pipeline,
+ * print filtered stdout, propagate child's exit code.
+ *
+ * `--stream`: emit filtered output line-by-line as the child produces it.
+ * Use for long-running commands (tail -f, cargo watch, builds with
+ * progressive output) where buffering would defer all output until exit.
+ * Stream mode applies ANSI strip + progress filter + adjacent dedup only —
+ * command-aware filters need the full output.
+ *
+ * Usage:
+ *   context-compress wrap "npm test"
+ *   context-compress wrap --stream "tail -f /var/log/app.log"
+ *   context-compress wrap -- npm test
+ */
+export declare function runWrap(args: string[]): Promise<number>;
+//# sourceMappingURL=filter.d.ts.map

package/dist/cli/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/cli/filter.ts"],"names":[],"mappings":"AAEA,OAAO,EAEN,KAAK,UAAU,EACf,KAAK,aAAa,EAGlB,MAAM,eAAe,CAAC;AAUvB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,GAAE,UAAyB,GAC7B,MAAM,CAgBR;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,GAAE,aAA4B,GAChC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,UAAU,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5E;AAoBD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAc/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0C7D"}