$ show headroomlabs-ai/headroom
Headroom is a context optimization layer for LLM applications that reduces token usage by 50-90% through intelligent compression, caching, and memory systems. It provides a transparent proxy between LLM clients (like Claude Code, Cursor, etc.) and LLM providers (Anthropic, OpenAI, etc.), implementing CCR (Compress-Cache-Retrieve) for lossless compression with retrieval capability. The system features a hybrid polyglot architecture with a Rust-based high-performance proxy core, Python ecosystem for extensibility, and TypeScript SDK. Key capabilities include agent wrapping, cross-agent memory using Qdrant/Neo4j, observability through metrics and dashboard, and a learning system that analyzes interaction patterns to generate optimization rules. Deployment options include Docker, system services, and direct execution.
The LLM identified 4 files worth highlighting for reuse:
Specialized compressor for JSON/structured data that preserves order and precision while achieving significant size reduction. Uses statistical analysis, outlier detection, and adaptive planning to determine optimal compression strategies. Self-contained with clear Transform interface, demonstrating non-obvious skill in adaptive algorithms that could be extracted for JSON compression in other domains.
Unified token counting abstraction that handles multiple LLM providers with consistent interface. Features provider-specific implementations, caching, error handling, and fallback estimation when specific tokenizers unavailable. Well-abstracted base class with clean separation of concerns, demonstrating skill in managing tokenizer ecosystem complexity while providing reliable counting for cost estimation and context window management.
Hierarchical memory system combining LRU cache with persistent backends (SQLite, FTS5, vector stores) and sync adapters for different storage systems. Implements hot/warm/cold storage patterns with clear interfaces for storage, indexing, and similarity search. Shows non-obvious skill in designing multi-layer storage that optimizes for access patterns while ensuring persistence and scalability.
Consistent abstraction layer for LLM providers that isolates provider-specific differences while exposing unified interface for token counting, context limits, and cost estimation. Features clean plugin architecture where new providers can be added by implementing base interfaces. Demonstrates skill in creating maintainable integration points that reduce coupling and simplify provider management.