{"data":{"slug":"headroomlabs-ai-headroom","name":"headroom","tagline":"Compress tool outputs, logs, files, and RAG chunks before they reach the LLM.","github_url":"https://github.com/headroomlabs-ai/headroom","owner":"headroomlabs-ai","repo":"headroom","owner_avatar_url":"https://avatars.githubusercontent.com/u/294291659?v=4","primary_language":"Python","stars":72850,"forks":5600,"topics":["agent","ai","anthropic","claude-code","compression","context-engineering","context-window","cursor","fastapi","langchain","llm","mcp","openai","prompt-engineering","proxy","python","rag","token-optimization","tokens","typescript"],"archived":false,"github_pushed_at":"2026-09-17T23:57:28+00:00","maintenance_label":"Very active","stars_delta_30d":6380,"url":"https://www.graphcanon.com/tools/headroomlabs-ai-headroom","markdown_url":"https://www.graphcanon.com/tools/headroomlabs-ai-headroom.md","api_url":"https://www.graphcanon.com/api/graphcanon/tools/headroomlabs-ai-headroom","graph_url":"https://www.graphcanon.com/api/graphcanon/graph?tool=headroomlabs-ai-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_url":"https://docs.headroomlabs.ai/docs","license":"Apache-2.0","open_issues":671,"watchers":215,"ai_summary":"Headroom compresses data for LLMs, reducing token usage by 20% for coding agents and 60-95% for JSON, without altering answers. It offers a library, proxy, and MCP server.","readme_excerpt":"# 1 — Install\nuv tool install --python 3.13 \"headroom-ai[all]\"  # CLI in a self-contained env\npip install \"headroom-ai[all]\"                    # Python — ships the `headroom` CLI\nnpm install headroom-ai                           # TypeScript SDK only — no CLI\n\n---\n\n## Install\n\n```bash\nuv tool install --python 3.13 \"headroom-ai[all]\"  # CLI, isolated app env\npip install \"headroom-ai[all]\"                    # Python, everything — includes the CLI\nnpm install headroom-ai                           # TypeScript SDK (library only)\ndocker pull ghcr.io/headroomlabs-ai/headroom:latest\n```\n\nGranular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`,\n`[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in\n`[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`,\n`[pytorch-mps]` (Apple-GPU memory-embedder offload — set\n`HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.10+**.\n\n> `[all]` covers the core stack but not the framework adapters. Install those\n> separately: `pip install \"headroom-ai[langchain]\"`, and likewise `[agno]`,\n> `[strands]`, `[anyllm]`, `[bedrock]`.\n\n→ [Installation guide](https://docs.headroomlabs.ai/docs/installation) — Docker\ntags, persistent service, PowerShell, devcontainers.\n\n<details>\n<summary><b>uv, pipx, and MCP clients that don't inherit your PATH</b></summary>\n\nPrefer `uv tool install` for the CLI so the command lives in an isolated app\nenvironment. On macOS, pass `--python 3.13` if your default `python3` is newer\nthan the current wheel set:\n\n```bash\nbrew install python@3.13  # if 3.13 is not already available\nuv tool install --python 3.13 \"headroom-ai[all]\"\nuv tool update-shell      # if ~/.local/bin is not on PATH\nheadroom --version\n```\n\nCodex and other MCP clients often cannot inherit an interactive shell `PATH`.\nConfigure the absolute path returned by `command -v headroom`:\n\n```toml\n[mcp_servers.headroom]\ncommand = \"/Users/you/.local/bin/headroom\"\nargs = [\"mcp\", \"serve\"]\n```\n\n`command = \"headroom\"` only works when the client starts with a `PATH` that\nalready includes the uv tool directory.\n\nWith pipx, choose the interpreter explicitly:\n\n```bash\npipx install --python python3.13 \"headroom-ai[all]\"\n```\n\nNative wheels currently cover macOS Apple Silicon and Linux. On Intel macOS, use\nthe Docker-native install until native wheel support lands.\n\n**CPU requirement (x86/x86_64).** The ONNX-backed features — Magika content\ndetection and embedding relevance — use a precompiled ONNX Runtime that needs\n**AVX2**. On x86 hosts without AVX2 (some Docker/QEMU setups, older cloud VMs)\nHeadroom falls back to its non-ONNX paths — BM25 relevance, heuristic detection —\nrather than crashing. `arm64` and Apple Silicon need no AVX2.\n\n</details>\n\n<details>\n<summary><b>Updating</b></summary>\n\n```bash\nheadroom update          # detects pip / pipx / uv tool and upgrades in place\nheadroom update --check  # report the latest release without upgrading\nheadroom update --pre    # include pre-releases\n```\n\n`headroom update` works out how Headroom was installed (pip/venv, `pip --user`,\npipx, uv tool) and runs the matching upgrade on macOS, Linux and Windows. For git\ncheckouts, editable installs, Docker images and externally-managed system Pythons\n(PEP 668) it prints the correct manual step instead of guessing.\n\nThe proxy also prints a one-line \"update available\" notice at startup. It checks\nPyPI at most once a day, in the background, and never blocks. Opt out with\n`HEADROOM_UPDATE_CHECK=off`; it is also skipped in `--stateless` mode and CI.\n\n</details>\n\n<details>\n<summary><b>Corporate networks and SSL inspection</b></summary>\n\nIf `pip install \"headroom-ai[all]\"` fails with `CERTIFICATE_VERIFY_FAILED`\n(`unable to get local issuer certificate`), your network runs SSL inspection — a\nMITM proxy presenting a company CA. The build backend (`maturin`) downloads\n`rustup` over a connection your TLS stack does not trust. Install Rust first so\nthe build never fetches it:\n\n```bash\n\n---\n\n##","github_created_at":"2026-01-07T19:58:51+00:00","created_at":"2026-07-07T17:31:04.553672+00:00","updated_at":"2026-09-20T04:32:09.819371+00:00","categories":[{"slug":"developer-tools","name":"Developer Tools","url":"https://www.graphcanon.com/categories/developer-tools","markdown_url":"https://www.graphcanon.com/categories/developer-tools.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/developer-tools"},{"slug":"evaluation-observability","name":"Evaluation & Observability","url":"https://www.graphcanon.com/categories/evaluation-observability","markdown_url":"https://www.graphcanon.com/categories/evaluation-observability.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/evaluation-observability"},{"slug":"inference-serving","name":"Inference & Serving","url":"https://www.graphcanon.com/categories/inference-serving","markdown_url":"https://www.graphcanon.com/categories/inference-serving.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/inference-serving"},{"slug":"model-training","name":"Model Training","url":"https://www.graphcanon.com/categories/model-training","markdown_url":"https://www.graphcanon.com/categories/model-training.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/model-training"}],"tags":[{"slug":"agent","name":"agent"},{"slug":"ai","name":"ai"},{"slug":"anthropic","name":"anthropic"},{"slug":"claude-code","name":"claude-code"},{"slug":"compression","name":"compression"},{"slug":"context-engineering","name":"context-engineering"},{"slug":"context-window","name":"context-window"},{"slug":"cursor","name":"cursor"}],"trust":{"provenance":{"is_fork":false,"github_id":1129940957,"owner_type":"Organization","methodology":"github_public_v1","parent_repo":null,"near_duplicate_slugs":[]},"computed_at":"2026-09-18T08:37:17.041Z","maintenance":{"label":"Very active","score":96,"methodology":"github_public_v1","releases_90d":16,"days_since_push":0,"last_release_at":"2026-08-27T21:18:26Z","stars_delta_30d":6380,"open_issues_delta_30d":183},"security_summary":{"status":"no_lockfile","scanner":null,"low_count":0,"high_count":0,"last_scan_at":"2026-09-20T04:00:40.129Z","medium_count":0,"scan_profile":"none","critical_count":0}},"capability_facts":{"mcp":{"source":"repo_scan","observed_at":"2026-09-18T08:37:15.916Z","server_manifest":false},"scan":{"source":"repo_scan","observed_at":"2026-09-18T08:37:15.916Z"},"deploy":{"source":"dockerfile:Dockerfile","self_host":true,"observed_at":"2026-09-18T08:37:15.916Z","managed_saas":false},"has_cli":{"value":true,"source":"pyproject.toml:[project.scripts]","observed_at":"2026-09-18T08:37:15.916Z"},"languages":{"value":["python"],"source":"github.language+pyproject.toml","observed_at":"2026-09-18T08:37:15.916Z"},"has_docker":{"value":true,"source":"dockerfile:Dockerfile","observed_at":"2026-09-18T08:37:15.916Z"},"license_spdx":{"value":"Apache-2.0","source":"github.license","observed_at":"2026-09-18T08:37:15.916Z"}},"decision_facts":{"hosting":null,"pricing":null,"requirements":{"notes":["Requires Python 3.10+.","ONNX-backed features require AVX2 on x86/x86_64 hosts."],"min_ram_gb":null,"requires_docker":true},"constraints":{"min_ram_gb":null,"requires_docker":true},"when_to_use":["When you need to reduce token usage for coding agents by 20% and for JSON by 60-95% without changing the answers.","If you are working with Python 3.10+ and require a tool that can compress tool outputs, logs, files, and RAG chunks before they reach the LLM.","When you need a tool that supports a variety of extras like proxy, MCP, and ML, and can be installed via pip, npm, or Docker."],"when_not_to_use":["If you are working with environments that do not support Python 3.10+.","When your project does not require token optimization or compression for JSON and coding agents.","If you are working on a platform that does not support the ONNX-backed features, such as some Docker/QEMU setups or older cloud VMs without AVX2."],"source":"enrich:decision_facts","observed_at":"2026-09-18T11:12:41.420Z"},"constraint_facets":{"min_ram_gb":null,"requires_docker":true},"decision_summary":[{"label":"Requirements","value":"Requires Docker; Requires Python 3.10+.; ONNX-backed features require AVX2 on x86/x86_64 hosts."},{"label":"Adopt for","value":"Headroom compresses data for LLMs, reducing token usage by 20% for coding agents and 60-95% for JSON, without altering answers. It offers a library, proxy, and MCP server."}]}}