{"id":45653630,"url":"https://github.com/chopratejas/headroom","last_synced_at":"2026-05-14T01:04:40.113Z","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-05-09T00:35:32.000Z","size":48904,"stargazers_count":1697,"open_issues_count":97,"forks_count":151,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-05-09T00:36:21.114Z","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://headroom-docs.vercel.app/docs","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-05-09T00:18:47.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":130,"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":32910635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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-05-14T01:04:40.107Z","avatar_url":"https://github.com/chopratejas.png","language":"Python","funding_links":["https://github.com/sponsors/headroom-sdk"],"categories":["Python","AI \u0026 ML (20)","🛠️ Tools \u0026 Projects","The latest additions 🎉","🌟 Community Projects","agent","🧠 AI \u0026 LLM","未分类","AI Agent Frameworks \u0026 SDKs","MCP Servers","🤖 AI \u0026 Machine Learning","Knowledge \u0026 Memory","Coding-Assistant Token Savers","AI Back Ends","Open-Source LLM \u0026 Agent Projects","4. Agentic AI \u0026 Multi-Agent Systems","Design Primitives","MCP 服务器精选列表","*Ops for AI","🛠️ Tools \u0026 Utilities","Repos"],"sub_categories":["Memory \u0026 Compression","🛠️ Developer Tools","Multi-Agent Collaboration Systems","Other MCP Servers","Context Delivery \u0026 Compaction","🧠 知识、记忆与 RAG","LLMOps"],"readme":"```\n  ██╗  ██╗███████╗ █████╗ ██████╗ ██████╗  ██████╗  ██████╗ ███╗   ███╗\n  ██║  ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║\n  ███████║█████╗  ███████║██║  ██║██████╔╝██║   ██║██║   ██║██╔████╔██║\n  ██╔══██║██╔══╝  ██╔══██║██║  ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║\n  ██║  ██║███████╗██║  ██║██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║\n  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝\n                  The context compression layer for AI agents\n```\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003e60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/chopratejas/headroom/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/gh/chopratejas/headroom\"\u003e\u003cimg src=\"https://codecov.io/gh/chopratejas/headroom/graph/badge.svg\" alt=\"codecov\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/headroom-ai/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/headroom-ai.svg\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/headroom-ai\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/headroom-ai.svg\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://huggingface.co/chopratejas/kompress-base\"\u003e\u003cimg src=\"https://img.shields.io/badge/model-Kompress--base-yellow.svg\" alt=\"Model: Kompress-base\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://headroomlabs.ai/dashboard\"\u003e\u003cimg src=\"https://img.shields.io/badge/tokens%20saved-60B%2B-2ea44f\" alt=\"Tokens saved: 60B+\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License: Apache 2.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://headroom-docs.vercel.app/docs\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-online-blue.svg\" alt=\"Docs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://headroom-docs.vercel.app/docs\"\u003eDocs\u003c/a\u003e ·\n  \u003ca href=\"#get-started-60-seconds\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#proof\"\u003eProof\u003c/a\u003e ·\n  \u003ca href=\"#agent-compatibility-matrix\"\u003eAgents\u003c/a\u003e ·\n  \u003ca href=\"https://discord.gg/yRmaUNpsPJ\"\u003eDiscord\u003c/a\u003e ·\n  \u003ca href=\"llms.txt\"\u003ellms.txt\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\n  \u003cb\u003eAI agents / LLMs:\u003c/b\u003e read \u003ca href=\"llms.txt\"\u003e\u003ccode\u003e/llms.txt\u003c/code\u003e\u003c/a\u003e here, or fetch \u003ca href=\"https://headroom-docs.vercel.app/llms.txt\"\u003ethe live index\u003c/a\u003e / \u003ca href=\"https://headroom-docs.vercel.app/llms-full.txt\"\u003efull docs blob\u003c/a\u003e.\n\u003c/sub\u003e\u003c/p\u003e\n\n---\n\n\u003e Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"HeadroomDemo-Fast.gif\" alt=\"Headroom in action\" width=\"820\"\u003e\n  \u003cbr/\u003e\u003csub\u003eLive: 10,144 → 1,260 tokens — same FATAL found.\u003c/sub\u003e\n\u003c/p\u003e\n\n## What it does\n\n- **Library** — `compress(messages)` in Python or TypeScript, inline in any app\n- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language\n- **Agent wrap** — `headroom wrap claude|codex|cursor|aider|copilot` in one command\n- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client\n- **Cross-agent memory** — shared store across Claude, Codex, Gemini, auto-dedup\n- **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md`\n- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand\n\n## How it works (30 seconds)\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- **ContentRouter** — detects content type, selects the right compressor\n- **SmartCrusher / CodeCompressor / Kompress-base** — compress JSON, AST, or prose\n- **CacheAligner** — stabilizes prefixes so provider KV caches actually hit\n- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them\n\n→ [Architecture](https://headroom-docs.vercel.app/docs/architecture) · [CCR reversible compression](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-base model card](https://huggingface.co/chopratejas/kompress-base)\n\n## Get started (60 seconds)\n\n```bash\n# 1 — Install\npip install \"headroom-ai[all]\"          # Python\nnpm install headroom-ai                 # Node / TypeScript\n\n# 2 — Pick your mode\nheadroom wrap claude                    # wrap a coding agent\nheadroom proxy --port 8787              # drop-in proxy, zero code changes\n# or: from headroom import compress      # inline library\n\n# 3 — See the savings\nheadroom stats\n```\n\nGranular extras: `[proxy]`, `[mcp]`, `[ml]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.\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: `python -m headroom.evals suite --tier 1` · [Full benchmarks \u0026 methodology](https://headroom-docs.vercel.app/docs/benchmarks)\n\n\u003cp 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  \u003cbr/\u003e\u003cb\u003e\u003ca href=\"https://headroomlabs.ai/dashboard\"\u003e60B+ tokens saved by the community — live leaderboard →\u003c/a\u003e\u003c/b\u003e\n\u003c/p\u003e\n\n## Agent compatibility matrix\n\n| Agent       | `headroom wrap` | Notes                            |\n|-------------|:---------------:|----------------------------------|\n| Claude Code | ●               | `--memory` · `--code-graph`      |\n| Codex       | ●               | shares memory with Claude        |\n| Cursor      | ●               | prints config — paste once       |\n| Aider       | ●               | starts proxy + launches          |\n| Copilot CLI | ●               | starts proxy + launches          |\n| OpenClaw    | ●               | installs as ContextEngine plugin |\n\nAny OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.\n\n## When to use · When to skip\n\n**Great fit if you…**\n- run AI coding agents daily and want savings without changing your code\n- work across multiple agents and want shared memory\n- need reversible compression — originals always retrievable via CCR\n\n**Skip it if you…**\n- only use a single provider's native compaction and don't need cross-agent memory\n- work in a sandboxed environment where local processes can't run\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eIntegrations — drop 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://headroom-docs.vercel.app/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\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePipeline internals\u003c/b\u003e\u003c/summary\u003e\n\nHeadroom exposes one stable request lifecycle across `compress()`, the SDK, and the proxy:\n\n`Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received`\n\n- **Transforms** do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.\n- **Pipeline extensions** observe or customize lifecycle stages via `on_pipeline_event(...)`.\n- **Compression hooks** sit alongside the canonical lifecycle as an additional extension seam.\n- **Proxy extensions** remain the server/app integration seam for ASGI middleware, routes, and startup policy.\n\nProvider and tool-specific behavior lives under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.\n\n- **CLI/tool slices**: `headroom/providers/claude`, `copilot`, `codex`, `openclaw`\n- **Provider runtime slices**: `headroom/providers/claude`, `gemini`, plus shared backend/runtime dispatch in `headroom/providers/registry.py`\n- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli/proxy.py`, and `proxy/server.py` delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.\n\n\u003c/details\u003e\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\nUsing `pipx`? Choose a supported interpreter explicitly:\n\n```bash\npipx install --python python3.13 \"headroom-ai[all]\"\n```\n\n→ [Installation guide](https://headroom-docs.vercel.app/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.\n\n## headroom learn\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"headroom_learn.gif\" alt=\"headroom learn in action\" width=\"720\"\u003e\n\u003c/p\u003e\n\n`headroom learn` — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`.\n\n## Documentation\n\n| Start here                                                                    | Go deeper                                                                          |\n|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------|\n| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart)                | [Architecture](https://headroom-docs.vercel.app/docs/architecture)                 |\n| [Proxy](https://headroom-docs.vercel.app/docs/proxy)                          | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |\n| [MCP tools](https://headroom-docs.vercel.app/docs/mcp)                        | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr)          |\n| [Memory](https://headroom-docs.vercel.app/docs/memory)                        | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization)     |\n| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning)    | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks)                    |\n| [Configuration](https://headroom-docs.vercel.app/docs/configuration)          | [Limitations](https://headroom-docs.vercel.app/docs/limitations)                  |\n\n## Compared to\n\nHeadroom runs **locally**, covers **every** content type, 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| [lean-ctx](https://github.com/yvgude/lean-ctx)                               | CLI commands, MCP tools, editor rules          | CLI wrapper · MCP                  | 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 --short`, scoped `ls`, summarized installers. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.\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## 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","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"}