From 0f6df1fef09ffcfcf5c41d220a2b240ea9943f7c Mon Sep 17 00:00:00 2001 From: chopratejas Date: Mon, 11 May 2026 22:33:03 -0700 Subject: [PATCH] docs(readme): redesign with lean-ctx-style crispness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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
- New When-to-use / When-to-skip section - GIFs centered via HTML with captions - Integrations and What's-inside remain collapsed
--- README.md | 318 ++++++++---------- .../2026-05-11-readme-redesign-design.md | 258 -------------- 2 files changed, 149 insertions(+), 427 deletions(-) delete mode 100644 docs/superpowers/specs/2026-05-11-readme-redesign-design.md diff --git a/README.md b/README.md index a00bafb23..7757d599a 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,54 @@ -
+``` + ██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ + ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ + ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ + ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ + ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ + ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ + The context compression layer for AI agents +``` -# Headroom +

60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible

-**Compress everything your AI agent reads. Same answers, fraction of the tokens.** +

+ CI + codecov + PyPI + npm + Model: Kompress-base + Tokens saved: 60B+ + License: Apache 2.0 + Docs +

-[![CI](https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg)](https://github.com/chopratejas/headroom/actions/workflows/ci.yml) -[![codecov](https://codecov.io/gh/chopratejas/headroom/graph/badge.svg)](https://app.codecov.io/gh/chopratejas/headroom) -[![PyPI](https://img.shields.io/pypi/v/headroom-ai.svg)](https://pypi.org/project/headroom-ai/) -[![npm](https://img.shields.io/npm/v/headroom-ai.svg)](https://www.npmjs.com/package/headroom-ai) -[![Model: Kompress-base](https://img.shields.io/badge/model-Kompress--base-yellow.svg)](https://huggingface.co/chopratejas/kompress-base) -[![Tokens saved: 60B+](https://img.shields.io/badge/tokens%20saved-60B%2B-2ea44f)](https://headroomlabs.ai/dashboard) -[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) -[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://headroom-docs.vercel.app/docs) - -Headroom in action - -
+

+ Docs · + Install · + Proof · + Agents · + Discord +

--- -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` +

+ Headroom in action +
Live: 10,144 → 1,260 tokens — same FATAL found. +

---- +## 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:** - -
+

60B+ tokens saved — community leaderboard -

60B+ tokens saved by the community in the last 20 days — live leaderboard →

-
+
60B+ tokens saved by the community — live leaderboard → +

-→ [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 -
- headroom learn in action -
- ---- - -## 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
-Drop Headroom into any stack +Integrations — drop Headroom into any stack -| 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` |
@@ -227,50 +183,76 @@ MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom
---- +
+Pipeline internals + +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. + +
## 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 + +

+ headroom learn in action +

+ +`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. diff --git a/docs/superpowers/specs/2026-05-11-readme-redesign-design.md b/docs/superpowers/specs/2026-05-11-readme-redesign-design.md deleted file mode 100644 index 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 `

`). - -### 2. Power-stats line (centered `

`) - -``` -60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible -``` - -### 3. Badge row (centered `

`) - -Keep current badges in current order: -CI · codecov · PyPI · npm · Kompress-base model · Tokens saved · License · Docs - -### 4. Nav links (centered `

`) - -``` -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 -

- Headroom in action -
Live: 10,144 → 1,260 tokens — same FATAL found. -

-``` - ---- - -### 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 `
` (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 `
` blocks - -Each collapsed by default. Exact `` labels specified below. - -**a. `Integrations — drop Headroom into any stack`** -Copy the current `
` block with heading "Drop Headroom into any stack" (lines ~196–213 of current README) verbatim — the integrations table is already inside a `
` today. - -**b. `What's inside`** -Copy the current `
` 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. `Pipeline internals`** -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 -

- headroom learn in action -

-``` - -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 `
` | -| "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