{"id":45653630,"url":"https://github.com/chopratejas/headroom","last_synced_at":"2026-04-18T18:09:45.906Z","repository":{"id":331711513,"uuid":"1129940957","full_name":"chopratejas/headroom","owner":"chopratejas","description":"The Context Optimization Layer for LLM Applications","archived":false,"fork":false,"pushed_at":"2026-04-11T18:05:13.000Z","size":37271,"stargazers_count":1269,"open_issues_count":33,"forks_count":113,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-04-11T18:07:10.016Z","etag":null,"topics":["agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization"],"latest_commit_sha":null,"homepage":"https://chopratejas.github.io/headroom/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chopratejas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["headroom-sdk"]}},"created_at":"2026-01-07T19:58:51.000Z","updated_at":"2026-04-11T18:05:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chopratejas/headroom","commit_stats":null,"previous_names":["chopratejas/headroom"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/chopratejas/headroom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chopratejas%2Fheadroom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chopratejas%2Fheadroom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chopratejas%2Fheadroom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chopratejas%2Fheadroom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chopratejas","download_url":"https://codeload.github.com/chopratejas/headroom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chopratejas%2Fheadroom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31978905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization"],"created_at":"2026-02-24T07:25:20.910Z","updated_at":"2026-04-18T18:09:45.900Z","avatar_url":"https://github.com/chopratejas.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n# Headroom\n\n**Compress everything your AI agent reads. Same answers, fraction of the tokens.**\n\n[![CI](https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg)](https://github.com/chopratejas/headroom/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/headroom-ai.svg)](https://pypi.org/project/headroom-ai/)\n[![npm](https://img.shields.io/npm/v/headroom-ai.svg)](https://www.npmjs.com/package/headroom-ai)\n[![Model: Kompress-base](https://img.shields.io/badge/model-Kompress--base-yellow.svg)](https://huggingface.co/chopratejas/kompress-base)\n[![Tokens saved: 60B+](https://img.shields.io/badge/tokens%20saved-60B%2B-2ea44f)](https://headroomlabs.ai/dashboard)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://chopratejas.github.io/headroom/)\n\n\u003cimg src=\"HeadroomDemo-Fast.gif\" alt=\"Headroom in action\" width=\"820\"\u003e\n\n\u003c/div\u003e\n\n---\n\nEvery tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — **losslessly, locally, and without touching accuracy.**\n\n\u003e **100 logs. One FATAL error buried at position 67. Both runs found it.**\n\u003e Baseline **10,144 tokens** → Headroom **1,260 tokens** — **87% fewer, identical answer.**\n\u003e `python examples/needle_in_haystack_test.py`\n\n---\n\n## Quick start\n\nWorks with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.\n\n**Wrap your coding agent — one command:**\n\n```bash\npip install \"headroom-ai[all]\"\n\nheadroom wrap claude      # Claude Code\nheadroom wrap codex       # Codex\nheadroom wrap cursor      # Cursor\nheadroom wrap aider       # Aider\nheadroom wrap copilot     # GitHub Copilot CLI\n```\n\n**Drop it into your own code — Python or TypeScript:**\n\n```python\nfrom headroom import compress\n\nresult = compress(messages, model=\"claude-sonnet-4-5\")\nresponse = client.messages.create(model=\"claude-sonnet-4-5\", messages=result.messages)\nprint(f\"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})\")\n```\n\n```typescript\nimport { compress } from 'headroom-ai';\nconst result = await compress(messages, { model: 'gpt-4o' });\n```\n\n**Or run it as a proxy — zero code changes, any language:**\n\n```bash\nheadroom proxy --port 8787\nANTHROPIC_BASE_URL=http://localhost:8787 your-app\nOPENAI_BASE_URL=http://localhost:8787/v1 your-app\n```\n\n---\n\n## Why Headroom\n\n- **Accuracy-preserving.** GSM8K **0.870 → 0.870** (±0.000). TruthfulQA **+0.030**. SQuAD v2 and BFCL both **97%** accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.\n- **Runs on your machine.** No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.\n- **[Kompress-base](https://huggingface.co/chopratejas/kompress-base) on HuggingFace.** Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with `pip install \"headroom-ai[ml]\"`.\n- **Cross-agent memory and learning.** Claude Code saves a fact, Codex reads it back. `headroom learn` mines failed sessions and writes corrections straight to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — reliability compounds over time.\n- **Reversible (CCR).** Compression is not deletion. The model can always call `headroom_retrieve` to pull the original bytes. Nothing is thrown away.\n\nBundles the [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — full [attribution below](#compared-to).\n\n---\n\n## How it fits\n\n```\n Your agent / app\n   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)\n        │   prompts · tool outputs · logs · RAG results · files\n        ▼\n    ┌────────────────────────────────────────────────────┐\n    │  Headroom   (runs locally — your data stays here)  │\n    │  ───────────────────────────────────────────────   │\n    │  CacheAligner  →  ContentRouter  →  CCR             │\n    │                    ├─ SmartCrusher   (JSON)         │\n    │                    ├─ CodeCompressor (AST)          │\n    │                    └─ Kompress-base  (text, HF)     │\n    │                                                     │\n    │  Cross-agent memory  ·  headroom learn  ·  MCP      │\n    └────────────────────────────────────────────────────┘\n        │   compressed prompt  +  retrieval tool\n        ▼\n LLM provider  (Anthropic · OpenAI · Bedrock · …)\n```\n\n→ [Architecture](https://chopratejas.github.io/headroom/docs/architecture) · [CCR reversible compression](https://chopratejas.github.io/headroom/docs/ccr) · [Kompress-base model card](https://huggingface.co/chopratejas/kompress-base)\n\n---\n\n## Proof\n\n**Savings on real agent workloads:**\n\n| Workload                      | Before | After  | Savings |\n|-------------------------------|-------:|-------:|--------:|\n| Code search (100 results)     | 17,765 |  1,408 | **92%** |\n| SRE incident debugging        | 65,694 |  5,118 | **92%** |\n| GitHub issue triage           | 54,174 | 14,761 | **73%** |\n| Codebase exploration          | 78,502 | 41,254 | **47%** |\n\n**Accuracy preserved on standard benchmarks:**\n\n| Benchmark  | Category | N   | Baseline | Headroom | Delta     |\n|------------|----------|----:|---------:|---------:|----------:|\n| GSM8K      | Math     | 100 |    0.870 |    0.870 | **±0.000**|\n| TruthfulQA | Factual  | 100 |    0.530 |    0.560 | **+0.030**|\n| SQuAD v2   | QA       | 100 |        — |  **97%** | 19% compression |\n| BFCL       | Tools    | 100 |        — |  **97%** | 32% compression |\n\nReproduce:\n\n```bash\npython -m headroom.evals suite --tier 1\n```\n\n**Community, live:**\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://headroomlabs.ai/dashboard\"\u003e\n    \u003cimg src=\"headroom-savings.png\" alt=\"60B+ tokens saved — community leaderboard\" width=\"820\"\u003e\n  \u003c/a\u003e\n  \u003cp\u003e\u003cb\u003e\u003ca href=\"https://headroomlabs.ai/dashboard\"\u003e60B+ tokens saved by the community in the last 20 days — live leaderboard →\u003c/a\u003e\u003c/b\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n→ [Full benchmarks \u0026 methodology](https://chopratejas.github.io/headroom/docs/benchmarks)\n\n---\n\n## Built for coding agents\n\n| Agent              | One-command wrap                   | Notes                                                            |\n|--------------------|------------------------------------|------------------------------------------------------------------|\n| **Claude Code**    | `headroom wrap claude`             | `--memory` for cross-agent memory, `--code-graph` for codebase intel |\n| **Codex**          | `headroom wrap codex --memory`     | Shares the same memory store as Claude                           |\n| **Cursor**         | `headroom wrap cursor`             | Prints Cursor config — paste once, done                          |\n| **Aider**          | `headroom wrap aider`              | Starts proxy, launches Aider                                     |\n| **Copilot CLI**    | `headroom wrap copilot`            | Starts proxy, launches Copilot                                   |\n| **OpenClaw**       | `headroom wrap openclaw`           | Installs Headroom as ContextEngine plugin                        |\n\nMCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"headroom_learn.gif\" alt=\"headroom learn in action\" width=\"720\"\u003e\n\u003c/div\u003e\n\n---\n\n## Integrations\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDrop Headroom into any stack\u003c/b\u003e\u003c/summary\u003e\n\n| Your setup              | Hook in with                                                     |\n|-------------------------|------------------------------------------------------------------|\n| Any Python app          | `compress(messages, model=…)`                                    |\n| Any TypeScript app      | `await compress(messages, { model })`                            |\n| Anthropic / OpenAI SDK  | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())`   |\n| Vercel AI SDK           | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |\n| LiteLLM                 | `litellm.callbacks = [HeadroomCallback()]`                       |\n| LangChain               | `HeadroomChatModel(your_llm)`                                    |\n| Agno                    | `HeadroomAgnoModel(your_model)`                                  |\n| Strands                 | [Strands guide](https://chopratejas.github.io/headroom/docs/strands) |\n| ASGI apps               | `app.add_middleware(CompressionMiddleware)`                      |\n| Multi-agent             | `SharedContext().put / .get`                                     |\n| MCP clients             | `headroom mcp install`                                           |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat's inside\u003c/b\u003e\u003c/summary\u003e\n\n- **SmartCrusher** — universal JSON: arrays of dicts, nested objects, mixed types.\n- **CodeCompressor** — AST-aware for Python, JS, Go, Rust, Java, C++.\n- **Kompress-base** — our HuggingFace model, trained on agentic traces.\n- **Image compression** — 40–90% reduction via trained ML router.\n- **CacheAligner** — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.\n- **IntelligentContext** — score-based context fitting with learned importance.\n- **CCR** — reversible compression; LLM retrieves originals on demand.\n- **Cross-agent memory** — shared store, agent provenance, auto-dedup.\n- **SharedContext** — compressed context passing across multi-agent workflows.\n- **`headroom learn`** — plugin-based failure mining for Claude, Codex, Gemini.\n\n\u003c/details\u003e\n\n---\n\n## Install\n\n```bash\npip install \"headroom-ai[all]\"          # Python, everything\nnpm  install headroom-ai                # TypeScript / Node\ndocker pull ghcr.io/chopratejas/headroom:latest\n```\n\nGranular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.\n\n→ [Installation guide](https://chopratejas.github.io/headroom/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.\n\n---\n\n## Documentation\n\n| Start here                                                              | Go deeper                                                              |\n|-------------------------------------------------------------------------|------------------------------------------------------------------------|\n| [Quickstart](https://chopratejas.github.io/headroom/docs/quickstart)    | [Architecture](https://chopratejas.github.io/headroom/docs/architecture) |\n| [Proxy](https://chopratejas.github.io/headroom/docs/proxy)              | [How compression works](https://chopratejas.github.io/headroom/docs/how-compression-works) |\n| [MCP tools](https://chopratejas.github.io/headroom/docs/mcp)            | [CCR — reversible compression](https://chopratejas.github.io/headroom/docs/ccr) |\n| [Memory](https://chopratejas.github.io/headroom/docs/memory)            | [Cache optimization](https://chopratejas.github.io/headroom/docs/cache-optimization) |\n| [Failure learning](https://chopratejas.github.io/headroom/docs/failure-learning) | [Benchmarks](https://chopratejas.github.io/headroom/docs/benchmarks) |\n| [Configuration](https://chopratejas.github.io/headroom/docs/configuration) | [Limitations](https://chopratejas.github.io/headroom/docs/limitations) |\n\n---\n\n## Compared to\n\nHeadroom runs **locally**, covers **every** content type (not just CLI or text), works with every major framework, and is **reversible**.\n\n|                                  | Scope                                           | Deploy                              | Local | Reversible |\n|----------------------------------|-------------------------------------------------|-------------------------------------|:-----:|:----------:|\n| **Headroom**                     | All context — tools, RAG, logs, files, history  | Proxy · library · middleware · MCP  |  Yes  |    Yes     |\n| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs                         | CLI wrapper                         |  Yes  |    No      |\n| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call         |  No   |    No      |\n| OpenAI Compaction                | Conversation history                            | Provider-native                     |  No   |    No      |\n\n\u003e **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/chopratejas/headroom.git \u0026\u0026 cd headroom\npip install -e \".[dev]\" \u0026\u0026 pytest\n```\n\nDevcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant \u0026 Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Community\n\n- **[Live leaderboard](https://headroomlabs.ai/dashboard)** — 60B+ tokens saved and counting.\n- **[Discord](https://discord.gg/yRmaUNpsPJ)** — questions, feedback, war stories.\n- **[Kompress-base on HuggingFace](https://huggingface.co/chopratejas/kompress-base)** — the model behind our text compression.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","funding_links":["https://github.com/sponsors/headroom-sdk"],"categories":["The latest additions 🎉","🌟 Community Projects","AI Back Ends"],"sub_categories":["🛠️ Developer Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchopratejas%2Fheadroom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchopratejas%2Fheadroom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchopratejas%2Fheadroom/lists"}