mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
docs(readme): redesign with lean-ctx-style crispness
- ASCII block logo replaces plain # heading - Power-stats line + nav links above the fold - Time-boxed section headings (30s / 60s) - What-it-does bullets pruned to one clause each - Agent table notes trimmed to ≤5 words with ● markers - Pipeline internals + provider slices moved to collapsed <details> - New When-to-use / When-to-skip section - GIFs centered via HTML with captions - Integrations and What's-inside remain collapsed <details>
This commit is contained in:
chopratejas
parent
3432ee3a96
commit
0f6df1fef0
2 changed files with 149 additions and 427 deletions
318
README.md
318
README.md
|
|
@ -1,93 +1,54 @@
|
|||
<div align="center">
|
||||
```
|
||||
██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗
|
||||
██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
|
||||
███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║
|
||||
██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║
|
||||
██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
|
||||
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝
|
||||
The context compression layer for AI agents
|
||||
```
|
||||
|
||||
# Headroom
|
||||
<p align="center"><strong>60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible</strong></p>
|
||||
|
||||
**Compress everything your AI agent reads. Same answers, fraction of the tokens.**
|
||||
<p align="center">
|
||||
<a href="https://github.com/chopratejas/headroom/actions/workflows/ci.yml"><img src="https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
||||
<a href="https://app.codecov.io/gh/chopratejas/headroom"><img src="https://codecov.io/gh/chopratejas/headroom/graph/badge.svg" alt="codecov"></a>
|
||||
<a href="https://pypi.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg" alt="PyPI"></a>
|
||||
<a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg" alt="npm"></a>
|
||||
<a href="https://huggingface.co/chopratejas/kompress-base"><img src="https://img.shields.io/badge/model-Kompress--base-yellow.svg" alt="Model: Kompress-base"></a>
|
||||
<a href="https://headroomlabs.ai/dashboard"><img src="https://img.shields.io/badge/tokens%20saved-60B%2B-2ea44f" alt="Tokens saved: 60B+"></a>
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
|
||||
<a href="https://headroom-docs.vercel.app/docs"><img src="https://img.shields.io/badge/docs-online-blue.svg" alt="Docs"></a>
|
||||
</p>
|
||||
|
||||
[](https://github.com/chopratejas/headroom/actions/workflows/ci.yml)
|
||||
[](https://app.codecov.io/gh/chopratejas/headroom)
|
||||
[](https://pypi.org/project/headroom-ai/)
|
||||
[](https://www.npmjs.com/package/headroom-ai)
|
||||
[](https://huggingface.co/chopratejas/kompress-base)
|
||||
[](https://headroomlabs.ai/dashboard)
|
||||
[](LICENSE)
|
||||
[](https://headroom-docs.vercel.app/docs)
|
||||
|
||||
<img src="HeadroomDemo-Fast.gif" alt="Headroom in action" width="820">
|
||||
|
||||
</div>
|
||||
<p align="center">
|
||||
<a href="https://headroom-docs.vercel.app/docs">Docs</a> ·
|
||||
<a href="#get-started-60-seconds">Install</a> ·
|
||||
<a href="#proof">Proof</a> ·
|
||||
<a href="#agent-compatibility-matrix">Agents</a> ·
|
||||
<a href="https://discord.gg/yRmaUNpsPJ">Discord</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
Every tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — **losslessly, locally, and without touching accuracy.**
|
||||
> Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.
|
||||
|
||||
> **100 logs. One FATAL error buried at position 67. Both runs found it.**
|
||||
> Baseline **10,144 tokens** → Headroom **1,260 tokens** — **87% fewer, identical answer.**
|
||||
> `python examples/needle_in_haystack_test.py`
|
||||
<p align="center">
|
||||
<img src="HeadroomDemo-Fast.gif" alt="Headroom in action" width="820">
|
||||
<br/><sub>Live: 10,144 → 1,260 tokens — same FATAL found.</sub>
|
||||
</p>
|
||||
|
||||
---
|
||||
## What it does
|
||||
|
||||
## Quick start
|
||||
- **Library** — `compress(messages)` in Python or TypeScript, inline in any app
|
||||
- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language
|
||||
- **Agent wrap** — `headroom wrap claude|codex|cursor|aider|copilot` in one command
|
||||
- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client
|
||||
- **Cross-agent memory** — shared store across Claude, Codex, Gemini, auto-dedup
|
||||
- **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md`
|
||||
- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand
|
||||
|
||||
Works with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.
|
||||
|
||||
**Wrap your coding agent — one command:**
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[all]"
|
||||
|
||||
headroom wrap claude # Claude Code
|
||||
headroom wrap codex # Codex
|
||||
headroom wrap cursor # Cursor
|
||||
headroom wrap aider # Aider
|
||||
headroom wrap copilot # GitHub Copilot CLI
|
||||
```
|
||||
|
||||
Using `pipx`? Current release wheels are built for Python 3.10 through 3.13, so
|
||||
choose a supported interpreter explicitly:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]"
|
||||
```
|
||||
|
||||
**Drop it into your own code — Python or TypeScript:**
|
||||
|
||||
```python
|
||||
from headroom import compress
|
||||
|
||||
result = compress(messages, model="claude-sonnet-4-5")
|
||||
response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages)
|
||||
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { compress } from 'headroom-ai';
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
```
|
||||
|
||||
**Or run it as a proxy — zero code changes, any language:**
|
||||
|
||||
```bash
|
||||
headroom proxy --port 8787
|
||||
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
|
||||
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Headroom
|
||||
|
||||
- **Accuracy-preserving.** GSM8K **0.870 → 0.870** (±0.000). TruthfulQA **+0.030**. SQuAD v2 and BFCL both **97%** accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.
|
||||
- **Runs on your machine.** No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.
|
||||
- **[Kompress-base](https://huggingface.co/chopratejas/kompress-base) on HuggingFace.** Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with `pip install "headroom-ai[ml]"`.
|
||||
- **Cross-agent memory and learning.** Claude Code saves a fact, Codex reads it back. `headroom learn` mines failed sessions and writes corrections straight to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — reliability compounds over time.
|
||||
- **Reversible (CCR).** Compression is not deletion. The model can always call `headroom_retrieve` to pull the original bytes. Nothing is thrown away.
|
||||
|
||||
Bundles managed [RTK](https://github.com/rtk-ai/rtk) and [lean-ctx](https://github.com/yvgude/lean-ctx) binaries for local CLI context filtering — full [attribution below](#compared-to).
|
||||
|
||||
---
|
||||
|
||||
## How it fits
|
||||
## How it works (30 seconds)
|
||||
|
||||
```
|
||||
Your agent / app
|
||||
|
|
@ -109,28 +70,30 @@ Bundles managed [RTK](https://github.com/rtk-ai/rtk) and [lean-ctx](https://gith
|
|||
LLM provider (Anthropic · OpenAI · Bedrock · …)
|
||||
```
|
||||
|
||||
- **ContentRouter** — detects content type, selects the right compressor
|
||||
- **SmartCrusher / CodeCompressor / Kompress-base** — compress JSON, AST, or prose
|
||||
- **CacheAligner** — stabilizes prefixes so provider KV caches actually hit
|
||||
- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them
|
||||
|
||||
→ [Architecture](https://headroom-docs.vercel.app/docs/architecture) · [CCR reversible compression](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-base model card](https://huggingface.co/chopratejas/kompress-base)
|
||||
|
||||
### Canonical pipeline lifecycle
|
||||
## Get started (60 seconds)
|
||||
|
||||
Headroom now exposes one stable request lifecycle across `compress()`, the SDK, and the proxy:
|
||||
```bash
|
||||
# 1 — Install
|
||||
pip install "headroom-ai[all]" # Python
|
||||
npm install headroom-ai # Node / TypeScript
|
||||
|
||||
`Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received`
|
||||
# 2 — Pick your mode
|
||||
headroom wrap claude # wrap a coding agent
|
||||
headroom proxy --port 8787 # drop-in proxy, zero code changes
|
||||
# or: from headroom import compress # inline library
|
||||
|
||||
- **Transforms** still do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
|
||||
- **Pipeline extensions** observe or customize those lifecycle stages via `on_pipeline_event(...)`.
|
||||
- **Compression hooks** still work and now sit alongside the canonical lifecycle instead of being the only extension seam.
|
||||
- **Proxy extensions** remain the server/app integration seam for ASGI middleware, routes, and startup policy.
|
||||
# 3 — See the savings
|
||||
headroom stats
|
||||
```
|
||||
|
||||
### Provider slices
|
||||
|
||||
Provider and tool-specific behavior is being moved behind dedicated modules under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.
|
||||
|
||||
- **CLI/tool slices**: `headroom/providers/claude`, `copilot`, `codex`, `openclaw`
|
||||
- **Provider runtime slices**: `headroom/providers/claude`, `gemini`, plus shared backend/runtime dispatch in `headroom/providers/registry.py`
|
||||
- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli/proxy.py`, and `proxy/server.py` now delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch instead of inlining those rules.
|
||||
|
||||
---
|
||||
Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.
|
||||
|
||||
## Proof
|
||||
|
||||
|
|
@ -145,69 +108,62 @@ Provider and tool-specific behavior is being moved behind dedicated modules unde
|
|||
|
||||
**Accuracy preserved on standard benchmarks:**
|
||||
|
||||
| Benchmark | Category | N | Baseline | Headroom | Delta |
|
||||
|------------|----------|----:|---------:|---------:|----------:|
|
||||
| GSM8K | Math | 100 | 0.870 | 0.870 | **±0.000**|
|
||||
| TruthfulQA | Factual | 100 | 0.530 | 0.560 | **+0.030**|
|
||||
| Benchmark | Category | N | Baseline | Headroom | Delta |
|
||||
|------------|----------|----:|---------:|---------:|------------|
|
||||
| GSM8K | Math | 100 | 0.870 | 0.870 | **±0.000** |
|
||||
| TruthfulQA | Factual | 100 | 0.530 | 0.560 | **+0.030** |
|
||||
| SQuAD v2 | QA | 100 | — | **97%** | 19% compression |
|
||||
| BFCL | Tools | 100 | — | **97%** | 32% compression |
|
||||
|
||||
Reproduce:
|
||||
Reproduce: `python -m headroom.evals suite --tier 1` · [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)
|
||||
|
||||
```bash
|
||||
python -m headroom.evals suite --tier 1
|
||||
```
|
||||
|
||||
**Community, live:**
|
||||
|
||||
<div align="center">
|
||||
<p align="center">
|
||||
<a href="https://headroomlabs.ai/dashboard">
|
||||
<img src="headroom-savings.png" alt="60B+ tokens saved — community leaderboard" width="820">
|
||||
</a>
|
||||
<p><b><a href="https://headroomlabs.ai/dashboard">60B+ tokens saved by the community in the last 20 days — live leaderboard →</a></b></p>
|
||||
</div>
|
||||
<br/><b><a href="https://headroomlabs.ai/dashboard">60B+ tokens saved by the community — live leaderboard →</a></b>
|
||||
</p>
|
||||
|
||||
→ [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)
|
||||
## Agent compatibility matrix
|
||||
|
||||
---
|
||||
| Agent | `headroom wrap` | Notes |
|
||||
|-------------|:---------------:|----------------------------------|
|
||||
| Claude Code | ● | `--memory` · `--code-graph` |
|
||||
| Codex | ● | shares memory with Claude |
|
||||
| Cursor | ● | prints config — paste once |
|
||||
| Aider | ● | starts proxy + launches |
|
||||
| Copilot CLI | ● | starts proxy + launches |
|
||||
| OpenClaw | ● | installs as ContextEngine plugin |
|
||||
|
||||
## Built for coding agents
|
||||
Any OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.
|
||||
|
||||
| Agent | One-command wrap | Notes |
|
||||
|--------------------|------------------------------------|------------------------------------------------------------------|
|
||||
| **Claude Code** | `headroom wrap claude` | `--memory` for cross-agent memory, `--code-graph` for codebase intel |
|
||||
| **Codex** | `headroom wrap codex --memory` | Shares the same memory store as Claude |
|
||||
| **Cursor** | `headroom wrap cursor` | Prints Cursor config — paste once, done |
|
||||
| **Aider** | `headroom wrap aider` | Starts proxy, launches Aider |
|
||||
| **Copilot CLI** | `headroom wrap copilot` | Starts proxy, launches Copilot |
|
||||
| **OpenClaw** | `headroom wrap openclaw` | Installs Headroom as ContextEngine plugin |
|
||||
## When to use · When to skip
|
||||
|
||||
MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client.
|
||||
**Great fit if you…**
|
||||
- run AI coding agents daily and want savings without changing your code
|
||||
- work across multiple agents and want shared memory
|
||||
- need reversible compression — originals always retrievable via CCR
|
||||
|
||||
<div align="center">
|
||||
<img src="headroom_learn.gif" alt="headroom learn in action" width="720">
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Integrations
|
||||
**Skip it if you…**
|
||||
- only use a single provider's native compaction and don't need cross-agent memory
|
||||
- work in a sandboxed environment where local processes can't run
|
||||
|
||||
<details>
|
||||
<summary><b>Drop Headroom into any stack</b></summary>
|
||||
<summary><b>Integrations — drop Headroom into any stack</b></summary>
|
||||
|
||||
| Your setup | Hook in with |
|
||||
|-------------------------|------------------------------------------------------------------|
|
||||
| Any Python app | `compress(messages, model=…)` |
|
||||
| Any TypeScript app | `await compress(messages, { model })` |
|
||||
| Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
|
||||
| Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
|
||||
| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
|
||||
| LangChain | `HeadroomChatModel(your_llm)` |
|
||||
| Agno | `HeadroomAgnoModel(your_model)` |
|
||||
| Strands | [Strands guide](https://headroom-docs.vercel.app/docs/strands) |
|
||||
| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
|
||||
| Multi-agent | `SharedContext().put / .get` |
|
||||
| MCP clients | `headroom mcp install` |
|
||||
| Your setup | Hook in with |
|
||||
|------------------------|------------------------------------------------------------------|
|
||||
| Any Python app | `compress(messages, model=…)` |
|
||||
| Any TypeScript app | `await compress(messages, { model })` |
|
||||
| Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
|
||||
| Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
|
||||
| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
|
||||
| LangChain | `HeadroomChatModel(your_llm)` |
|
||||
| Agno | `HeadroomAgnoModel(your_model)` |
|
||||
| Strands | [Strands guide](https://headroom-docs.vercel.app/docs/strands) |
|
||||
| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
|
||||
| Multi-agent | `SharedContext().put / .get` |
|
||||
| MCP clients | `headroom mcp install` |
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -227,50 +183,76 @@ MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom
|
|||
|
||||
</details>
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary><b>Pipeline internals</b></summary>
|
||||
|
||||
Headroom exposes one stable request lifecycle across `compress()`, the SDK, and the proxy:
|
||||
|
||||
`Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received`
|
||||
|
||||
- **Transforms** do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
|
||||
- **Pipeline extensions** observe or customize lifecycle stages via `on_pipeline_event(...)`.
|
||||
- **Compression hooks** sit alongside the canonical lifecycle as an additional extension seam.
|
||||
- **Proxy extensions** remain the server/app integration seam for ASGI middleware, routes, and startup policy.
|
||||
|
||||
Provider and tool-specific behavior lives under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.
|
||||
|
||||
- **CLI/tool slices**: `headroom/providers/claude`, `copilot`, `codex`, `openclaw`
|
||||
- **Provider runtime slices**: `headroom/providers/claude`, `gemini`, plus shared backend/runtime dispatch in `headroom/providers/registry.py`
|
||||
- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli/proxy.py`, and `proxy/server.py` delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.
|
||||
|
||||
</details>
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[all]" # Python, everything
|
||||
npm install headroom-ai # TypeScript / Node
|
||||
npm install headroom-ai # TypeScript / Node
|
||||
docker pull ghcr.io/chopratejas/headroom:latest
|
||||
```
|
||||
|
||||
Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.
|
||||
|
||||
Using `pipx`? Choose a supported interpreter explicitly:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]"
|
||||
```
|
||||
|
||||
→ [Installation guide](https://headroom-docs.vercel.app/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
|
||||
|
||||
---
|
||||
## headroom learn
|
||||
|
||||
<p align="center">
|
||||
<img src="headroom_learn.gif" alt="headroom learn in action" width="720">
|
||||
</p>
|
||||
|
||||
`headroom learn` — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`.
|
||||
|
||||
## Documentation
|
||||
|
||||
| Start here | Go deeper |
|
||||
|-------------------------------------------------------------------------|------------------------------------------------------------------------|
|
||||
| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart) | [Architecture](https://headroom-docs.vercel.app/docs/architecture) |
|
||||
| [Proxy](https://headroom-docs.vercel.app/docs/proxy) | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |
|
||||
| [MCP tools](https://headroom-docs.vercel.app/docs/mcp) | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr) |
|
||||
| [Memory](https://headroom-docs.vercel.app/docs/memory) | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization) |
|
||||
| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning) | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks) |
|
||||
| [Configuration](https://headroom-docs.vercel.app/docs/configuration) | [Limitations](https://headroom-docs.vercel.app/docs/limitations) |
|
||||
|
||||
---
|
||||
| Start here | Go deeper |
|
||||
|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
|
||||
| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart) | [Architecture](https://headroom-docs.vercel.app/docs/architecture) |
|
||||
| [Proxy](https://headroom-docs.vercel.app/docs/proxy) | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |
|
||||
| [MCP tools](https://headroom-docs.vercel.app/docs/mcp) | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr) |
|
||||
| [Memory](https://headroom-docs.vercel.app/docs/memory) | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization) |
|
||||
| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning) | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks) |
|
||||
| [Configuration](https://headroom-docs.vercel.app/docs/configuration) | [Limitations](https://headroom-docs.vercel.app/docs/limitations) |
|
||||
|
||||
## Compared to
|
||||
|
||||
Headroom runs **locally**, covers **every** content type (not just CLI or text), works with every major framework, and is **reversible**.
|
||||
Headroom runs **locally**, covers **every** content type, works with every major framework, and is **reversible**.
|
||||
|
||||
| | Scope | Deploy | Local | Reversible |
|
||||
|----------------------------------|-------------------------------------------------|-------------------------------------|:-----:|:----------:|
|
||||
| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
|
||||
| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |
|
||||
| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No |
|
||||
| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
|
||||
| OpenAI Compaction | Conversation history | Provider-native | No | No |
|
||||
| | Scope | Deploy | Local | Reversible |
|
||||
|------------------------------------------------------------------------------|------------------------------------------------|------------------------------------|:-----:|:----------:|
|
||||
| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
|
||||
| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |
|
||||
| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No |
|
||||
| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
|
||||
| OpenAI Compaction | Conversation history | Provider-native | No | No |
|
||||
|
||||
> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.
|
||||
|
||||
---
|
||||
> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show --short`, scoped `ls`, summarized installers. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -281,8 +263,6 @@ pip install -e ".[dev]" && pytest
|
|||
|
||||
Devcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant & Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
- **[Live leaderboard](https://headroomlabs.ai/dashboard)** — 60B+ tokens saved and counting.
|
||||
|
|
|
|||
|
|
@ -1,258 +0,0 @@
|
|||
# README Redesign — Design Spec
|
||||
|
||||
**Date:** 2026-05-11
|
||||
**Status:** Approved
|
||||
**Reference:** [lean-ctx README](https://github.com/yvgude/lean-ctx) — structural and visual inspiration
|
||||
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Redesign `README.md` to match the crispness and scannability of lean-ctx's README while
|
||||
foregrounding what makes Headroom distinct: library + proxy + MCP (not CLI-only), reversible
|
||||
compression (CCR), and cross-agent memory.
|
||||
|
||||
---
|
||||
|
||||
## Structure (ordered)
|
||||
|
||||
### 1. ASCII block logo
|
||||
|
||||
Six-row block-letter HEADROOM (same double-width box-drawing style as lean-ctx):
|
||||
|
||||
```
|
||||
██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗
|
||||
██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
|
||||
███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║
|
||||
██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║
|
||||
██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
|
||||
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝
|
||||
The context compression layer for AI agents
|
||||
```
|
||||
|
||||
Tagline on line 7, centered, plain text (no `<h3>`).
|
||||
|
||||
### 2. Power-stats line (centered `<p>`)
|
||||
|
||||
```
|
||||
60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible
|
||||
```
|
||||
|
||||
### 3. Badge row (centered `<p>`)
|
||||
|
||||
Keep current badges in current order:
|
||||
CI · codecov · PyPI · npm · Kompress-base model · Tokens saved · License · Docs
|
||||
|
||||
### 4. Nav links (centered `<p>`)
|
||||
|
||||
```
|
||||
Docs · Install · Proof · Agents · Discord
|
||||
```
|
||||
|
||||
Anchor-linked to section IDs in the document:
|
||||
- **Docs** → `#documentation`
|
||||
- **Install** → `#get-started-60-seconds`
|
||||
- **Proof** → `#proof`
|
||||
- **Agents** → `#agent-compatibility-matrix`
|
||||
- **Discord** → external Discord URL
|
||||
|
||||
---
|
||||
|
||||
### 5. Horizontal rule + blockquote elevator pitch
|
||||
|
||||
```
|
||||
> Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks,
|
||||
> files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.
|
||||
```
|
||||
|
||||
Immediately followed by the existing `HeadroomDemo-Fast.gif`, centered using raw HTML:
|
||||
|
||||
```html
|
||||
<p align="center">
|
||||
<img src="HeadroomDemo-Fast.gif" alt="Headroom in action" width="820">
|
||||
<br/><sub>Live: 10,144 → 1,260 tokens — same FATAL found.</sub>
|
||||
</p>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. What it does
|
||||
|
||||
Seven bullets, one clause each. No prose paragraphs.
|
||||
|
||||
- **Library** — `compress(messages)` in Python or TypeScript, inline in any app
|
||||
- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language
|
||||
- **Agent wrap** — `headroom wrap claude|codex|cursor|aider|copilot` in one command
|
||||
- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client
|
||||
- **Cross-agent memory** — shared store across Claude, Codex, Gemini, auto-dedup
|
||||
- **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md`
|
||||
- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand
|
||||
|
||||
---
|
||||
|
||||
### 7. How it works (30 seconds)
|
||||
|
||||
Keep the existing ASCII pipeline diagram verbatim. Replace all prose beneath it with exactly
|
||||
four tight bullets (no more than one clause each), mirroring lean-ctx's pattern:
|
||||
|
||||
- **ContentRouter** — detects content type, selects the right compressor
|
||||
- **SmartCrusher / CodeCompressor / Kompress-base** — compress JSON, AST, or prose
|
||||
- **CacheAligner** — stabilizes prefixes so provider KV caches actually hit
|
||||
- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them
|
||||
|
||||
Drop the "Canonical pipeline lifecycle" paragraphs and "Provider slices" paragraphs from main
|
||||
body — they move to `<details>` (see Section 12).
|
||||
|
||||
---
|
||||
|
||||
### 8. Get started (60 seconds)
|
||||
|
||||
Three numbered steps, bash only — no prose in between:
|
||||
|
||||
```bash
|
||||
# 1 — Install
|
||||
pip install "headroom-ai[all]" # Python
|
||||
npm install headroom-ai # Node / TypeScript
|
||||
|
||||
# 2 — Pick your mode
|
||||
headroom wrap claude # wrap a coding agent
|
||||
headroom proxy --port 8787 # drop-in proxy, zero code changes
|
||||
# or: from headroom import compress # inline library
|
||||
|
||||
# 3 — See the savings
|
||||
headroom stats
|
||||
```
|
||||
|
||||
One-liner extras note below the block:
|
||||
`Granular extras: [proxy], [mcp], [ml], [agno], [langchain], [evals]. Requires Python 3.10+`
|
||||
|
||||
---
|
||||
|
||||
### 9. Proof
|
||||
|
||||
Keep both existing tables verbatim (workloads savings + accuracy benchmarks).
|
||||
Keep `headroom-savings.png` with the leaderboard link.
|
||||
Keep the reproduce snippet: `python -m headroom.evals suite --tier 1`
|
||||
|
||||
---
|
||||
|
||||
### 10. Agent compatibility matrix
|
||||
|
||||
Replace the current verbose "Notes" column with ≤5-word entries. Add a `●` column for wrap support.
|
||||
|
||||
| Agent | `headroom wrap` | Notes |
|
||||
|---|:---:|---|
|
||||
| Claude Code | ● | `--memory` · `--code-graph` |
|
||||
| Codex | ● | shares memory with Claude |
|
||||
| Cursor | ● | prints config — paste once |
|
||||
| Aider | ● | starts proxy + launches |
|
||||
| Copilot CLI | ● | starts proxy + launches |
|
||||
| OpenClaw | ● | installs as ContextEngine plugin |
|
||||
|
||||
Footer note: *Any OpenAI-compatible client works via `headroom proxy`.*
|
||||
|
||||
---
|
||||
|
||||
### 11. When to use · When to skip *(new section)*
|
||||
|
||||
**Great fit if you…**
|
||||
- run AI coding agents daily and want savings without changing your code
|
||||
- work across multiple agents and want shared memory
|
||||
- need reversible compression — originals always retrievable via CCR
|
||||
|
||||
**Skip it if you…**
|
||||
- only use a single provider's native compaction and don't need cross-agent memory
|
||||
- work in a sandboxed environment where local processes can't run
|
||||
|
||||
---
|
||||
|
||||
### 12. Three `<details>` blocks
|
||||
|
||||
Each collapsed by default. Exact `<summary>` labels specified below.
|
||||
|
||||
**a. `<summary><b>Integrations — drop Headroom into any stack</b></summary>`**
|
||||
Copy the current `<details>` block with heading "Drop Headroom into any stack" (lines ~196–213 of current README) verbatim — the integrations table is already inside a `<details>` today.
|
||||
|
||||
**b. `<summary><b>What's inside</b></summary>`**
|
||||
Copy the current `<details>` block with heading "What's inside" (lines ~215–228 of current README) verbatim — SmartCrusher, CodeCompressor, Kompress-base, image compression, CacheAligner, IntelligentContext, CCR, cross-agent memory, SharedContext, `headroom learn`.
|
||||
|
||||
**c. `<summary><b>Pipeline internals</b></summary>`**
|
||||
Move the "Canonical pipeline lifecycle" section (lines ~107–135 of current README, beginning "Headroom now exposes one stable request lifecycle…") and the "Provider slices" section (lines ~137–148, beginning "Provider and tool-specific behavior…") here. Content unchanged — just relocated out of the main body.
|
||||
|
||||
---
|
||||
|
||||
### 13. Install
|
||||
|
||||
Keep current `pip` / `npm` / `docker` block verbatim.
|
||||
Keep extras and Python version note.
|
||||
**Note:** Both §8 (quick-start 60-second block) and §13 (full install matrix with docker + extras) are intentional and survive. §8 is the happy path; §13 is the complete reference.
|
||||
|
||||
---
|
||||
|
||||
### 14. headroom learn
|
||||
|
||||
Keep `headroom_learn.gif` in a slim subsection **immediately before Section 15 (Docs)**,
|
||||
under a `## headroom learn` heading. Centered using raw HTML:
|
||||
|
||||
```html
|
||||
<p align="center">
|
||||
<img src="headroom_learn.gif" alt="headroom learn in action" width="720">
|
||||
</p>
|
||||
```
|
||||
|
||||
One-sentence caption below: *"headroom learn — mines failed sessions, writes corrections to CLAUDE.md / AGENTS.md"*
|
||||
|
||||
---
|
||||
|
||||
### 15. Documentation
|
||||
|
||||
Keep current two-column doc links table verbatim.
|
||||
|
||||
---
|
||||
|
||||
### 16. Compared to
|
||||
|
||||
Keep current comparison table verbatim.
|
||||
Keep attribution paragraph for RTK and lean-ctx.
|
||||
|
||||
---
|
||||
|
||||
### 17. Contributing · Community · License
|
||||
|
||||
Contributing bash block unchanged.
|
||||
Community bullet list (leaderboard, Discord, Kompress-base) unchanged.
|
||||
License line unchanged.
|
||||
|
||||
---
|
||||
|
||||
## What changes vs. today
|
||||
|
||||
| Area | Before | After |
|
||||
|---|---|---|
|
||||
| Logo | Plain `# Headroom` | ASCII block logo (6 rows) |
|
||||
| Tagline | 2-sentence paragraph | 1-line centered, below logo |
|
||||
| Power stats | None | Centered line below tagline |
|
||||
| Nav links | None | `Docs · Install · Proof · Agents · Discord` |
|
||||
| Section headings | Flat prose | Time-boxed where helpful |
|
||||
| Agent notes | 15–20 word sentences | ≤5 words |
|
||||
| Pipeline/provider | In main body (~80 lines) | Collapsed `<details>` |
|
||||
| "When to skip" | Missing | Added |
|
||||
| GIF placement | Inline, no caption | Centered with token-count caption |
|
||||
|
||||
## What does NOT change
|
||||
|
||||
- All benchmark numbers and tables
|
||||
- All code snippets
|
||||
- All existing GIFs (HeadroomDemo-Fast.gif, headroom_learn.gif, headroom-savings.png)
|
||||
- Attribution paragraph for RTK and lean-ctx
|
||||
- Docs links
|
||||
- Contributing / Community / License
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No new GIFs or screenshots
|
||||
- No 3-column demo table (no 3 separate GIFs available)
|
||||
- No rewrite of benchmark methodology
|
||||
- No changes to docs site
|
||||
Loading…
Add table
Add a link
Reference in a new issue