{"data":{"slug":"headroomlabs-ai-headroom","name":"headroom","tagline":"Compress tool outputs and data to reduce tokens before reaching 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":66470,"forks":5103,"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-08-16T00:57:42+00:00","maintenance_label":"Very active","stars_delta_30d":6941,"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":488,"watchers":193,"ai_summary":"A library, proxy, and MCP server for compressing tool outputs, logs, files, and RAG chunks. Can result in 60-95% fewer tokens with unchanged answers.","readme_excerpt":"# 1 — Install\nuv tool install --python 3.13 \"headroom-ai[all]\"  # CLI as a global tool in a self-contained virtual env\npip install \"headroom-ai[all]\"                    # Python — ships the `headroom` CLI\nnpm install headroom-ai                           # TypeScript SDK only — no `headroom` CLI\n\n---\n\n# 2 — Pick your mode  (the `headroom` commands below come from the uv or pip install)\nheadroom deploy                         # turnkey local deployment + agent config\nheadroom wrap claude                    # wrap a coding agent\nheadroom proxy --port 8787              # drop-in proxy, zero code changes\n\n---\n\n### Codex / global install\n\nIf Codex or another MCP client cannot inherit a shell `PATH` reliably, install Headroom as a persistent uv tool and point the client at the absolute binary path:\n\n```bash\nuv tool install \"headroom-ai[all]\"\ncommand -v headroom\n```\n\nThen use the returned path in MCP config:\n\n```toml\n[mcp_servers.headroom]\ncommand = \"/absolute/path/from/command-v/headroom\"\nargs = [\"mcp\", \"serve\"]\n```\n\n`command = \"headroom\"` only works when the client starts with a `PATH` that already includes the uv tool directory.\n\n---\n\n### GitHub Copilot CLI subscription mode\n\nHeadroom can route GitHub Copilot CLI subscription traffic through the local proxy:\n\n```bash\nheadroom copilot-auth login\nheadroom wrap copilot --subscription -- --model gpt-4o\n```\n\nThis lets Headroom intercept OpenAI-compatible Copilot CLI requests and apply the same proxy compression pipeline before forwarding to GitHub Copilot's hosted API. The wrapper exchanges Headroom's reusable GitHub OAuth token for Copilot's short-lived API token and prints the upstream endpoint as `COPILOT_PROVIDER_API_URL=...` during launch.\n\n`headroom copilot-auth login` stores a Headroom-specific Copilot OAuth token.\nThis avoids relying on generic GitHub or Copilot CLI tokens that can read\nCopilot account metadata but may still be rejected by Copilot's token-exchange\nendpoint.\n\nFor GitHub Enterprise Server or custom-domain Copilot deployments, set one of\nthese before launching:\n\n```bash\nexport GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com\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 `headroom` CLI\nnpm install headroom-ai                           # TypeScript SDK (library only — no `headroom` CLI)\ndocker pull ghcr.io/headroomlabs-ai/headroom:latest\n```\n\nGranular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`, `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain, not in `[all]`), `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`, `[pytorch-mps]` (Apple-GPU memory-embedder offload — set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.10+**.\n\n> **Note**: `[all]` covers the core stack but excludes framework adapters. Install them separately: `pip install \"headroom-ai[langchain]\"` (also `[agno]`, `[strands]`, `[anyllm]`, `[bedrock]`).\n\nUsing `uv` for the `headroom` CLI? Prefer `uv tool install` so the command lives in an isolated app environment. On macOS, pass `--python 3.13` if your default `python3` is newer than the current wheel set:\n\n```bash\nbrew install python@3.13  # if Python 3.13 is not already available\nuv tool install --python 3.13 \"headroom-ai[all]\"\nuv tool update-shell      # if ~/.local/bin is not already on PATH\nheadroom --version\n```\n\nFor MCP clients such as Codex that do not inherit your interactive shell `PATH`, configure the absolute executable path returned by `command -v headroom`:\n\n```toml\n[mcp_servers.headroom]\ncommand = \"/Users/you/.local/bin/headroom\"\nargs = [\"mcp\", \"serve\"]\n```\n\nCurrent native wheels cover macOS Apple Silicon and Linux. On Intel macOS, use Docker-native install until native wheel support lands.\n\nUsing `pipx`? Choose a supported interpreter explicitly:\n\n```bash\npipx install --python python3.13 \"headroom-ai[all]\"\n```\n\n> **Pick 3.13 if you want d","github_created_at":"2026-01-07T19:58:51+00:00","created_at":"2026-07-07T17:31:04.553672+00:00","updated_at":"2026-08-16T06:02:05.810477+00:00","categories":[{"slug":"data-retrieval","name":"Data & Retrieval","url":"https://www.graphcanon.com/categories/data-retrieval","markdown_url":"https://www.graphcanon.com/categories/data-retrieval.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/data-retrieval"},{"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"}],"tags":[{"slug":"agent","name":"agent"},{"slug":"ai","name":"ai"},{"slug":"compression","name":"compression"},{"slug":"context-engineering","name":"context-engineering"},{"slug":"token-optimization","name":"token-optimization"}],"trust":{"provenance":{"is_fork":false,"github_id":1129940957,"owner_type":"Organization","methodology":"github_public_v1","parent_repo":null,"near_duplicate_slugs":[]},"computed_at":"2026-08-16T06:02:05.054Z","maintenance":{"label":"Very active","score":96,"methodology":"github_public_v1","releases_90d":17,"days_since_push":0,"last_release_at":"2026-08-13T03:47:18Z","stars_delta_30d":6941,"open_issues_delta_30d":42},"security_summary":{"status":"no_manifest","scanner":null,"low_count":0,"high_count":0,"last_scan_at":"2026-07-11T10:56:46.583Z","medium_count":0,"scan_profile":"mcp_manifest","critical_count":0}},"capability_facts":{"mcp":{"source":"repo_scan","observed_at":"2026-08-16T06:02:05.494Z","server_manifest":false},"scan":{"source":"repo_scan","observed_at":"2026-08-16T06:02:05.494Z"},"deploy":{"source":"dockerfile:Dockerfile","self_host":true,"observed_at":"2026-08-16T06:02:05.494Z","managed_saas":false},"has_cli":{"value":true,"source":"pyproject.toml:[project.scripts]","observed_at":"2026-08-16T06:02:05.494Z"},"languages":{"value":["python"],"source":"github.language+pyproject.toml","observed_at":"2026-08-16T06:02:05.494Z"},"has_docker":{"value":true,"source":"dockerfile:Dockerfile","observed_at":"2026-08-16T06:02:05.494Z"},"license_spdx":{"value":"Apache-2.0","source":"github.license","observed_at":"2026-08-16T06:02:05.494Z"}},"decision_facts":{"hosting":null,"pricing":null,"requirements":null,"constraints":null,"when_to_use":["When you are looking to optimize your token usage in Python-based projects where token count directly affects operational efficiency or cost.","If you need to compress RAG chunks and files before they reach LLMs to maximize context window utilization without altering the response accuracy."],"when_not_to_use":["In scenarios where preserving all original data nuances is critical, as compression might inadvertently alter data interpretation despite maintaining answer integrity.","For projects that require high-speed processing without any delays introduced by headroom's compression algorithms."],"source":"enrich:decision_facts","observed_at":"2026-07-11T12:20:49.140Z"},"constraint_facets":null,"decision_summary":[{"label":"Adopt for","value":"Headroom is a library, proxy, and MCP server that compresses various data inputs intended for LLMs. It can significantly reduce the number of tokens required while maintaining answer integrity."}]}}