headroom
SHA-256Headroom compresses tool outputs, logs, RAG chunks, files, and conversation history before they reach the LLM. 60-95% fewer tokens with identical answers. Integrates as a library, proxy, MCP server, or agent wrapper.
Smart Download
Download Download Version
v0.22.4 · 15.3 MB
Compress everything your AI agent reads: 60-95% fewer tokens, same answers. Library, proxy, MCP, reversible.
Core Features
- Reversible compression (CCR): originals stored locally, LLM retrieves on demand
- 6 algorithms auto-selected: SmartCrusher (JSON), CodeCompressor (AST), Kompress-base (text), etc.
- Zero-code integration: agent wrapping (Claude Code/Codex/Cursor), inline library, transparent proxy
- Cross-agent memory: shared compressed context across Claude, Codex, Gemini, with auto-dedup
- Automated learning: mines failed sessions, writes corrections to AGENTS.md / CLAUDE.md
What It Can't Do
- •Requires Python 3.10+ and modern Node.js. Best suited for AI agent contexts; general text compression may be less dramatic. CCR needs local storage; if you can't keep files locally, disable CCR.
Use Cases
- Daily use with AI coding agents (Claude Code, Cursor, Aider) to slash API costs
- Multi-agent workflows where shared memory reduces redundant context transfer
Detailed Introduction
Headroom is a context compression layer for AI agents that reduces token usage by 60-95% while preserving answer accuracy. It compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before reaching the LLM. Unlike tools like LLMLingua or Selective Context, Headroom offers reversible compression (CCR) so originals are never lost, and cross-agent memory across Claude, Codex, Cursor, Aider, and more. It runs locally, supports 6 compression algorithms (SmartCrusher, CodeCompressor, Kompress-base, etc.), and integrates as a library, proxy, MCP server, or agent wrapper.
Tags
Getting Started
Download installer
Click the button above to download the installer for your system
Install the software
Open the downloaded dmg file, then drag the app to Applications
Install: pip install "headroom-ai[all]" or npm install headroom-ai
Choose mode: headroom wrap claude to wrap an agent, or headroom proxy --port 8787 for transparent proxy
Verify: headroom stats to see token savings
- Install: pip install "headroom-ai[all]" or npm install headroom-ai
- Choose mode: headroom wrap claude to wrap an agent, or headroom proxy --port 8787 for transparent proxy
- Verify: headroom stats to see token savings
SHA-256 checksum verified
Checksum extracted from GitHub official Release page
SHA256 Checksum
0942c5d45c6f94bb2cc7b094a323175bae262fdc3d38ab088e27aea6cc5186f3This checksum is extracted from the GitHub Release page. Verify file integrity after download.
All SHA-256 checksums on this platform are extracted from the project's official GitHub Release page, without any modification. You can independently verify them on the GitHub Releases page.
Open Source Transparency
View GitHub SourceUninstall Info
Uninstall the package: pip uninstall headroom-ai or npm uninstall headroom-ai. If you used `wrap`, remove ~/.headroom directory and any injected environment variables.
No Extra Dependencies
Ready to use after download. No additional runtime required.
Similar Projects
LocalAI
LocalAI is the open-source AI engine to run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required. Drop-in API compatibility with OpenAI, Anthropic, and ElevenLabs.
goose
Goose is a general-purpose AI agent that runs on your machine. Use it for coding, research, writing, automation, and more. It offers a native desktop app (macOS, Linux, Windows), a full CLI, and an API. Works with 15+ providers (Anthropic, OpenAI, Google, Ollama, etc.) and connects to 70+ extensions via the Model Context Protocol. Built in Rust, part of the Linux Foundation.
daily_stock_analysis
An open-source AI stock analysis system for A/H/US markets that generates daily decision dashboards and pushes them to WeChat Work, Feishu, Telegram, Discord, Slack, or email. Deploy via GitHub Actions for free.