Claude Code and Codex credits burn fast on real projects. Most of that cost isn't your prompts. It's tool outputs, file reads, logs, RAG chunks, all dumped into context with zero filtering.

The agent reads everything. Nothing governs what reaches the model.

Headroom: a context governance layer

Headroom (53k+ stars, open source) sits between your agent and the LLM. It classifies, compresses, and routes content before the model sees it. Runs locally, your data stays on your machine.

RTK (Tool Exit Governance) rewrites shell output before it enters the transcript. Headroom takes that idea to production scale. Same principle: intercept tool output before it hits the context window, reduce it, keep the original retrievable.

The flow: Agent -> Tool Output (rg, logs, JSON, diff) -> Headroom Context Router -> LLM.

Three things happen in that middle layer:

  1. Identify structure first. No generic summarizer. It recognizes what type of tool output it's looking at: search results, test logs, JSON tables, diffs, code files.

  2. Pick a compression strategy per type. JSON gets SmartCrusher. Code gets AST-aware CodeCompressor. Prose gets Kompress-v2-base. Different inputs, different treatment.

  3. Originals stay retrievable. The model sees the compressed view. When it needs the full content, it calls back through CCR (reversible compression) and gets the original on demand.

Three compressors in action

Search results (rg/grep): SearchCompressor parses file:line:match triples, merges hits from the same file into clusters, scores by query relevance and error signals, keeps top-scoring head/tail matches. The model gets: representative matches + surrounding lines + omitted count.

Logs (test/build): LogCompressor scans for ERROR/FAIL/WARN anchors, expands a context window around each error, binds stack traces to failed tests, drops pass/info/debug to summary. The model gets: failure signature + call stack + minimal repro clues.

JSON tables (thousands of rows): SmartCrusher parses arrays and fields, keeps small results lossless, does row selection on large results, preserves error/rare/first/last rows. The model gets: field schema outline + key rows + CCR reference for full retrieval.

CacheAligner also stabilizes prompt prefixes so provider KV caches hit more often.

Get started

pip install "headroom-ai[all]"
headroom wrap claude

Also supports proxy mode (headroom proxy --port 8787, zero code changes) and MCP server mode.

Real savings

Workload Before After Savings
Code search (100 results) 17,765 1,408 92%
SRE incident debugging 65,694 5,118 92%
Codebase exploration 78,502 41,254 47%

Accuracy on GSM8K, TruthfulQA, SQuAD v2, and BFCL stays at 97%+ after compression.

Caveats

  • Compression is lossy. Benchmarks hold, but test on your workflow before trusting it blindly.
  • Output token reduction (trimming what the model writes back) is off by default. Enable with HEADROOM_OUTPUT_SHAPER=1.
  • headroom learn mines failed sessions and writes corrections to CLAUDE.local.md. Review what it generates.

GitHub: headroomlabs-ai/headroom