Two different approaches to reducing Claude token usage. An honest, architectural comparison.
Headroom and mcp-injector both reduce Claude token costs, but they operate on entirely different parts of the problem. Headroom is a network proxy that intercepts dynamic tool outputs (logs, API responses, test results) and compresses them heuristically before they reach the model. mcp-injector is a persistent local daemon that uses deterministic AST body-folding to compress the static codebase structure. They are largely complementary, not alternatives.
| Feature / Aspect | mcp-injector | Headroom |
|---|---|---|
| What it compresses | ✅ Codebase structure (static) Pre-indexes source files. AST-folds function bodies. Serves compressed snapshots of your repository architecture. |
✅ Tool outputs & logs (dynamic) Intercepts claude tool call results, test output, git diffs, JSON responses — compresses them before they enter context. |
| Compression approach | ✅ Deterministic AST folding Structurally safe. Retains all type signatures, imports, interfaces. Only removes function bodies. Output is byte-identical across runs. |
⚠️ Heuristic / AI-based Uses LLM-guided and rule-based compression. Effective but non-deterministic — output varies per run, causing prompt cache misses. |
| Silent failure risk | ✅ None (structural, not lossy) AST folding cannot omit a compiler warning or error message — those aren't function bodies. Architecturally safe for agentic loops. |
⚠️ Possible on edge cases Heuristic truncation of tool output can omit critical warnings or non-zero exit codes. Documented concern in the developer community. |
| Integration model | ✅ Native MCP server (stdio) Runs as a local daemon. IDE spawns it as a subprocess. No network proxy, no traffic interception. |
⚠️ Network proxy / CLI wrapper Intercepts at the API call layer. Works as a macOS menu bar app, Python library, OpenAI-compatible proxy, or CLI wrapper. |
| Prompt cache hits | ✅ 100% deterministic (maximum hits) Byte-identical output. Alphabetically sorted files, timestamps stripped. Anthropic KV cache fires on every request after the first. |
❌ Non-deterministic (frequent misses) Output varies per run. Cache prefix breaks. You pay for full write cost more often than necessary. |
| Source / License | ❌ Closed-source binary Commercial. Free tier: 50k LOC, no account. Pro: $12/month for unlimited monorepos. |
✅ Open-source core (MIT) Core CLI is open source. Commercial macOS app: Pro $3/mo, Max x5 $12/mo, Max x20 $24/mo. |
| What it does NOT address | ❌ Dynamic runtime outputs Does not compress tool call results, test logs, or API responses at runtime. These are Headroom's domain. |
❌ Codebase structure Does not pre-index codebases or provide AST-level structural compression for architectural navigation. |
| Best for | Developers loading large codebases repeatedly into Claude Code, Cursor, or VS Code for architectural navigation and editing. | Developers running long agentic loops where tool outputs (test runners, build logs, search results) dominate context growth. |
The fundamental distinction is what gets compressed and how. mcp-injector operates pre-flight: before any LLM call, your codebase is indexed and structurally folded. The result is deterministic — the same AST fold every time. This is mathematically safe because function bodies are the only thing removed, and AST parsers don't make mistakes about what constitutes a function body.
Headroom operates in-flight: it intercepts the dynamic outputs of tools and applies heuristic or AI-guided compression to reduce their size. This is powerful for runtime verbosity (test output, git diffs, JSON payloads) but carries inherent risk: any heuristic that processes unstructured text can, in edge cases, truncate content the agent needs. The developer community's significant debate about RTK and Headroom's "token compression illusion" centers precisely on this class of failure.
Yes. They target different token sources. mcp-injector compresses the codebase you load for architectural context. Headroom compresses what flows back from tools during task execution. A workflow using both would see compressive effects at both phases, independently. There is no known conflict between them.
If your primary usage is codebase-heavy architectural sessions (loading a large repository to understand structure, navigate unfamiliar code, make cross-file changes), start with mcp-injector. The free tier covers 50,000 lines with no account required. If your primary pain is long agentic task runs where test logs and build output dominate your context growth, Headroom's domain is more relevant.
The benchmarks for mcp-injector's codebase compression are at foldwork.dev/benchmarks. Installation guide at foldwork.dev/docs.