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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs(readme): redesign with lean-ctx-style crispness
chopratejas0f6df1fef09f
diff --git a/README.md b/README.mdindex a00bafb23..7757d599a 100644--- a/README.md+++ b/README.md@@ -1,93 +1,54 @@-<div align="center">--# Headroom--**Compress everything your AI agent reads. Same answers, fraction of the tokens.**--[](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>-------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.**--> **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`-------## Quick start--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' });+ ██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗+ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║+ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║+ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║+ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║+ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝+ The context compression layer for AI agents```-**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-```+<p align="center"><strong>60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible</strong></p>++<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>++<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>----## Why Headroom+> 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.-- **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.+<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>-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).+## What it does----+- **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-## 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://githLLM provider (Anthropic · OpenAI · Bedrock · …)```-→ [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+- **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-Headroom now 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`+→ [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)-- **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.+## Get started (60 seconds)-### Provider slices+```bash+# 1 — Install+pip install "headroom-ai[all]" # Python+npm install headroom-ai # Node / TypeScript-Provider and tool-specific behavior is being moved behind dedicated modules under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.+# 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-- **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.+# 3 — See the savings+headroom stats+```----+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:--```bash-python -m headroom.evals suite --tier 1-```--**Community, live:**+Reproduce: `python -m headroom.evals suite --tier 1` · [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)-<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>--→ [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)+ <br/><b><a href="https://headroomlabs.ai/dashboard">60B+ tokens saved by the community — live leaderboard →</a></b>+</p>----+## Agent compatibility matrix-## Built for coding agents+| 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 |-| 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 |+Any OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.-MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client.--<div align="center">- <img src="headroom_learn.gif" alt="headroom learn in action" width="720">-</div>+## When to use · When to skip----+**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-## 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>--| 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` |+<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` |</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```bashpip install "headroom-ai[all]" # Python, everything-npm install headroom-ai # TypeScript / Node+npm install headroom-ai # TypeScript / Nodedocker 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-## Documentation+<p align="center">+ <img src="headroom_learn.gif" alt="headroom learn in action" width="720">+</p>-| 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) |+`headroom learn` — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`.----+## Documentation-## Compared to+| 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) |-Headroom runs **locally**, covers **every** content type (not just CLI or text), works with every major framework, and is **reversible**.+## Compared to-| | 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 |+Headroom runs **locally**, covers **every** content type, works with every major framework, and is **reversible**.-> **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 ...`.+| | 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 --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]" && pytestDevcontainers 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.diff --git a/docs/superpowers/specs/2026-05-11-readme-redesign-design.md b/docs/superpowers/specs/2026-05-11-readme-redesign-design.mddeleted file mode 100644index 38cef3928..000000000--- a/docs/superpowers/specs/2026-05-11-readme-redesign-design.md+++ /dev/null@@ -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