headroom

Headroom – Technical Briefing Prepared for a technical client – consultant‑grade, evidence‑based.

Overview

Headroom is a context‑optimization layer for LLM applications that losslessly strips boiler‑plate (logs, tool outputs, RAG chunks, etc.) from prompts, reducing token count while preserving answer accuracy. The repository is a portfolio of 8 self‑contained projects:

The headroom core (328 code files, 1 data file) implements compression, caching, proxy serving, and a CLI. It is used by the SDKs and the wrapper commands (headroom wrap claude, headroom proxy …).

Key metrics (static analysis, deterministic):

• 774 code files analysed (TypeScript 91, Python 671, JavaScript 4, Shell 8)
• 766 internal modules, 1 633 import edges, 65 modules in circular dependencies
• 3 473 functions, 527 classes named via tree‑sitter
• 541 test files, 398 doc files

How It Fits

Execution start points (entry‑point analysis):

Call graph highlights – the most‑connected functions (callers → callee, times):

• exists – 117 callers
• print – 108 callers
• set – 83 callers
• search – 60 callers
• SmartCrusherConfig – 47 callers

Hub with blast radius – headroom/__init__.py is imported by 67 modules; headroom/config.py defines 23 classes and is depended on by 23 modules. Circular imports exist in headroom/__init__.py, headroom/proxy/server.py, and headroom/cache/compression_store.py (instability 0.49‑0.03).

Files with the most responsibility (call volume, database I/O, crypto, network):

Traced paths that leave the process (shortest routes from entry points):

• main → resolve – filesystem binary_path.parent.mkdir
• run → load_locomo → download_locomo – cache mkdir, network urllib.request.urlretrieve
• init → _run_init_targets → _init_openclaw – subprocess subprocess.run
• start → _hydrate_persisted_state – crypto hashlib.sha256(key.encode()).hexdigest
• _verify_claude_local → _read_manifest – filesystem path.read_text

How To Use It

Real‑World Use

A typical RAG‑enabled agent receives a 10 k‑token context (logs + retrieved chunks). Running headroom.compress(messages, model="claude-sonnet-4-5") reduces the prompt to ~1.3 k tokens (≈87 % savings) while GSM8K accuracy stays at 0.870 and TruthfulQA improves by +0.030. The compressed payload is then sent to the LLM; the model can still call headroom_retrieve to recover original bytes if needed.

Code Health & Issues

Measured analysis (deterministic, 488 findings):

• High soundness – 14 modules in circular import cycles (e.g., headroom/__init__.py, headroom/proxy/server.py, headroom/cache/compression_store.py).
• High cognitive load – 21 files with max indentation depth 10; 10 files > 2 000 lines (headroom/proxy/server.py, headroom/transforms/smart_crusher.py, headroom/cache/compression_store.py).
• High clarity – Hub module headroom/__init__.py imported by 67 others; high‑churn risk.
• Medium resource safety – open(...) without with in headroom/proxy/server.py (potential leak).
• Medium resilience – 5 files with broad except clauses that swallow errors.
• Medium cognitive load – headroom/transforms/smart_crusher.py has 802 branch points over 2 671 lines.

Code‑health audit (11 findings, 0 critical):

The Bottom Line

Headroom delivers a substantial token reduction (≈87 %) with zero accuracy loss, making it attractive for any LLM‑driven agent that pays for token usage or wants snappier responses. The core compression engine is well‑structured but suffers from circular imports, oversized files, and a wildcard CORS policy that together raise security and maintainability risk. The audit surface is modest (11 findings, none critical) and most have clear, actionable fixes (pin SHAs, fix CORS, git‑ignore node_modules, switch to npm ci, add LFS for large binaries).

Who should use it: Teams building Retrieval‑augmented generation, tool‑heavy agents, or any deployment where prompt size drives cost or latency. Organizations that can address the listed hygiene items will gain the most stable, secure experience.