[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74213":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":23,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":40,"readmeContent":41,"aiSummary":42,"trendingCount":16,"starSnapshotCount":16,"syncStatus":43,"lastSyncTime":44,"discoverSource":45},74213,"headroom","chopratejas\u002Fheadroom","chopratejas","Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server.","https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs",null,"Python",14352,912,56,98,0,690,1027,98.88,"Apache License 2.0",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization","2026-06-06 04:05:57","```\n  ██╗  ██╗███████╗ █████╗ ██████╗ ██████╗  ██████╗  ██████╗ ███╗   ███╗\n  ██║  ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║\n  ███████║█████╗  ███████║██║  ██║██████╔╝██║   ██║██║   ██║██╔████╔██║\n  ██╔══██║██╔══╝  ██╔══██║██║  ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║\n  ██║  ██║███████╗██║  ██║██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║\n  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝\n                  The context compression layer for AI agents\n```\n\n\u003Cp align=\"center\">\u003Cstrong>60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible\u003C\u002Fstrong>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fapp.codecov.io\u002Fgh\u002Fchopratejas\u002Fheadroom\">\u003Cimg src=\"https:\u002F\u002Fcodecov.io\u002Fgh\u002Fchopratejas\u002Fheadroom\u002Fgraph\u002Fbadge.svg\" alt=\"codecov\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fheadroom-ai\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fheadroom-ai.svg\" alt=\"PyPI\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fheadroom-ai\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fheadroom-ai.svg\" alt=\"npm\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fchopratejas\u002Fkompress-base\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fmodel-Kompress--base-yellow.svg\" alt=\"Model: Kompress-base\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fheadroomlabs.ai\u002Fdashboard\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftokens%20saved-60B%2B-2ea44f\" alt=\"Tokens saved: 60B+\">\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg\" alt=\"License: Apache 2.0\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-online-blue.svg\" alt=\"Docs\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\">Docs\u003C\u002Fa> ·\n  \u003Ca href=\"#get-started-60-seconds\">Install\u003C\u002Fa> ·\n  \u003Ca href=\"#proof\">Proof\u003C\u002Fa> ·\n  \u003Ca href=\"#agent-compatibility-matrix\">Agents\u003C\u002Fa> ·\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ\">Discord\u003C\u002Fa> ·\n  \u003Ca href=\"llms.txt\">llms.txt\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Csub>\n  \u003Cb>AI agents \u002F LLMs:\u003C\u002Fb> read \u003Ca href=\"llms.txt\">\u003Ccode>\u002Fllms.txt\u003C\u002Fcode>\u003C\u002Fa> here, or fetch \u003Ca href=\"https:\u002F\u002Fheadroom-docs.vercel.app\u002Fllms.txt\">the live index\u003C\u002Fa> \u002F \u003Ca href=\"https:\u002F\u002Fheadroom-docs.vercel.app\u002Fllms-full.txt\">full docs blob\u003C\u002Fa>.\n\u003C\u002Fsub>\u003C\u002Fp>\n\n---\n\n> 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\">\n  \u003Cimg src=\"HeadroomDemo-Fast.gif\" alt=\"Headroom in action\" width=\"820\">\n  \u003Cbr\u002F>\u003Csub>Live: 10,144 → 1,260 tokens — same FATAL found.\u003C\u002Fsub>\n\u003C\u002Fp>\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` \u002F `AGENTS.md`\n- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand\n\n## How it works (30 seconds)\n\n```\n Your agent \u002F 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 \u002F CodeCompressor \u002F 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:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Farchitecture) · [CCR reversible compression](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fccr) · [Kompress-base model card](https:\u002F\u002Fhuggingface.co\u002Fchopratejas\u002Fkompress-base)\n\n## Get started (60 seconds)\n\n```bash\n# 1 — Install\npip install \"headroom-ai[all]\"          # Python\nnpm install headroom-ai                 # Node \u002F 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 & methodology](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fbenchmarks)\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fheadroomlabs.ai\u002Fdashboard\">\n    \u003Cimg src=\"headroom-savings.png\" alt=\"60B+ tokens saved — community leaderboard\" width=\"820\">\n  \u003C\u002Fa>\n  \u003Cbr\u002F>\u003Cb>\u003Ca href=\"https:\u002F\u002Fheadroomlabs.ai\u002Fdashboard\">60B+ tokens saved by the community — live leaderboard →\u003C\u002Fa>\u003C\u002Fb>\n\u003C\u002Fp>\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>\n\u003Csummary>\u003Cb>Integrations — drop Headroom into any stack\u003C\u002Fb>\u003C\u002Fsummary>\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 \u002F 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:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fstrands)  |\n| ASGI apps              | `app.add_middleware(CompressionMiddleware)`                      |\n| Multi-agent            | `SharedContext().put \u002F .get`                                     |\n| MCP clients            | `headroom mcp install`                                           |\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What's inside\u003C\u002Fb>\u003C\u002Fsummary>\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\u002FOpenAI 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\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Pipeline internals\u003C\u002Fb>\u003C\u002Fsummary>\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 \u002F 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\u002Fapp integration seam for ASGI middleware, routes, and startup policy.\n\nProvider and tool-specific behavior lives under `headroom\u002Fproviders\u002F` so core orchestration stays focused on lifecycle, sequencing, and policy.\n\n- **CLI\u002Ftool slices**: `headroom\u002Fproviders\u002Fclaude`, `copilot`, `codex`, `openclaw`\n- **Provider runtime slices**: `headroom\u002Fproviders\u002Fclaude`, `gemini`, plus shared backend\u002Fruntime dispatch in `headroom\u002Fproviders\u002Fregistry.py`\n- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli\u002Fproxy.py`, and `proxy\u002Fserver.py` delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.\n\n\u003C\u002Fdetails>\n\n## Install\n\n```bash\npip install \"headroom-ai[all]\"          # Python, everything\nnpm install headroom-ai                 # TypeScript \u002F Node\ndocker pull ghcr.io\u002Fchopratejas\u002Fheadroom: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:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Finstallation) — Docker tags, persistent service, PowerShell, devcontainers.\n\n## headroom learn\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"headroom_learn.gif\" alt=\"headroom learn in action\" width=\"720\">\n\u003C\u002Fp>\n\n`headroom learn` — mines failed sessions, writes corrections to `CLAUDE.md` \u002F `AGENTS.md` \u002F `GEMINI.md`.\n\n## Documentation\n\n| Start here                                                                    | Go deeper                                                                          |\n|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------|\n| [Quickstart](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fquickstart)                | [Architecture](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Farchitecture)                 |\n| [Proxy](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fproxy)                          | [How compression works](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fhow-compression-works) |\n| [MCP tools](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fmcp)                        | [CCR — reversible compression](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fccr)          |\n| [Memory](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fmemory)                        | [Cache optimization](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fcache-optimization)     |\n| [Failure learning](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Ffailure-learning)    | [Benchmarks](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fbenchmarks)                    |\n| [Configuration](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Fconfiguration)          | [Limitations](https:\u002F\u002Fheadroom-docs.vercel.app\u002Fdocs\u002Flimitations)                  |\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:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk)                                        | CLI command outputs                            | CLI wrapper                        | Yes   | No         |\n| [lean-ctx](https:\u002F\u002Fgithub.com\u002Fyvgude\u002Flean-ctx)                               | CLI commands, MCP tools, editor rules          | CLI wrapper · MCP                  | Yes   | No         |\n| [Compresr](https:\u002F\u002Fcompresr.ai), [Token Co.](https:\u002F\u002Fthetokencompany.ai)    | Text sent to their API                         | Hosted API call                    | No    | No         |\n| OpenAI Compaction                                                            | Conversation history                           | Provider-native                    | No    | No         |\n\n> **Attribution.** Headroom ships with the excellent [RTK](https:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk) 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:\u002F\u002Fgithub.com\u002Fyvgude\u002Flean-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:\u002F\u002Fgithub.com\u002Fchopratejas\u002Fheadroom.git && cd headroom\npip install -e \".[dev]\" && pytest\n```\n\nDevcontainers in `.devcontainer\u002F` (default + `memory-stack` with Qdrant & Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Community\n\n- **[Live leaderboard](https:\u002F\u002Fheadroomlabs.ai\u002Fdashboard)** — 60B+ tokens saved and counting.\n- **[Discord](https:\u002F\u002Fdiscord.gg\u002FyRmaUNpsPJ)** — questions, feedback, war stories.\n- **[Kompress-base on HuggingFace](https:\u002F\u002Fhuggingface.co\u002Fchopratejas\u002Fkompress-base)** — the model behind our text compression.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","Headroom 是一个专为大型语言模型（LLM）应用设计的上下文优化层。它通过压缩AI代理读取的所有内容，如工具输出、日志、检索增强生成（RAG）片段、文件和对话历史记录，在保持相同答案质量的同时显著减少了所需的令牌数量。项目支持多种算法，具备本地优先且可逆的特点，并提供库、代理及代理包装器等多种使用方式，适用于需要高效处理大量文本数据以降低成本或提高性能的各种AI应用场景。",2,"2026-06-06 03:50:39","high_star"]