headroomlabs-ai/headroom
headroom
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.
GitHub metrics
- Stars
- 75K
- +810 this week
- Forks
- 5.8K
- 30-day growth
- —
- Open issues
- 211
| Day | GitHub stars |
|---|---|
| 2026-10-04 | 74357 |
| 2026-10-10 | 74880 |
| 2026-10-13 | 75167 |
What it does
Headroom is a Python and TypeScript tool that shrinks the text an AI agent sends to a model (tool output, logs, files, RAG chunks and chat history) so each request uses fewer tokens. The compression runs on your own machine.
You can use it in four ways: a compress() library for Python and TypeScript, a local proxy you point an app at, a headroom wrap command that starts coding agents such as Claude Code, Codex or Aider through that proxy, or an MCP server. A router looks at each piece of content and picks a compressor: one for JSON, one for source code, and a small Hugging Face model called Kompress-v2-base for prose. Originals stay in a local cache, and the model can call a retrieve tool when the short version is not enough.
The project publishes its own offline benchmark of four MCP-style scenarios, with savings from 21% to 57%. The README also describes steering the model toward shorter replies and labels that saving as an estimate. The latest release is v0.39.1, from September 2026.
Why it matters
Agents spend much of their context window on bulky tool results and logs that the model only skims. Headroom compresses that material before it is sent, picks a different method for JSON, code and prose, and keeps the originals so nothing is lost for good. It drops into existing setups as a proxy or a one-command agent wrapper, so you do not have to change application code to try it.
Main features
- `compress()` library for Python, plus a TypeScript SDK
- Local proxy started with `headroom proxy --port 8787`
- `headroom wrap` launches a supported coding agent through the proxy; `headroom unwrap` reverts it
- MCP server with compress, retrieve and stats tools
- Separate compressors for JSON, source code and prose
- Local cache of originals that the model can retrieve on demand
- `headroom learn` writes corrections from failed sessions into agent instruction files
- `headroom doctor` health check and a live savings dashboard
Who it's for
- Developers running coding agents such as Claude Code, Codex or Aider who hit context or token limits
- Teams building LLM apps with large tool outputs, logs or RAG results
- Python or TypeScript developers who want to call compression inline before an API request
Strengths
- Compression happens locally; the README says prompt and file content is not sent elsewhere to be compressed
- Several entry points (library, proxy, agent wrapper, MCP server) cover most setups
- Originals are kept, so the model can fetch the full text when needed
- Apache 2.0 licence and frequent releases (15 in the last 90 days)
Limitations
- Anonymous telemetry is on by default; turn it off with `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1` or `--offline`
- The README says short exchanges, prose and already dense content see little or no reduction
- `headroom wrap` also installs the Serena MCP server unless you pass `--code-memory none`
- The npm package has no CLI, and the TypeScript SDK depends on the Python proxy running
Getting started
The Python package includes the headroom command; the npm package is only the TypeScript SDK and talks to a running Headroom proxy. A Docker image is also published.
uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
npm install headroom-ai
docker pull ghcr.io/headroomlabs-ai/headroom:latest
Requirements: Python 3.10 or newer (the uv install pins 3.13); the TypeScript SDK needs a running Headroom proxy; an account with your own LLM provider.
Always follow the official instructions in the README on GitHub. This overview is our summary, not a copy.
Sources
- headroomlabs-ai/headroomRepositoryPrimarygithub.com
- Introduction | HeadroomOfficial sitePrimarydocs.headroomlabs.ai
- docs.headroomlabs.ai/docs/quickstartOfficial docsPrimary
Alternatives to headroom
codebase-memory-mcp is an MCP server, written in C, that parses a code repository into a knowledge graph so an AI coding agent can ask structural questions (what calls this function, which HTTP routes exist, what a change affects) instead of reading files one by one. It ships as one native executable for macOS, Linux and Windows. Parsing uses tree-sitter grammars compiled into the binary, and the README lists 162 languages. A hybrid LSP layer adds type resolution for a smaller set, including Python, TypeScript, Go, Java and Rust. Agents reach the graph through 17 MCP tools covering search, call tracing, architecture overviews, change detection, Cypher queries and architecture decision records. A 3D graph viewer is built into the binary and opens at localhost:9749. The installer finds supported agents on your machine and writes their MCP configuration; the README counts 45 client surfaces, among them Claude Code, Codex, Gemini CLI, Cursor and Windsurf. The authors describe the design in an arXiv preprint and report 83% answer quality with 10 times fewer tokens than file-by-file exploration across 31 repositories. Indexing and queries run locally without an API key.
- Stars
- 46K
- Language
- C
- License
- MIT
- Momentum
- +1.6% 7dEstablished
Caveman is a skill plus a local proxy that reduce the tokens a coding agent spends, both in what it writes back and in what it reads. The skill changes the reply style: answer first, one idea per sentence, no greeting or recap. Code, commands, file paths, error messages and numbers are kept character for character, and your own prompts are never rewritten. There are three levels (/caveman, /ultracave and /megacave, the last one in classical Chinese) and extra commands for one-line commit messages, terse code review and shrinking memory files such as CLAUDE.md. The second part is the caveman CLI, which runs on your machine and compresses bulky input before the agent sees it: logs, CSV, YAML, JSON and test output. Originals stay on disk so the agent can pull them back. The CLI also has caveman browse for compact web pages and caveman learn, which ranks where tokens went in past sessions. Separate TypeScript and Python middleware packages apply the same compression to agents built on the Vercel AI SDK, LangChain, OpenAI or Anthropic calls. The project's own benchmark reports 33.2% fewer input tokens over 54 Claude Code runs, with 18 of 18 answers correct. The same table shows HTML sessions getting 9.9% worse, because HTML has no compressor yet.
- Stars
- 111K
- Language
- Go
- License
- Apache-2.0
- Momentum
- +1.6% 7dEstablished
OmO (the repository is oh-my-openagent) is a terminal agent for coding and other work, started with a single omo command. It runs on senpi, the author's fork of the pi coding agent, with extra features built in. You open a project, run omo and describe the job. Adding the keyword ultrawork (or ulw) to a prompt tells the agent to read the codebase first, plan, check each step and verify the result before it stops. Typing mass ulw splits a large job into a graph of agents that run in parallel, each on a model picked for its part. A memory feature called Kibitzer keeps notes as markdown files in a git repository and has a cheaper model warn the main agent before it repeats an earlier mistake. The /login command signs in with Claude, ChatGPT, Kimi and GLM subscriptions. OmO installs as a native binary through a shell script (PowerShell on Windows) or as the omo-ai package from npm or Bun. People on the older OpenCode edition can carry their settings over with omo setup. GitHub lists the licence as "Other"; the repository's LICENSE.md is the Sustainable Use License.
- Stars
- 70K
- Language
- TypeScript
- Momentum
- +0.3% 7dEstablished
RTK (Rust Token Killer) is a command-line proxy that trims the terminal output of common developer commands before an AI coding agent reads it, so less of the agent's context fills up with noise. It ships as one Rust binary. When an agent runs something like git status, a hook installed by rtk init swaps it for rtk git status, which returns a compact version: failing tests only, grouped lint errors, one-line git confirmations, shortened directory trees. The README lists filters for git, the GitHub CLI, test runners such as pytest, Jest and cargo test, linters, package managers, Docker, kubectl, AWS and Pulumi, and claims more than 100 supported commands with under 10 ms of added time. When a command fails, RTK keeps the full unfiltered output so the agent can fetch it with rtk recall instead of running the command again. The project is careful about its own numbers. It says it cuts up to 90% of the bash output an agent reads, and states plainly that this does not mean a 90% smaller bill, since shell output is only part of the input tokens. Token counts in rtk gain are estimated as bytes divided by four because RTK has no tokenizer.
- Stars
- 83K
- Language
- Rust
- License
- Apache-2.0
- Momentum
- +1.0% 7dEstablished
Understand Anything turns a codebase or supported knowledge base into an interactive knowledge graph for exploring files, functions, classes, dependencies, and relationships. Its code analysis combines Tree-sitter structural parsing with LLM-generated summaries, tags, architectural layers, tours, and business-domain information. The dashboard lets you search the graph, inspect nodes, follow relationships, and view code organized by architectural layer. The main /understand workflow creates .ua/knowledge-graph.json, with older projects continuing to use .understand-anything/. Later runs are incremental by default and re-analyze changed files. Separate commands cover change-impact analysis, explanations of specific code, onboarding guides, domain graphs, and Karpathy-pattern wiki analysis. The project supports Claude Code and a range of other coding agents and IDE integrations. Generated graph data can be committed to a repository and opened by teammates with the standalone viewer. That viewer needs Node.js 18 or newer and reads the graph from local disk without LLM calls. Building or running the analysis code from source requires Node.js 22 or newer and pnpm 10 or newer.
- Stars
- 86K
- Language
- TypeScript
- License
- MIT
- Momentum
- +1.1% 7dEstablished
Orca is a desktop development environment for running multiple AI coding agents side by side, with each task isolated in its own Git worktree. It can launch agents such as Claude Code, Codex, Cursor CLI and OpenCode, while keeping terminals, files, diffs and browser sessions tied to each worktree. The project is aimed at developers who already use coding-agent command-line tools and want one place to manage several sessions. Orca runs on macOS, Windows and Linux. Worktrees can run locally, on SSH machines or on a remote Orca server that you control. Its built-in browser includes a Design Mode that can send an element's HTML, CSS and screenshot to an agent. The CLI can create worktrees, control terminals, open files and diffs, and automate Orca's browser. A mobile companion for iOS and Android can monitor sessions, send replies, inspect files and source control, and receive completion notifications. Orca does not provide an AI model or hosted compute. You bring the coding-agent accounts or subscriptions you already use, and remote execution uses machines or cloud accounts under your control.
- Stars
- 91K
- Language
- TypeScript
- License
- MIT
- Momentum
- +7.8% 7dEstablished