context-compress 2026.5.0 → 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

@@ -3,16 +3,17 @@
 # context-compress
 
 **Stop drowning your AI agent in shell output.**
-Compress tool output before it hits the context window — through an MCP server, a drop-in CLI, or both.
+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/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-213%20passing-success)](#contributing)
+[![Tests](https://img.shields.io/badge/tests-unit%20%2B%20integration-success)](#contributing)
 
-[Quickstart](#quickstart) · [Compression Modes](#compression-modes) · [vs RTK](#head-to-head-with-rtk) · [How It Works](#how-it-works) · [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>
 
@@ -27,9 +28,9 @@ Compress tool output before it hits the context window — through an MCP server
 </td>
 <td align="center" width="25%">
 
-**+10.5pp**
-<br>over RTK
-<br><sub>same commands</sub>
+**Searchable**
+<br>raw data retained
+<br><sub>FTS5 + BM25</sub>
 
 </td>
 <td align="center" width="25%">
@@ -41,9 +42,9 @@ Compress tool output before it hits the context window — through an MCP server
 </td>
 <td align="center" width="25%">
 
-**8 MCP tools**
-<br>+ standalone CLI
-<br><sub>RTK-compatible wrap</sub>
+**Plugins**
+<br>Codex + Claude
+<br><sub>MCP • hooks • skills</sub>
 
 </td>
 </tr>
@@ -121,6 +122,18 @@ It works in two modes that compose freely:
 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
 
 ```bash
@@ -290,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
@@ -335,8 +350,8 @@ CONTEXT_COMPRESS_NUDGE_GREP=0
 # Compression mode: conservative | balanced (default) | aggressive | auto
 CONTEXT_COMPRESS_MODE=balanced
 
-# Auto mode prefers the Anthropic API when this is set (faster than `claude -p` fallback)
-ANTHROPIC_API_KEY=sk-ant-...
+# 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
@@ -448,7 +463,7 @@ context-compress/
 │       ├── doctor.ts         # `doctor` — diagnostics
 │       └── uninstall.ts      # `uninstall` — clean removal
 ├── tests/
-│   ├── unit/                 # 18 unit test files (213 tests, all passing)
+│   ├── unit/                 # 18 unit test files
 │   └── integration/          # 3 integration test files
 ├── scripts/
 │   ├── benchmark.ts          # Synthetic compression benchmark
@@ -516,6 +531,8 @@ RTK_BIN=... tsx scripts/benchmark-vs-rtk.ts --auto    # also run LLM-judged auto
 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

package/docs/agentic-benchmark.md

@@ -0,0 +1,110 @@
+# Agentic Benchmark Plan
+
+This benchmark measures context-compress in real agent sessions, not synthetic command output alone.
+
+The claim to test:
+
+> Large tool output should stay searchable outside the conversation, while the agent still solves the same task with less context pressure.
+
+## Why This Exists
+
+`docs/token-reduction-report.md` measures byte and token reduction for common operations. That is necessary, but it does not fully answer whether an agent remains effective across a real coding task.
+
+This benchmark adds the missing layer: run the same task with and without context-compress, isolate each arm, and compare context usage, task success, cost, and time.
+
+## Arms
+
+| Arm | Setup | Purpose |
+| --- | --- | --- |
+| `baseline` | No context-compress MCP, no hook | Measures normal agent behavior. |
+| `mcp-only` | MCP server registered, no PreToolUse hook | Measures explicit tool adoption. |
+| `hook-balanced` | MCP plus PreToolUse hook, `CONTEXT_COMPRESS_MODE=balanced` | Default recommended setup. |
+| `hook-aggressive` | MCP plus PreToolUse hook, `CONTEXT_COMPRESS_MODE=aggressive` | Maximum compression trade-off. |
+
+Each arm must run in a fresh workspace with isolated agent settings. Do not allow global plugins, global MCP servers, or previous conversation state to leak into the run.
+
+## Task Set
+
+Use tasks that naturally produce large outputs:
+
+1. Diagnose a failing test suite and patch the root cause.
+2. Review a multi-commit diff and summarize risky changes.
+3. Inspect a large API response and implement one missing field mapping.
+4. Analyze a generated Playwright snapshot and fix one selector bug.
+5. Audit dependency output and identify one vulnerable or outdated package.
+6. Search a large log file and explain the first recurring failure.
+
+Pin every input repository and fixture by commit hash. Preserve every run directory so metrics can be recomputed.
+
+## Metrics
+
+| Metric | How to collect |
+| --- | --- |
+| Context bytes returned by tools | Sum raw tool payloads in agent logs. |
+| Compressed bytes returned | Sum context-compress tool responses. |
+| Indexed bytes | Use `stats` output and session DB stats. |
+| Task success | Deterministic test, assertion, or scorer per task. |
+| Cost/time | Agent runner JSON output when available. |
+| Follow-up retrieval quality | Count whether the final answer cites indexed/search results when needed. |
+
+Report raw numbers and relative deltas. Do not only report the best percentage.
+
+## Isolation Rules
+
+- Use a new temp workspace for every `(task, arm, run)` cell.
+- Disable user/global plugin sources for the baseline arm.
+- Install exactly the intended plugin or MCP config for non-baseline arms.
+- Clear persistent context-compress DBs between runs unless the task explicitly tests persistence.
+- Keep model, prompt, timeout, and working tree identical across arms.
+- Record the exact agent version, model, OS, Node version, and context-compress version.
+
+## Safety Checks
+
+Compression must not hide important failures. Every task needs one deterministic scorer:
+
+- tests pass after the agent patch,
+- expected files changed and unrelated files did not,
+- security-relevant details are still retrievable with `search`,
+- final answer includes the actual root cause, not just a compressed summary.
+
+If an arm uses fewer tokens but fails the scorer, mark it as a failure, not a win.
+
+## Reporting Template
+
+```md
+# Agentic benchmark: context-compress on real coding tasks
+
+Date:
+Agent:
+Model:
+context-compress:
+Repo/fixture commits:
+
+## Summary
+
+| Arm | Success | Tool bytes in context | Indexed bytes | Cost | Time |
+| --- | ---: | ---: | ---: | ---: | ---: |
+
+## Per-task Results
+
+| Task | Arm | Success | Tool bytes | Indexed bytes | Notes |
+| --- | --- | ---: | ---: | ---: | --- |
+
+## Failures And Limits
+
+- What failed:
+- What this benchmark does not prove:
+- Known nondeterminism:
+```
+
+## Reproduce
+
+Until this harness is automated, run the benchmark manually with:
+
+```bash
+npm run build
+context-compress setup --auto
+CONTEXT_COMPRESS_MODE=balanced context-compress doctor
+```
+
+Then run each task in isolated agent settings and attach the resulting logs plus `context-compress stats` output to the benchmark result.

package/hooks/claude-codex-hooks.json

@@ -0,0 +1,19 @@
+{
+  "description": "context-compress PreToolUse hooks for Claude-compatible plugin hosts",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read|Grep|WebFetch|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v node >/dev/null 2>&1 && CONTEXT_COMPRESS_FILTER_BASH=1 CONTEXT_COMPRESS_BIN=\"node ${CLAUDE_PLUGIN_ROOT}/dist/cli/index.js\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs\" || exit 0",
+            "commandWindows": "if (Get-Command node -ErrorAction SilentlyContinue) { $env:CONTEXT_COMPRESS_FILTER_BASH='1'; $env:CONTEXT_COMPRESS_BIN='context-compress'; node \"$env:CLAUDE_PLUGIN_ROOT\\hooks\\pretooluse.mjs\" }",
+            "timeout": 5,
+            "statusMessage": "Protecting context window..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-compress",
-  "version": "2026.5.0",
+  "version": "2026.6.0",
   "description": "Context-aware MCP server that compresses tool output for Claude Code",
   "type": "module",
   "main": "dist/server.js",
@@ -38,6 +38,9 @@
     "typescript": "^5.7.0"
   },
   "files": [
+    ".codex-plugin/",
+    ".claude-plugin/",
+    ".mcp.json",
     "dist/",
     "docs/",
     "hooks/",
@@ -46,10 +49,10 @@
     "README.md"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Open330/context-compress"
-  },
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Open330/context-compress.git"
+	},
   "keywords": [
     "mcp",
     "claude",

package/skills/context-compress-audit/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: context-compress-audit
+description: Audit a repository, plugin setup, or agent session for raw Bash, Read, WebFetch, and MCP outputs that should be routed through context-compress instead. Use when asked to find context waste, raw tool output waste, missing plugin routing, or places where large command/file/web output still enters the agent context window.
+---
+
+# Context-Compress Audit
+
+Find places where large raw output can still enter the agent context window.
+
+## Procedure
+
+1. Run `mcp__context-compress__stats` first if the tool is available.
+2. Inspect setup surfaces that control routing:
+   - `.codex-plugin/plugin.json`
+   - `.claude-plugin/plugin.json`
+   - `.mcp.json`
+   - `hooks/`
+   - `skills/`
+   - README install instructions
+3. Search for risky guidance or examples that encourage raw output:
+   - `Bash` for tests, logs, `git log`, `git diff`, `curl`, `kubectl`, `docker`, `npm test`
+   - `Read` for large logs, bundled files, snapshots, CSV/JSON dumps
+   - `WebFetch` for documentation pages that should use `fetch_and_index`
+   - Playwright snapshots without a file/index/search path
+4. Report only actionable findings. Prefer one-line fixes that route work through:
+   - `batch_execute` for several commands plus searches
+   - `execute` for command/API output that must be analyzed first
+   - `execute_file` for large local files
+   - `fetch_and_index` plus `search` for web documentation
+
+## Output
+
+Use this format:
+
+```md
+## Context-Compress Audit
+
+- [severity] file:line - raw-output risk. Replace with <tool/workflow>.
+- [severity] file:line - missing install/routing coverage. Add <specific fix>.
+
+Summary: <N> findings, estimated impact <low|medium|high>.
+```
+
+Severity:
+- `high`: large output can enter context by default.
+- `medium`: docs/examples teach a wasteful path.
+- `low`: minor wording, missing cross-link, or optional setup gap.
+
+If nothing meaningful is found, say `No raw-output waste found. Routing looks covered.`

package/skills/context-compress-audit/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Context Compress Audit"
+  short_description: "Find raw-output context waste."
+  default_prompt: "Use $context-compress-audit to audit this project for raw tool output waste and missing routing."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "context-compress"
+      description: "Context-compress MCP server for stats and indexed search."
+
+policy:
+  allow_implicit_invocation: true