Skip to content
Back to search

headroom-marketplace

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/headroomlabs-ai/headroom with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/headroomlabs-ai/headroom'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/headroomlabs-ai-headroom/badge.svg)](/listings/headroomlabs-ai-headroom)

HTML

<a href="/listings/headroomlabs-ai-headroom"><img src="/api/listings/headroomlabs-ai-headroom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
pip install "headroom-ai[all]"                    # CLI/proxy feature set
npm install headroom-ai                           # TypeScript SDK (library only)
docker pull ghcr.io/headroomlabs-ai/headroom:latest

`[all]` includes the CLI/proxy feature set, including image support, without PyTorch-backed dependencies. Add `[ml]`, `[memory]`, `[evals]`, or `[voice]` separately for those features; their PyTorch dependency can install CUDA runtime packages on Linux.

Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`, `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain), `[relevance]`, `[image]`, `[lean]` (torch-free proxy dependency profile; `[sandbox]` is a deprecated alias), `[agno]`, `[langchain]`, `[evals]`, `[voice]`, and `[pytorch-mps]` (Apple-GPU memory-embedder offload — set `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.11+**.

> `[all]` covers the core stack but not the framework adapters. Install those > separately: `pip install "headroom-ai[langchain]"`, and likewise `[agno]`, > `[strands]`, `[anyllm]`, `[bedrock]`.

→ [Installation guide](https://docs.headroomlabs.ai/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.

<details> <summary><b>uv, pipx, and MCP clients that don't inherit your PATH</b></summary>

Prefer `uv tool install` for the CLI 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:

brew install python@3.13  # if 3.13 is not already available
uv tool install --python 3.13 "headroom-ai[all]"
uv tool update-shell      # if ~/.local/bin is not on PATH
headroom --version

Codex and other MCP clients often cannot inherit an interactive shell `PATH`. Configure the absolute path returned by `command -v headroom`:

[mcp_servers.headroom]
command = "/Users/you/.local/bin/headroom"
args = ["mcp", "serve"]

`command = "headroom"` only works when the client starts with a `PATH` that already includes the uv tool directory.

With pipx, choose the interpreter explicitly:

pipx install --python python3.13 "headroom-ai[all]"

Native wheels currently cover macOS Apple Silicon and Linux. On Intel macOS, use the Docker-native install until native wheel support lands.

**CPU requirement (x86/x86_64).** The ONNX-backed features — Magika content detection and embedding relevance — use a precompiled ONNX Runtime that needs **AVX2**. On x86 hosts without AVX2 (some Docker/QEMU setups, older cloud VMs) Headroom falls back to its non-ONNX paths — BM25 relevance, heuristic detection — rather than crashing. `arm64` and Apple Silicon need no AVX2.

</details>

<details> <summary><b>Updating</b></summary>

headroom update          # detects pip / pipx / uv tool and upgrades in place
headroom update --check  # report the latest release without upgrading
headroom update --pre    # include pre-releases

`headroom update` works out how Headroom was installed (pip/venv, `pip --user`, pipx, uv tool) and runs the matching upgrade on macOS, Linux and Windows. For git checkouts, editable installs, Docker images and externally-managed system Pythons (PEP 668) it prints the correct manual step instead of guessing.

The proxy also prints a one-line "update available" notice at startup. It checks PyPI at most once a day, in the background, and never blocks. Opt out with `HEADROOM_UPDATE_CHECK=off`; it is also skipped in `--stateless` mode and CI.

</details>

<details> <summary><b>Corporate networks and SSL inspection</b></summary>

If `pip install "headroom-ai[all]"` fails with `CERTIFICATE_VERIFY_FAILED` (`unable to get local issuer certificate`), your network runs SSL inspection — a MITM proxy presenting a company CA. The build backend (`maturin`) downloads `rustup` over a connection your TLS stack does not trust. Install Rust first so

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 71 lines
  1. {
  2. "name": "headroom-marketplace",
  3. "owner": {
  4. "name": "Headroom Contributors"
  5. },
  6. "metadata": {
  7. "description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
  8. "version": "0.44.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "headroom",
  13. "source": "./plugins/headroom-agent-hooks",
  14. "description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
  15. "version": "0.44.0",
  16. "author": {
  17. "name": "Headroom Contributors",
  18. "url": "https://github.com/headroomlabs-ai/headroom"
  19. },
  20. "homepage": "https://github.com/headroomlabs-ai/headroom",
  21. "repository": "https://github.com/headroomlabs-ai/headroom",
  22. "keywords": [
  23. "headroom",
  24. "hooks",
  25. "claude-code",
  26. "copilot-cli"
  27. ]
  28. },
  29. {
  30. "name": "headroom-skill",
  31. "source": "./plugins/headroom-skill",
  32. "description": "Skill: add headroom-ai compress() to a Python or TypeScript app to cut LLM input tokens (tool outputs, logs, JSON, chat history). No API key.",
  33. "version": "0.44.0",
  34. "author": {
  35. "name": "Headroom Contributors",
  36. "url": "https://github.com/headroomlabs-ai/headroom"
  37. },
  38. "homepage": "https://github.com/headroomlabs-ai/headroom",
  39. "repository": "https://github.com/headroomlabs-ai/headroom",
  40. "keywords": [
  41. "headroom",
  42. "skill",
  43. "token-cost",
  44. "tool-outputs",
  45. "context-window",
  46. "claude-code",
  47. "codex",
  48. "copilot-cli"
  49. ]
  50. },
  51. {
  52. "name": "headroom-snip",
  53. "source": "./plugins/headroom-snip",
  54. "description": "Claude Code mod: watch Headroom snip tokens off every request, with an animated band, a /headroom log and a running total.",
  55. "version": "0.44.0",
  56. "author": {
  57. "name": "Headroom Contributors",
  58. "url": "https://github.com/headroomlabs-ai/headroom"
  59. },
  60. "homepage": "https://github.com/headroomlabs-ai/headroom",
  61. "repository": "https://github.com/headroomlabs-ai/headroom",
  62. "keywords": [
  63. "headroom",
  64. "claude-code",
  65. "tokens",
  66. "compression",
  67. "mod"
  68. ]
  69. }
  70. ]
  71. }
README.md · README · 745 lines
  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/.github/assets/hero.svg" alt="Headroom — the context compression layer for AI agents. A 55,957 token agent prompt compresses to the 24,340 tokens actually sent to the model, and the FATAL line at item 67 survives byte for byte." width="880">
  3. <a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="headroomlabs-ai/headroom | Trendshift — #1 Repository Of The Day" width="250" height="55"/></a>
  4. <p>
  5. <a href="https://github.com/headroomlabs-ai/headroom"><img src="https://img.shields.io/github/stars/headroomlabs-ai/headroom?style=flat&color=00F0B5&labelColor=0C1118&label=stars" alt="GitHub stars"></a>
  6. <a href="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml"><img src="https://github.com/headroomlabs-ai/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  7. <a href="https://pypi.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg?color=00F0B5&labelColor=0C1118&label=pypi" alt="PyPI"></a>
  8. <a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg?color=00F0B5&labelColor=0C1118&label=npm" alt="npm"></a>
  9. <a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-kompress--v2--base-65D8FF?labelColor=0C1118" alt="Model"></a>
  10. <a href="https://docs.headroomlabs.ai/docs"><img src="https://img.shields.io/badge/docs-online-00F0B5?labelColor=0C1118" alt="Docs"></a>
  11. <a href="https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-98A4B3?labelColor=0C1118" alt="License"></a>
  12. </p>
  13. <p>
  14. <b><a href="https://docs.headroomlabs.ai/docs/quickstart">Quickstart</a></b> ·
  15. <b><a href="#headroom-for-teams">Headroom for Teams</a></b> ·
  16. <a href="#get-started-60-seconds">Install</a> ·
  17. <a href="#proof-measured-token-savings">Proof</a> ·
  18. <a href="#agent-compatibility">Agents</a> ·
  19. <a href="https://docs.headroomlabs.ai/docs">Docs</a> ·
  20. <a href="https://discord.gg/yRmaUNpsPJ">Discord</a> ·
  21. <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt">llms.txt</a>
  22. </p>
  23. <sub><b>AI agents / LLMs:</b> read <a href="https://github.com/headroomlabs-ai/headroom/blob/main/llms.txt"><code>/llms.txt</code></a> here, or fetch
  24. <a href="https://docs.headroomlabs.ai/llms.txt">the live index</a> ·
  25. <a href="https://docs.headroomlabs.ai/llms-full.txt">full docs blob</a>.</sub>
  26. </div>
  27. <!-- mcp-name: io.github.headroomlabs-ai/headroom -->
  28. **Headroom** (`headroom-ai` on PyPI and npm) compresses everything your AI agent
  29. reads — tool outputs, logs, RAG chunks, files, and conversation history — before
  30. it reaches the LLM. Same answers, fewer input tokens. Measured: 21–57% fewer
  31. input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log
  32. lines, little on prose ([Proof](#proof-measured-token-savings)). Compression
  33. runs on your machine; no prompt or file content is sent anywhere to be compressed.
  34. ## Start here
  35. **My app calls an LLM** (Python, LangChain, LiteLLM, Agno, Strands):
  36. ```bash
  37. pip install headroom-ai
  38. ```
  39. ```python
  40. from headroom import compress
  41. result = compress(messages, model="gpt-4o") # OpenAI or Anthropic message dicts
  42. client.chat.completions.create(model="gpt-4o", messages=result.messages)
  43. ```
  44. No API key, no model download, in-process. Set `HEADROOM_OFFLINE=1` for a
  45. zero-network run. Tool and assistant messages are compressed; user messages are
  46. left alone unless you pass `compress_user_messages=True`.
  47. [FastAPI example](https://docs.headroomlabs.ai/docs/fastapi) ·
  48. [API reference](https://docs.headroomlabs.ai/docs/api-reference).
  49. TypeScript apps: `npm install headroom-ai` plus the proxy
  50. (`pip install "headroom-ai[proxy]"`, `headroom proxy --port 8787`); the npm SDK
  51. sends messages to it. [TypeScript quickstart](https://docs.headroomlabs.ai/docs/quickstart)
  52. **I run coding agents** (Claude Code, Codex, Cursor, Copilot, OpenCode, Aider):
  53. ```bash
  54. uv tool install --python 3.13 "headroom-ai[all]"
  55. headroom wrap claude
  56. ```
  57. Zero code changes. [Agent compatibility](#agent-compatibility) ·
  58. [Proxy](https://docs.headroomlabs.ai/docs/proxy)
  59. <p align="center">
  60. <a href="https://headroomlabs.ai"><img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/.github/assets/enterprise-perk.svg" alt="Headroom Enterprise for teams. Talk to us: hello@headroomlabs.ai." width="880"></a>
  61. </p>
  62. <div align="center">
  63. <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/HeadroomDemo-Fast.gif" alt="Headroom compressing a 10,144 token log dump to 1,260 tokens while preserving the FATAL line" width="820">
  64. <br><sub>10,144 → 1,260 tokens. The same <code>FATAL</code> found.</sub>
  65. </div>
  66. ## What it does
  67. - **Library** — `compress(messages)` in Python or TypeScript, inline in any app.
  68. - **Proxy** — `headroom proxy --port 8787`, zero code changes, any language.
  69. - **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode` in one command; undo with `headroom unwrap <tool>`.
  70. - **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client.
  71. - **Cross-agent memory** — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
  72. - **`headroom learn`** — mines failed sessions and writes corrections to `CLAUDE.local.md` (default, gitignored), `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `GROK.md`.
  73. - **Output token reduction** — trims what the model *writes back*, not only what you send. See [below](#output-token-reduction).
  74. - **Reversible (CCR)** — originals are cached locally and retrieved on demand.
  75. ## How it works
  76. ```
  77. Your agent / app
  78. (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
  79. │ prompts · tool outputs · logs · RAG results · files
  80. ▼
  81. ┌────────────────────────────────────────────────────┐
  82. │ Headroom (runs locally — your data stays here) │
  83. │ ──────────────────────────────────────────────── │
  84. │ CacheAligner → ContentRouter → CCR │
  85. │ ├─ SmartCrusher (JSON) │
  86. │ ├─ CodeCompressor (AST) │
  87. │ └─ Kompress-v2-base (text, HF) │
  88. │ │
  89. │ Cross-agent memory · headroom learn · MCP │
  90. └────────────────────────────────────────────────────┘
  91. │ compressed prompt + retrieval tool
  92. ▼
  93. LLM provider (Anthropic · OpenAI · Bedrock · …)
  94. ```
  95. - **ContentRouter** detects the content type and selects a compressor for it.
  96. - **SmartCrusher / CodeCompressor / Kompress-v2-base** handle JSON, source code and prose respectively.
  97. - **CacheAligner** flags volatile content that would bust a provider KV-cache prefix. It never rewrites prompts.
  98. - **CCR** stores originals locally so the model can call `headroom_retrieve` when it needs the full text.
  99. → [Architecture](https://docs.headroomlabs.ai/docs/architecture) ·
  100. [CCR](https://docs.headroomlabs.ai/docs/ccr) ·
  101. [Kompress-v2-base model card](https://huggingface.co/chopratejas/kompress-v2-base)
  102. ## Get started (60 seconds)
  103. ```bash
  104. # 1 — Install
  105. uv tool install --python 3.13 "headroom-ai[all]" # CLI in a self-contained env
  106. pip install "headroom-ai[all]" # Python — ships the `headroom` CLI
  107. npm install headroom-ai # TypeScript SDK only — no CLI
  108. # 2 — Pick a mode
  109. headroom deploy # turnkey local deployment + agent config
  110. headroom wrap claude # wrap a coding agent
  111. headroom proxy --port 8787 # drop-in proxy, zero code changes
  112. # or: from headroom import compress # inline library
  113. # 3 — Check it and watch the savings
  114. headroom doctor # health check — confirms routing works
  115. headroom perf
  116. headroom dashboard # live savings (proxy must be running)
  117. ```
  118. ### Reduce input tokens in your own app
  119. ```python
  120. from headroom import compress
  121. from openai import OpenAI
  122. messages = [{"role": "user", "content": "Analyze these results"}]
  123. result = compress(messages, model="gpt-4o")
  124. client = OpenAI()
  125. response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
  126. print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
  127. ```
  128. Launch a wrapped agent session each time, so the setup runs. `headroom wrap`
  129. starts a local proxy and launches the agent configured to route through
  130. Headroom. Add `--code-memory serena` to also install
  131. **[Serena](https://github.com/oraios/serena)** for semantic code navigation (off
  132. by default). For Claude Code, Serena is registered for the wrapped project only
  133. (as a `local`-scope MCP server in `~/.claude.json`); use `--code-memory-scope user`
  134. to make it available in every project. `headroom unwrap` removes either registration.
  135. `headroom wrap ...` is session-scoped: its proxy exits with the wrapped agent.
  136. For a proxy that survives reboots, use the turnkey `headroom deploy` command.
  137. Use `headroom install apply` when you need to choose a specific persistent
  138. service, scheduled task, Docker runtime, scope, or provider target; see the
  139. [persistent installs guide](https://docs.headroomlabs.ai/docs/persistent-installs).
  140. The `headroom` CLI ships only in the PyPI package. The npm `headroom-ai` package
  141. is the TypeScript SDK — a library you import
  142. (`import { compress } from 'headroom-ai'`) — and provides no `headroom` command.
  143. ## Proof: measured token savings
  144. Four scenarios built from real MCP server output formats, measured with the
  145. provider tokenizer and the shipped `compress()` at its default configuration.
  146. Seeded and offline, so you get the same numbers we did:
  147. ```bash
  148. uv run python benchmarks/index_proof_table.py --seed 20260902
  149. ```
  150. | Scenario | Before | After | Saved |
  151. |---|---:|---:|---:|
  152. | Code search (100 results) | 17,199 | 13,597 | **21%** |
  153. | SRE incident debugging | 55,957 | 24,340 | **57%** |
  154. | Codebase exploration | 58,801 | 33,895 | **42%** |
  155. | GitHub issue triage | 46,067 | 32,429 | **30%** |
  156. Savings scale with how repetitive the payload is. Repeated JSON arrays and log
  157. lines clear 90% in `benchmarks/bench_latency.py`; prose and already-dense output
  158. compress very little. Run `headroom savings` against your own traffic for the
  159. number that applies to you.
  160. Compression costs **well under a millisecond** — 0.21 ms p50 on a 10K-token JSON
  161. search result, 1.4 ms at 100K tokens — so it does not show up in agent latency.
  162. **Accuracy.** `python -m headroom.evals suite --tier 1`:
  163. | Benchmark | Category | N | Baseline | Headroom | Delta |
  164. |---|---|---:|---:|---:|---|
  165. | GSM8K | Math | 100 | 0.870 | 0.870 | ±0.000 |
  166. | TruthfulQA | Factual | 100 | 0.530 | 0.560 | +0.030 |
  167. | SQuAD v2 | QA | 100 | — | 97% | at 19% compression |
  168. | BFCL | Tools | 100 | — | 97% | at 32% compression |
  169. At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA
  170. shows no detectable difference rather than an improvement.
  171. [Methodology →](https://docs.headroomlabs.ai/docs/benchmarks)
  172. ## Output token reduction
  173. Everything above shrinks the prompt you **send**. You also pay for every token
  174. the model **writes back**, and on Opus-class models output costs 5× input. Much
  175. of that output is ceremony: "Great, let me…" preambles, code re-printed straight
  176. back at you, and deep reasoning spent on routine steps like reading a file.
  177. Headroom trims it from the proxy, with no change to your code:
  178. - **Verbosity steering** appends a short "be terse, don't restate context" note to the *end* of the system prompt, so your prompt cache still hits.
  179. It applies to Anthropic `/v1/messages` and to OpenAI-compatible
  180. `/v1/chat/completions` and `/v1/responses`, with the same `output_shaper:*`
  181. labels on all paths.
  182. ```bash
  183. export HEADROOM_OUTPUT_SHAPER=1 # off by default
  184. headroom proxy --port 8787
  185. ```
  186. > **Already running a proxy?** These switches are read live on every request, so
  187. > a proxy that `headroom wrap` *reused* rather than started would not see a value
  188. > you export afterwards — its environment was snapshotted at launch. `headroom
  189. > wrap` hot-syncs your current settings to the running proxy over a loopback
  190. > `POST /admin/runtime-env`, so they take effect with no restart and no dropped
  191. > requests. On a shared proxy these overrides are global; the last explicit
  192. > setting wins.
  193. **Terseness you didn't have to configure.** People rarely state how terse they
  194. want answers — they show it, by interrupting long replies or moving on before
  195. they could have read them. `headroom learn --verbosity` reads past sessions and
  196. picks the level:
  197. ```bash
  198. headroom learn --verbosity # dry run — preview what it found
  199. headroom learn --verbosity --apply # save it and apply it to the running proxy
  200. ```
  201. A proxy in cache mode (the default) never re-reads the learned level, because a
  202. level that changes mid-conversation would bust the prompt cache. There `--apply`
  203. pins it with `HEADROOM_VERBOSITY_LEVEL`; set that variable yourself to keep it
  204. after a restart.
  205. **Measuring it.** Output savings are counterfactual — we never see what the model
  206. *would* have written — so Headroom reports an estimate with a confidence range
  207. and labels it as one:
  208. ```bash
  209. headroom output-savings
  210. # Reduction: 31.7% (95% CI 27.7% … 35.7%) [estimated]
  211. ```
  212. For a measured number instead, hold out 10% of conversations as an unshaped
  213. control: `export HEADROOM_OUTPUT_HOLDOUT=0.1`. The dashboard's **Output Tokens
  214. Saved** card then reads `measured` rather than `estimated`, with the band.
  215. → [Output token reduction](https://docs.headroomlabs.ai/docs/savings)
  216. ## Agent compatibility
  217. | Agent | `headroom wrap` | Notes |
  218. |---|:---:|---|
  219. | Claude Code | ✅ | `--memory` · `--code-graph` · `--1m` · `--tool-search` |
  220. | Codex | ✅ | shares memory with Claude |
  221. | Grok CLI | ✅ | routes via `GROK_MODELS_BASE_URL` |
  222. | Cursor | Manual setup | starts the proxy and prints base URLs for Cursor settings |
  223. | Aider | ✅ | starts proxy + launches |
  224. | Copilot CLI | ✅ | starts proxy + launches |
  225. | VS Code Copilot | ✅ | transparent proxy; keeps the selected model |
  226. | OpenClaw | ✅ | installs as a ContextEngine plugin |
  227. | OpenCode | ✅ | injects config · starts proxy + launches [^third-party-upstream] |
  228. | Cline | ✅ | starts proxy + injects config |
  229. | Continue | ✅ | starts proxy + injects config |
  230. | Goose | ✅ | starts proxy + launches |
  231. | OpenHands | ✅ | starts proxy + launches |
  232. | Mistral Vibe | ✅ | starts proxy + launches |
  233. | Oh My Pi | ✅ | Anthropic + OpenAI/Codex · injects config · starts proxy + launches |
  234. | Factory Droid | ✅ | routes via `FACTORY_API_BASE_URL`; Anthropic-model turns compressed, other Factory traffic passed through |
  235. | Cortex Code | Library only | 60–65% savings in library mode; no `wrap` |
  236. | Kimi CLI | ✅ | OAuth bearer forwarded — log in once |
  237. | ZCode | ✅ | starts the proxy and prints base URLs for ZCode settings |
  238. [^third-party-upstream]: `headroom wrap` routes OpenAI-compatible traffic to the default upstream (`https://api.openai.com/v1`). For a third-party OpenAI-compatible provider (DeepSeek, Together, OpenRouter, a self-hosted gateway), pass `--openai-api-url https://api.deepseek.com/v1` — or set `OPENAI_TARGET_API_URL` before wrapping — otherwise your provider key is sent to OpenAI and rejected with `401 Incorrect API key provided`. See [OpenCode + DeepSeek](https://docs.headroomlabs.ai/docs/opencode-deepseek).
  239. Any OpenAI-compatible client works through `headroom proxy`. MCP-native clients:
  240. `headroom mcp install`. Undo durable wrapping with `headroom unwrap <tool>`
  241. (`claude`, `copilot`, `codex`, `grok`, `kimi`, `omp`, `opencode`, `openclaw`,
  242. `zcode`). Registry authors should use the canonical [`server.json`](https://github.com/headroomlabs-ai/headroom/blob/main/server.json)
  243. rather than reconstructing the `headroom mcp serve` contract from prose.
  244. For Anthropic `/v1/messages`, `--mode cache` skips automatic `--memory` context injection so the provider prefix remains stable. OpenAI chat/responses and Gemini append memory to the live-zone tail. Use `--mode token` when you need automatic memory context on the Anthropic path.
  245. <details>
  246. <summary><b>GitHub Copilot CLI subscription mode</b></summary>
  247. Headroom can route Copilot CLI subscription traffic through the local proxy:
  248. ```bash
  249. headroom copilot-auth login
  250. headroom wrap copilot --subscription -- --model gpt-4o
  251. ```
  252. The wrapper exchanges Headroom's reusable GitHub OAuth token for Copilot's
  253. short-lived API token and prints the upstream endpoint as
  254. `COPILOT_PROVIDER_API_URL=...` at launch. `headroom copilot-auth login` stores a
  255. Headroom-specific Copilot OAuth token, rather than relying on generic GitHub or
  256. Copilot CLI tokens that can read account metadata but are still rejected by
  257. Copilot's token-exchange endpoint.
  258. For GitHub Enterprise Server or a custom-domain Copilot deployment, set one of
  259. these before launching. If both are set, the URL wins:
  260. ```bash
  261. export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
  262. export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com
  263. ```
  264. For GitHub.com Enterprise Cloud URLs such as
  265. `github.com/enterprises/your-enterprise`, set neither — Headroom uses GitHub's
  266. normal token-exchange endpoint and the Copilot API endpoint advertised for the
  267. signed-in account.
  268. **Platform support.** macOS auth reuse through Copilot CLI Keychain storage and
  269. Windows device authentication are live-tested. Copilot CLI 1.0.81 does not expose
  270. its Windows login through the legacy Credential Manager schema Headroom reads, so
  271. run `headroom copilot-auth login` on Windows. Linux Secret Service /
  272. `secret-tool` reuse is implemented but not yet validated on a real desktop. In
  273. Docker and CI, pass an explicit `GITHUB_COPILOT_TOKEN` or
  274. `GITHUB_COPILOT_GITHUB_TOKEN` instead of relying on host keychain access.
  275. </details>
  276. <details>
  277. <summary><b>GitHub Copilot in VS Code</b></summary>
  278. Headroom overrides Copilot's API proxy endpoint, so the VS Code model picker
  279. stays authoritative. GPT-5.5, GPT-5.6 Luna/Sol/Terra, Claude Sonnet/Opus and
  280. other Copilot models keep their original model IDs while traffic passes through
  281. the local compression proxy. Headroom does not patch VS Code or change Codex
  282. settings.
  283. ```bash
  284. headroom copilot-auth login
  285. headroom wrap vscode
  286. ```
  287. Keep the command running and use Copilot normally. The short-lived upstream
  288. Copilot token is held only in the proxy process.
  289. [Full guide →](https://docs.headroomlabs.ai/docs/vscode-copilot)
  290. </details>
  291. <details>
  292. <summary><b>Claude Code in VS Code</b></summary>
  293. The official Claude Code extension embeds Claude Code and reads the same user
  294. settings as the CLI. Install the proxy extra, then run the wrapper from the
  295. project you will open in VS Code:
  296. ```bash
  297. pip install "headroom-ai[proxy]"
  298. headroom wrap vscode-claude
  299. # Optional: persist Claude Code's client-owned 1M model selector
  300. headroom wrap vscode-claude --1m
  301. ```
  302. Reload the VS Code window on first run. Keep the wrapper terminal running while
  303. you use the Claude Code panel; the dashboard or proxy log printed at startup
  304. shows requests and savings. Your Anthropic authentication and selected model are
  305. preserved. `Ctrl+C` stops the proxy; `headroom unwrap vscode-claude` restores the
  306. settings that existed before setup.
  307. With `--1m`, Headroom writes the resolved `[1m]` model selector to Claude Code's
  308. top-level user setting and restores the exact prior model on
  309. `headroom unwrap vscode-claude` or when setup runs again without `--1m`. Use
  310. `headroom wrap vscode-claude --no-configure --1m` to print the setting without
  311. writing files.
  312. Claude Code and Anthropic own 1M model support and account eligibility. Local
  313. tests prove persisted settings and restoration, not a live entitled VS Code
  314. session or the resulting context window.
  315. [Full guide →](https://docs.headroomlabs.ai/docs/vscode-claude-code)
  316. </details>
  317. ## When to use · when to skip
  318. **Use the library** (`compress()`) when your own code builds the prompt: an API
  319. that forwards tool results, logs, search hits, database rows or long chat
  320. history to a model. It is a function over the message list, runs in-process with
  321. no key and no network, and works anywhere Python runs, including sandboxes and
  322. serverless functions.
  323. **Use the proxy or `headroom wrap`** when you want savings on a coding agent or
  324. any client you do not control, with no code changes, or when you want one shared
  325. memory across several agents. Either way, compression is reversible: originals
  326. stay retrievable through CCR for the configured TTL.
  327. **Skip it** for short conversational prompts and prose: there is little to
  328. compress, and blocks under the Kompress `min_input_words` floor come back
  329. byte-identical. If your provider's native compaction already covers your traffic
  330. and you do not need reversibility or cross-agent memory, you may not need
  331. Headroom either. [Limitations](https://docs.headroomlabs.ai/docs/limitations)
  332. has the full list.
  333. <details>
  334. <summary><b>Integrations — drop Headroom into any stack</b></summary>
  335. | Your setup | Hook in with |
  336. |---|---|
  337. | Any Python app | `compress(messages, model=…)` |
  338. | Any TypeScript app | `await compress(messages, { model })` |
  339. | Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
  340. | Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
  341. | LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
  342. | LangChain | `HeadroomChatModel(your_llm)` |
  343. | Agno | `HeadroomAgnoModel(your_model)` |
  344. | Strands | [Strands guide](https://docs.headroomlabs.ai/docs/strands) |
  345. | ASGI apps | `app.add_middleware(CompressionMiddleware)` |
  346. | Multi-agent | `SharedContext().put / .get` |
  347. | MCP clients | `headroom mcp install` |
  348. </details>
  349. <details>
  350. <summary><b>What's inside</b></summary>
  351. - **SmartCrusher** — universal JSON: arrays of dicts, nested objects, mixed types. It keeps error items, values outside the normal statistical range, and first/last boundaries, selected from field-variance statistics rather than a keyword list.
  352. - **CodeCompressor** — AST-aware for Python, JS/TS, Go, Rust, Java, C/C++, C#, PHP.
  353. - **Kompress-v2-base** — our HuggingFace model, trained on agentic traces.
  354. - **Image compression** — 40–90% reduction through a trained ML router.
  355. - **CacheAligner** — flags volatile content that would bust a provider KV-cache prefix; never rewrites prompts.
  356. - **Live-zone compression** — only new bytes are compressed (fresh tool output, the latest turn). The frozen prefix stays byte-identical, so the provider cache survives, and history is never dropped.
  357. - **CCR** — reversible compression; the model retrieves originals on demand.
  358. - **Cross-agent memory** — shared store with agent provenance and auto-dedup.
  359. - **SharedContext** — compressed context passing across multi-agent workflows.
  360. - **`headroom learn`** — plugin-based failure mining for Claude, Codex and Gemini.
  361. </details>
  362. <details>
  363. <summary><b>Pipeline internals</b></summary>
  364. One request lifecycle is shared by `compress()`, the SDKs and the proxy:
  365. `Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` →
  366. `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` →
  367. `Post-Send` → `Response Received`
  368. - **Transforms** do the work: CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base, live-zone only. IntelligentContext and RollingWindow were retired in PR-B1.
  369. - **Pipeline extensions** observe or customise lifecycle stages through `on_pipeline_event(...)`.
  370. - **Compression hooks** sit alongside the lifecycle as an additional extension seam.
  371. - **Proxy extensions** are the integration seam for ASGI middleware, routes and startup policy.
  372. Provider- and tool-specific behaviour lives under `headroom/providers/`, so core
  373. orchestration stays focused on lifecycle, sequencing and policy:
  374. - CLI/tool slices — `headroom/providers/claude`, `copilot`, `codex`, `grok`, `openclaw`
  375. - Provider runtime slices — `headroom/providers/claude`, `gemini`, with shared backend dispatch in `headroom/providers/registry.py`
  376. - `wrap.py`, `client.py`, `cli/proxy.py` and `proxy/server.py` delegate env shaping, API target normalisation, backend selection and transport dispatch
  377. </details>
  378. ## Install
  379. ```bash
  380. uv tool install --python 3.13 "headroom-ai[all]" # CLI, isolated app env
  381. pip install "headroom-ai[all]" # CLI/proxy feature set
  382. npm install headroom-ai # TypeScript SDK (library only)
  383. docker pull ghcr.io/headroomlabs-ai/headroom:latest
  384. ```
  385. `[all]` includes the CLI/proxy feature set, including image support, without PyTorch-backed dependencies.
  386. Add `[ml]`, `[memory]`, `[evals]`, or `[voice]` separately for those features;
  387. their PyTorch dependency can install CUDA runtime packages on Linux.
  388. Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-v2-base), `[code]`,
  389. `[memory]`, `[vector]` (optional HNSW backend — needs a C++ toolchain),
  390. `[relevance]`, `[image]`, `[lean]` (torch-free proxy dependency profile; `[sandbox]` is a deprecated alias), `[agno]`, `[langchain]`, `[evals]`, `[voice]`, and
  391. `[pytorch-mps]` (Apple-GPU memory-embedder offload — set
  392. `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`). Requires **Python 3.11+**.
  393. > `[all]` covers the core stack but not the framework adapters. Install those
  394. > separately: `pip install "headroom-ai[langchain]"`, and likewise `[agno]`,
  395. > `[strands]`, `[anyllm]`, `[bedrock]`.
  396. → [Installation guide](https://docs.headroomlabs.ai/docs/installation) — Docker
  397. tags, persistent service, PowerShell, devcontainers.
  398. <details>
  399. <summary><b>uv, pipx, and MCP clients that don't inherit your PATH</b></summary>
  400. Prefer `uv tool install` for the CLI so the command lives in an isolated app
  401. environment. On macOS, pass `--python 3.13` if your default `python3` is newer
  402. than the current wheel set:
  403. ```bash
  404. brew install python@3.13 # if 3.13 is not already available
  405. uv tool install --python 3.13 "headroom-ai[all]"
  406. uv tool update-shell # if ~/.local/bin is not on PATH
  407. headroom --version
  408. ```
  409. Codex and other MCP clients often cannot inherit an interactive shell `PATH`.
  410. Configure the absolute path returned by `command -v headroom`:
  411. ```toml
  412. [mcp_servers.headroom]
  413. command = "/Users/you/.local/bin/headroom"
  414. args = ["mcp", "serve"]
  415. ```
  416. `command = "headroom"` only works when the client starts with a `PATH` that
  417. already includes the uv tool directory.
  418. With pipx, choose the interpreter explicitly:
  419. ```bash
  420. pipx install --python python3.13 "headroom-ai[all]"
  421. ```
  422. Native wheels currently cover macOS Apple Silicon and Linux. On Intel macOS, use
  423. the Docker-native install until native wheel support lands.
  424. **CPU requirement (x86/x86_64).** The ONNX-backed features — Magika content
  425. detection and embedding relevance — use a precompiled ONNX Runtime that needs
  426. **AVX2**. On x86 hosts without AVX2 (some Docker/QEMU setups, older cloud VMs)
  427. Headroom falls back to its non-ONNX paths — BM25 relevance, heuristic detection —
  428. rather than crashing. `arm64` and Apple Silicon need no AVX2.
  429. </details>
  430. <details>
  431. <summary><b>Updating</b></summary>
  432. ```bash
  433. headroom update # detects pip / pipx / uv tool and upgrades in place
  434. headroom update --check # report the latest release without upgrading
  435. headroom update --pre # include pre-releases
  436. ```
  437. `headroom update` works out how Headroom was installed (pip/venv, `pip --user`,
  438. pipx, uv tool) and runs the matching upgrade on macOS, Linux and Windows. For git
  439. checkouts, editable installs, Docker images and externally-managed system Pythons
  440. (PEP 668) it prints the correct manual step instead of guessing.
  441. The proxy also prints a one-line "update available" notice at startup. It checks
  442. PyPI at most once a day, in the background, and never blocks. Opt out with
  443. `HEADROOM_UPDATE_CHECK=off`; it is also skipped in `--stateless` mode and CI.
  444. </details>
  445. <details>
  446. <summary><b>Corporate networks and SSL inspection</b></summary>
  447. If `pip install "headroom-ai[all]"` fails with `CERTIFICATE_VERIFY_FAILED`
  448. (`unable to get local issuer certificate`), your network runs SSL inspection — a
  449. MITM proxy presenting a company CA. The build backend (`maturin`) downloads
  450. `rustup` over a connection your TLS stack does not trust. Install Rust first so
  451. the build never fetches it:
  452. ```bash
  453. # macOS / Linux
  454. curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
  455. # Windows
  456. winget install Rustlang.Rustup && rustup default stable
  457. ```
  458. Restart your shell, then install. A prebuilt wheel avoids the Rust build
  459. entirely: `pip install --only-binary headroom-ai headroom-ai`. Wheels are
  460. published for Windows (`win_amd64`), Linux (`x86_64` / `aarch64`) and macOS
  461. (Apple Silicon and Intel), so those platforms never need a local Rust toolchain —
  462. the Rust-first step above is only for the sdist fallback when no wheel matches.
  463. **At runtime** Headroom verifies upstream TLS against the operating system's
  464. certificate store — where IT installs the Zscaler / Netskope / Palo Alto root —
  465. plus certifi's public roots, so a managed machine normally needs no setup.
  466. `headroom doctor --network` shows who signed each upstream certificate, whether
  467. Headroom trusts it, and whether a gateway block page is in the way. If the root
  468. is not in the OS store, export it as PEM and set
  469. `HEADROOM_CA_BUNDLE=/path/to/root.pem` (`NODE_EXTRA_CA_CERTS` also works). Full
  470. guide and the domain list for IT: [Corporate networks](https://docs.headroomlabs.ai/docs/corporate-networks).
  471. Two download hosts can still need attention:
  472. - **`cdn.pyke.io`** — the ONNX Runtime for the Rust core, fetched with Mozilla's roots only. Pre-provide it with `ORT_STRATEGY=system` and `ORT_LIB_LOCATION=/path/to/onnxruntime`.
  473. - **`huggingface.co`** — the `kompress-base` model (Python, OS store) and the Rust core's embedding model (Mozilla's roots only). If the domain is blocked, pre-download and run with `HF_HUB_OFFLINE=1`, or point `HF_ENDPOINT` at a trusted mirror.
  474. Running with compression disabled (pure gateway) needs neither asset.
  475. **Intel macOS: no prebuilt ONNX Runtime ([#941](https://github.com/headroomlabs-ai/headroom/issues/941)).**
  476. `ort-sys` ships no prebuilt binary for `x86_64-apple-darwin`, so a source build
  477. fails by default even outside a corporate proxy. Point it at a system runtime:
  478. ```bash
  479. brew install onnxruntime
  480. ORT_STRATEGY=system \
  481. ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
  482. ORT_PREFER_DYNAMIC_LINK=1 \
  483. pip install "headroom-ai[all]"
  484. # ORT is dlopen'd at runtime too:
  485. export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib"
  486. ```
  487. `ORT_LIB_LOCATION` must point at `lib/`, not the bare prefix, and
  488. `ORT_PREFER_DYNAMIC_LINK=1` is required — without it `ORT_STRATEGY=system` still
  489. attempts static linking, which the Homebrew keg does not provide.
  490. **"Basic Constraints of CA cert not marked critical"** only occurs with
  491. `HEADROOM_CERT_STORE=bundled` (the OS store verifies these roots fine). If TLS
  492. fails with:
  493. ```
  494. [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
  495. Basic Constraints of CA cert not marked critical
  496. ```
  497. then the corporate CA *is* found and trusted, and adding it to a CA bundle
  498. changes nothing. Python 3.13 with OpenSSL 3.x enables `VERIFY_X509_STRICT` by
  499. default, which enforces RFC 5280 §4.2.1.9: a CA cert's `basicConstraints` must be
  500. marked critical. Inspection roots such as Zscaler set `CA:TRUE` without the
  501. critical bit, so the chain is rejected.
  502. `HEADROOM_TLS_STRICT=0` clears only the strict flag, from every TLS context
  503. Headroom controls — the proxy's httpx upstream client and the
  504. urllib3/`huggingface_hub` path used for model downloads. Chain validation,
  505. signature, expiry and hostname checks all stay on.
  506. ```bash
  507. HEADROOM_TLS_STRICT=0 headroom proxy --port 8787
  508. ```
  509. The Rust core's downloads use rustls with Mozilla's roots and are unaffected by
  510. `HEADROOM_TLS_STRICT` and the CA variables; pre-provision ONNX Runtime with
  511. `ORT_STRATEGY=system` and models via `HF_ENDPOINT` as above.
  512. </details>
  513. ## headroom learn
  514. <div align="center">
  515. <img src="https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/headroom_learn.gif" alt="headroom learn mining failed sessions and writing corrections" width="720">
  516. </div>
  517. `headroom learn` mines failed sessions and writes corrections to
  518. `CLAUDE.local.md` (default, gitignored; use `--target CLAUDE.md` for the shared
  519. team file), `AGENTS.md` or `GEMINI.md`.
  520. → [Failure learning](https://docs.headroomlabs.ai/docs/failure-learning)
  521. ## Telemetry
  522. An anonymous beacon is **on by default**. It reports how compression behaved:
  523. ratios, counters, provider and model IDs, OS and architecture. It never sends
  524. prompts, completions, code or file paths. It exists so we can see when a release
  525. regresses a compression ratio across real workloads rather than only our own test
  526. corpus.
  527. Turn it off with `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off`, the
  528. `DO_NOT_TRACK=1` convention, or `HEADROOM_OFFLINE=1`. The full field list is in
  529. [the proxy docs](https://docs.headroomlabs.ai/docs/proxy).
  530. ## Headroom for teams
  531. **Not seeing the savings you want?** Headroom OSS is a framework. It was built to show
  532. what's possible on one developer's laptop, so it saves less than it could. We are
  533. building bigger savings for teams and enterprises in Headroom Enterprise, which adds:
  534. - More cost savings
  535. - Tokens secured
  536. - On premise deployment
  537. - Deep attribution
  538. - And many more features
  539. If you're a team or an enterprise, **talk to us**:
  540. [hello@headroomlabs.ai](mailto:hello@headroomlabs.ai) · [headroomlabs.ai](https://headroomlabs.ai)
  541. Everything in this repo stays open source under Apache 2.0.
  542. ## Documentation
  543. | Start here | Go deeper |
  544. |---|---|
  545. | [Quickstart](https://docs.headroomlabs.ai/docs/quickstart) | [Architecture](https://docs.headroomlabs.ai/docs/architecture) |
  546. | [Proxy](https://docs.headroomlabs.ai/docs/proxy) | [How compression works](https://docs.headroomlabs.ai/docs/how-compression-works) |
  547. | [MCP tools](https://docs.headroomlabs.ai/docs/mcp) | [CCR — reversible compression](https://docs.headroomlabs.ai/docs/ccr) |
  548. | [Memory](https://docs.headroomlabs.ai/docs/memory) | [Cache optimization](https://docs.headroomlabs.ai/docs/cache-optimization) |
  549. | [Failure learning](https://docs.headroomlabs.ai/docs/failure-learning) | [Benchmarks](https://docs.headroomlabs.ai/docs/benchmarks) |
  550. | [Configuration](https://docs.headroomlabs.ai/docs/configuration) | [Limitations](https://docs.headroomlabs.ai/docs/limitations) |
  551. | [Persistent installs](https://docs.headroomlabs.ai/docs/persistent-installs) | [Savings analytics](https://docs.headroomlabs.ai/docs/savings) |
  552. ## Compared to
  553. Headroom runs locally, covers every content type, works with every major
  554. framework, and is reversible.
  555. | | Scope | Deploy | Local | Reversible |
  556. |---|---|---|:---:|:---:|
  557. | **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
  558. | [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
  559. | OpenAI Compaction | Conversation history | Provider-native | No | No |
  560. Headroom is the proxy, and it compresses everything flowing through it whatever
  561. sits upstream. Our recommended companion is
  562. **[Serena](https://github.com/oraios/serena)** for semantic code navigation,
  563. installed with `headroom wrap --code-memory serena`, plus **Ponytail** if you want leaner
  564. model output. Everything else is your call — attach a code-memory MCP, Graphify,
  565. Caveman, or any other MCP server, and Headroom compresses downstream of all of it.
  566. ## Contributing
  567. ```bash
  568. git clone https://github.com/headroomlabs-ai/headroom.git && cd headroom
  569. uv sync --extra dev && uv run pytest
  570. ```
  571. Devcontainers in `.devcontainer/` (default, plus `memory-stack` with Qdrant and
  572. Neo4j). See [CONTRIBUTING.md](https://github.com/headroomlabs-ai/headroom/blob/main/CONTRIBUTING.md).
  573. ## Community
  574. - **[Discord](https://discord.gg/yRmaUNpsPJ)** — questions, feedback, war stories.
  575. - **[Kompress-v2-base on HuggingFace](https://huggingface.co/chopratejas/kompress-v2-base)** — the model behind text compression.
  576. - **[Claude Code status-line plugin](https://github.com/Ship-Wright/headroom-plugin)** — live token savings in your status line, by [@Ship-Wright](https://github.com/Ship-Wright).
  577. ## License
  578. Apache 2.0 — see [LICENSE](https://github.com/headroomlabs-ai/headroom/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.