{"full_name":"chopratejas/headroom","owner":"chopratejas","name":"headroom","shard":"1","url":"https://github.com/chopratejas/headroom","description":"Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.","homepage":"https://docs.headroomlabs.ai/docs","topics":["agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization"],"tag_pages":["agent","ai","anthropic","compression","context-engineering","context-window","fastapi","langchain","llm","mcp","openai","proxy","python","rag","token-optimization"],"language":"Python","license":"Apache-2.0","avatar":"https://avatars.githubusercontent.com/u/294291659?v=4","created_at":"2026-01-07T19:58:51Z","pushed_at":"2026-11-15T15:29:28Z","metrics":{"stars":79731,"forks":6243,"watchers":213,"issues":1364,"prs":3372,"releases":178,"issues_open":130,"issues_closed":1234,"prs_open":182,"prs_closed":642,"prs_merged":2548,"discussions":92},"growth":{"day":{"stars":71,"forks":7,"base_day":"2026-11-15"},"week":{"stars":1005,"forks":91,"base_day":"2026-11-04"},"month":{"stars":4599,"forks":416,"base_day":"2026-10-17"}},"history":{"dates":["2026-09-06","2026-09-07","2026-09-08","2026-09-09","2026-09-10","2026-09-11","2026-09-12","2026-09-13","2026-09-14","2026-09-15","2026-09-16","2026-09-17","2026-09-18","2026-09-19","2026-09-20","2026-09-21","2026-09-22","2026-09-23","2026-09-24","2026-09-25","2026-09-26","2026-09-27","2026-09-28","2026-09-29","2026-09-30","2026-10-01","2026-10-02","2026-10-03","2026-10-04","2026-10-05","2026-10-06","2026-10-07","2026-10-08","2026-10-09","2026-10-10","2026-10-11","2026-10-12","2026-10-13","2026-10-14","2026-10-15","2026-10-16","2026-10-17","2026-10-18","2026-10-19","2026-10-20","2026-10-21","2026-10-22","2026-10-23","2026-10-24","2026-10-25","2026-10-26","2026-10-27","2026-10-28","2026-10-29","2026-10-30","2026-10-31","2026-11-01","2026-11-02","2026-11-03","2026-11-04","2026-11-10","2026-11-11","2026-11-12","2026-11-13","2026-11-14","2026-11-15","2026-11-16"],"stars":[67398,67560,67686,67810,67864,67913,67995,68307,68541,68793,68924,69020,69729,70708,71043,71330,71574,71724,72097,72315,72466,72726,72926,73075,73389,73504,73633,73707,73802,73871,74020,74090,74233,74285,74339,74455,74515,74578,74737,74823,74899,75132,75201,75351,75426,75514,75577,76143,76651,77153,77538,77634,77715,77911,78018,78139,78255,78365,78655,78726,79281,79354,79439,79473,79582,79660,79731],"forks":[5193,5206,5223,5238,5244,5255,5264,5296,5310,5331,5341,5354,5386,5426,5445,5466,5482,5497,5522,5537,5562,5589,5608,5616,5652,5669,5682,5689,5693,5701,5719,5723,5742,5740,5750,5763,5765,5774,5786,5801,5809,5827,5836,5847,5855,5865,5867,5919,5952,5985,6020,6027,6037,6059,6070,6085,6097,6108,6141,6152,6198,6208,6214,6219,6228,6236,6243],"watchers":[194,196,197,197,200,200,201,208,209,210,209,210,210,212,210,210,211,212,213,215,214,215,216,216,217,217,218,218,218,218,217,219,218,218,218,218,218,218,217,217,217,220,219,220,221,221,221,223,226,226,225,224,218,217,217,216,214,214,213,213,null,212,213,213,213,212,213],"issues_open":[null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,127,131,131,128,130,130],"prs_open":[null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,148,160,168,172,181,182]},"boards":{"monthly":126},"same_owner":[],"issues":[{"number":4613,"title":"[BUG] Proxy leaks compression-executor threads (image OCR?), pinning cores.","comments":6,"created_at":"2026-11-02T09:50:57Z"},{"number":4433,"title":"[BUG] security-model.mdx says an unsafe x-headroom-base-url override is \"ignored\", but the proxy routes answer 400","comments":6,"created_at":"2026-10-22T17:32:47Z"},{"number":3563,"title":"[BUG] CCR recovery JSON re-offloaded through Codex functions.exec wrapper; named retrieval exemption passes","comments":6,"created_at":"2026-09-12T00:44:31Z"},{"number":3187,"title":"[FEATURE] please add wrap support for prime-agent","comments":6,"created_at":"2026-08-21T20:31:56Z"},{"number":2649,"title":"[FEATURE] Pre-upstream context limit guard — hard-cap input tokens to avoid upstream 400 + client retry storm","comments":6,"created_at":"2026-07-29T11:39:35Z"},{"number":748,"title":"[FEATURE] One consolidated `headroom uninstall` command + document teardown in --help and README","comments":6,"created_at":"2026-06-08T15:42:06Z"},{"number":709,"title":"[BUG] Proactive context expansion injects stale CCR contexts in fast agentic sessions","comments":6,"created_at":"2026-06-06T17:21:32Z"},{"number":975,"title":"[FEATURE] headroom wrap support for Kilo Code (VS Code, CLI, Cloud)","comments":5,"created_at":"2026-06-14T12:15:20Z"}],"discussions":[{"number":4676,"title":"RFC: one label set for request attribution (project, client, host, …) instead of one axis per dimension","comments":0,"category":"Ideas","created_at":"2026-11-07T04:33:35Z"},{"number":4668,"title":"Headroom as a baseline in a study on learned field projections for agent tool outputs","comments":0,"category":"Show and tell","created_at":"2026-11-06T08:49:12Z"},{"number":4612,"title":"Measured byte-level savings on Windows: tool output -71.1%, path list -92.0%, build log +0.7%","comments":0,"category":"Show and tell","created_at":"2026-11-02T08:56:52Z"},{"number":4483,"title":"Headroom with rtk 1.0","comments":0,"category":"General","created_at":"2026-10-25T09:43:19Z"},{"number":4439,"title":"Question about MCP-only mode in Codex Desktop: Who evaluates the need for compression and on what basis?","comments":1,"category":"Q&A","created_at":"2026-10-23T06:24:50Z"},{"number":4312,"title":"Any plan to add support for Mimocode Desktop for Windows?","comments":0,"category":"Ideas","created_at":"2026-10-20T13:32:39Z"},{"number":3961,"title":"OpusBar: a macOS menu bar app for Claude Code and Codex usage, limits and waiting sessions","comments":0,"category":"Show and tell","created_at":"2026-10-04T15:45:48Z"},{"number":3922,"title":"README idea: HVTrust badge linking to Headroom's independent trust profile","comments":0,"category":"Ideas","created_at":"2026-10-02T10:59:30Z"}],"latest_release":{"name":"Release v0.44.0","tag":"v0.44.0","published_at":"2026-11-10T01:58:31Z","body":"## [0.44.0](https://github.com/headroomlabs-ai/headroom/compare/v0.43.1...v0.44.0) (2026-11-09)\n\n\n### ⚠ BREAKING CHANGES\n\n* **packaging:** keep PyTorch extras out of all ([#4067](https://github.com/headroomlabs-ai/headroom/issues/4067))\n\n### Features\n\n* **pipeline:** say whose request an OutcomeSnapshot is ([#4698](https://github.com/headroomlabs-ai/headroom/issues/4698)) ([a2bcbd1](https://github.com/headroomlabs-ai/headroom/commit/a2bcbd101b1391debfd218ec8c63cb72d2bc240a))\n* **providers:** add Hermes agent wrap support ([#934](https://github.com/headroomlabs-ai/headroom/issues/934)) ([7877241](https://github.com/headroomlabs-ai/headroom/commit/7877241d84c93b3ec487e07324245838ddae85cc))\n* **proxy/model-router:** add shadow mode (HEADROOM_MODEL_ROUTER_LOG_ONLY) ([#2395](https://github.com/headroomlabs-ai/headroom/issues/2395)) ([861ef95](https://github.com/headroomlabs-ai/headroom/commit/861ef95620c801c2560a2eacc5773a26e131dfd0))\n* **proxy:** add lossless /v1/compress mode and detect provider by wire shape ([#4617](https://github.com/headroomlabs-ai/headroom/issues/4617)) ([33f067a](https://github.com/headroomlabs-ai/headroom/commit/33f067a243b2e648730c01ae6b9f20cba879f351))\n* **proxy:** expose per-request cost_usd in /stats recent_requests ([#1079](https://github.com/headroomlabs-ai/headroom/issues/1079)) ([#1565](https://github.com/headroomlabs-ai/headroom/issues/1565)) ([84cedbf](https://github.com/headroomlabs-ai/headroom/commit/84cedbf2b4197f09ace9944c50655786dac35b03))\n* **proxy:** expose shared Redis store availability in /health and /metrics ([#4578](https://github.com/headroomlabs-ai/headroom/issues/4578)) ([602ca65](https://github.com/headroomlabs-ai/headroom/commit/602ca65126e12d73ef44d4b1b01bbe1fa3b37080))\n* **proxy:** give turn hooks one conversation id per client conversation ([#4496](https://github.com/headroomlabs-ai/headroom/issues/4496)) ([94a99ed](https://github.com/headroomlabs-ai/headroom/commit/94a99ed20f6fe110e03d2613e9feec42d9547150))\n* **proxy:** report DeepSeek as its own provider in dashboard ([#2565](https://github.com/headroomlabs-ai/headroom/issues/2565)) ([9ad16a7](https://github.com/headroomlabs-ai/headroom/commit/9ad16a77f8b9a7817331aa5e9a9ee04d1e1fc05e))\n* **proxy:** show per-request /stats metadata to token-authenticated callers ([#4168](https://github.com/headroomlabs-ai/headroom/issues/4168)) ([9b2dec5](https://github.com/headroomlabs-ai/headroom/commit/9b2dec56f9882a25fb511dc5f480b047845141f9))\n* **proxy:** unified multi-upstream routing for Anthropic Cloud and local oMLX ([#4597](https://github.com/headroomlabs-ai/headroom/issues/4597)) ([f896161](https://github.com/headroomlabs-ai/headroom/commit/f896161340893dd8e96502d4c309980bed52d3d1))\n* **savings:** carry cumulative actual output_tokens in history checkpoints ([#2921](https://github.com/headroomlabs-ai/headroom/issues/2921)) ([8388ff5](https://github.com/headroomlabs-ai/headroom/commit/8388ff5efd7caf3a827e66bf69449c4a64df05af))\n* **wrap:** add `headroom wrap droid` for Factory Droid ([#4143](https://github.com/headroomlabs-ai/headroom/issues/4143)) ([bb8d18a](https://github.com/headroomlabs-ai/headroom/commit/bb8d18a56abb07ca7e811235c86ea6b626eb1f8b))\n* **wrap:** make the Serena code-memory MCP opt-in ([#4509](https://github.com/headroomlabs-ai/headroom/issues/4509)) ([2649835](https://github.com/headroomlabs-ai/headroom/commit/2649835a51e6d459ac47e8dcb8591e5bf027715b))\n\n\n### Bug Fixes\n\n* **asgi:** stop buffering when the client disconnects (GHSA-mc2f-vg4v-2fh4) ([#4701](https://github.com/headroomlabs-ai/headroom/issues/4701)) ([c6d7081](https://github.com/headroomlabs-ai/headroom/commit/c6d708144ce27abeb08c4c57374b373eebe1951e))\n* **beacon:** enforce the allowlist below the top-level keys ([#4691](https://github.com/headroomlabs-ai/headroom/issues/4691)) ([456288d](https://github.com/headroomlabs-ai/headroom/commit/456288da0765985ca31eed58dbdaef44ff9aa43a))\n* **binaries:** fail closed on HEADROOM_BINARIES_ALLOW_UNVERIFIED=0/false (","is_prerelease":false},"readme":true,"readme_zh":false,"news":[{"title":"Compress tool outputs, logs, files, RAG chunks before LLM for 60-95% less tokens","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=48606411","source":"Hacker News","lang":"en","date":"2026-06-20","points":4,"comments":0},{"title":"A Compression Tool for LLM Reads. Est. 60-95% Fewer Tokens","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=48155888","source":"Hacker News","lang":"en","date":"2026-05-16","points":4,"comments":0},{"title":"Headroom – LLM Input Compression","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=48346909","source":"Hacker News","lang":"en","date":"2026-05-31","points":3,"comments":0},{"title":"Show HN: Headroom (OSS): Cuts LLM costs by 85%","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=46663757","source":"Hacker News","lang":"en","date":"2026-01-18","points":3,"comments":5},{"title":"TokenMinMaxing","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=48583281","source":"Hacker News","lang":"en","date":"2026-06-18","points":2,"comments":0},{"title":"Headroom","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=48565177","source":"Hacker News","lang":"en","date":"2026-06-17","points":2,"comments":0},{"title":"Headroom – context optimization layer for tool-using agents","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=46602761","source":"Hacker News","lang":"en","date":"2026-01-13","points":2,"comments":2},{"title":"Show HN: Headroom – Reversible context compression for LLMs(~60% cost reduction)","url":"https://github.com/chopratejas/headroom","hn":"https://news.ycombinator.com/item?id=46628278","source":"Hacker News","lang":"en","date":"2026-01-15","points":1,"comments":1},{"title":"[20261019] LLM News & FP8 KV Cache for Increasing Inference Headroom","url":"https://note.com/jazzy_briony8396/n/n7fe650352f0d?hl=en","source":"note","lang":"en","date":"2026-10-19"},{"title":"GitHub 狂攬 4 萬星！Headroom 開源工具幫開發者省下 70 萬美元 API 費，Token 消耗暴降 92%","url":"https://www.techbang.com/posts/130440-netflix-engineer-headroom-ai-token-savings","source":"T客邦","lang":"zh","date":"2026-08-01"},{"title":"Headroom: The Context Compression Layer Your AI Agent Desperately Needs","url":"https://www.alphamatch.ai/blog/headroom-context-compression-ai-agents-2026","source":"alphamatch.ai","lang":"en","date":"2026-06-11"},{"title":"[GitHub Trend Summary] markitdown surges, Hermes Agent makes strides, and LLM compression tool headroom gains attention - 1st week of June 2026","url":"https://note.com/shali_note/n/n10ee18d10021?hl=en","source":"note","lang":"en","date":"2026-06-06"},{"title":"A Netflix Engineer Built a Free Tool That Cuts Your AI Token Bill by 88%","url":"https://news.google.com/rss/articles/CBMiowFBVV95cUxPLUI1THdMMUQ3NjVXS092Y3l3UVBvQzBXUTlJWmhSZDBvTGFkRWNVelJYeGp5ellNSk14aGhfaVUtb1c0elp4WWtsZ3VBMVYyV0RsX2pTQzcwcHo5Qmh3SVNqNGpZcnRCTHBHckxiVkZ0Ui1HME1sUDhEcUl4Rm1lREVNYmgxMlBNWHVvd0ZWdmtzWnVZNHhCSzdDaFptRUdVU3o0?oc=5","source":"HackerNoon","lang":"en","date":"2026-08-05"},{"title":"从一张 287 美元账单到 4.4 万 star 的开源传奇：Netflix 工程师如何用 Headroom 为 AI Agent “瘦身” 90% 的 Token","url":"https://news.google.com/rss/articles/CBMiS0FVX3lxTE9CdDVVTW84Zkw4YmVucnY3ZHlLcVJkUENSTnNjMHhPMklNZ1ZMaE14dDRLamxSWjlmbE13VmsyMU9VZXcwLU8yRjUwMA?oc=5","source":"OSCHINA","lang":"zh","date":"2026-06-23"},{"title":"Headroom开源工具：最高节省92%Token成本，为AI编程降本增效","url":"https://news.google.com/rss/articles/CBMia0FVX3lxTE01X1ZnZTB6VE1oWmxNM2xtUFloa1FXemxYcUVhT3BDOXlHU2dnSE5UaXhtdmstc1RXT2pQbUhadDhRSEdCREdscm53R3ZLXzhGWVAwLVJ4SDJoM2hnM0lkZlpvN0ROakJrNFp3?oc=5","source":"CSDN博客","lang":"zh","date":"2026-06-23"},{"title":"Headroom vs Caveman: Compress Input or Cut Output","url":"https://news.google.com/rss/articles/CBMikgFBVV95cUxPSkVOakFYWnJQMjBPWngybnNZZWN4YkFwZDU5NjV4YUdsX3BIckQxQldBUTN5M0hOMFRjdnN0Q0E3UHFRVVNuclpXMUNuZkxMYzJCSVRaai1URmQ0aXJTNS13U3JmMHFaOTZDUUVSMjI2RXRwdnh0V25RREJKTTNzdWNLcExadGtGOUJFdl83N21EZw?oc=5","source":"Pasquale Pillitteri","lang":"en","date":"2026-06-20"},{"title":"Headroom Cuts AI Tokens up to 95% on JSON: the Tool Born at Netflix","url":"https://news.google.com/rss/articles/CBMiiAFBVV95cUxON2tQTFZHTVp0VWkxa3h4c2ZmQ3BtYUtnbXB3NnBlUGlOMlo3SXgtbm5pdGR0cDJDTTE2U3JTeTJnU1d4bE5FZzcxbE9pU2Z0bjByX1hwbFNxVW51X3dHV1FqSW1ZbTVjU214dVlpMHJWb2lDQnJ1X2IyX0VhSW4zakVveUpLM2lY?oc=5","source":"Pasquale Pillitteri","lang":"en","date":"2026-06-20"},{"title":"Headroom 在 JSON 上将 AI token 削减最多 95%：诞生于 Netflix 的工具","url":"https://news.google.com/rss/articles/CBMihAFBVV95cUxQaVJVU2gweGoxRHhtTlRUQzNMeGUtbEVFU21MX3FPVi1fU1RUVDJHeGUxbkJZVFpTOHpiT1BOaFJ5YkNlcEU4a1k0UFA0RnVUM1V6V1g3cWJQNUd1SlRQVmhQV0QwX2FneEs0M1o1UnNmWmFyRmVrZGdGN2dOanUzU1ZSZlg?oc=5","source":"Pasquale Pillitteri","lang":"zh","date":"2026-06-20"},{"title":"砍掉 90% 冗余词元，省下 70 万美元：Netflix 开源工具狙击 AI 账单黑洞","url":"https://news.google.com/rss/articles/CBMiXkFVX3lxTE9TelV5dXppQXh5SHc4NG9laDRTaGhzM1JzSWZjY2E2c1J2a3VIYjliQ295emtHcXpycG1FVzE1WExsa01KbWk5NjRwaHA4V3RRdTBVYThkNEVhWUswN3c?oc=5","source":"InfoQ.cn","lang":"zh","date":"2026-06-18"},{"title":"狂揽22.2k star！AI智能体上下文压缩工具开源，Token成本直降95%准确率不变","url":"https://news.google.com/rss/articles/CBMiV0FVX3lxTE12VnpYaHJGdHFrMHhrWVFJREFITkFNcmc4R0tqY1l6S1lNS3JycDJfY3dpRDRXV2ZDbElUWmpNMlZqT0RQc1F3NklRTndKWlEtTy1RRmx2cw?oc=5","source":"view.inews.qq.com","lang":"zh","date":"2026-06-12"},{"title":"Netflix wiz creates app to slash AI bills, then open sources it","url":"https://news.google.com/rss/articles/CBMitgFBVV95cUxPYUltNGNvOXhPcnE4VzkxbUJTT0gtNHhnMFZZVWtwWVQycmZqU0xNeVBCUTNqbFgxb1dLTmY0WHBsZDF4T1hhQ0lENWZ6SHg1bU9wZGFTWkpRWDJ3dXR5TWtLZlh4eU4teFpQRVpZN0d6SFBGYWY2c3NWUXhyZldVV2EyLUdtYmJyRWJkV0V1dkpOOTR4b1hZM0tLSEN2UlFHY3U2Y01pZ2FDNkJJaEhlWUJoLTloZw?oc=5","source":"The Register","lang":"en","date":"2026-05-31"}],"stale":false,"snapshot_at":"2026-11-16T09:23:14Z","history_start":"2026-09-06"}