# Docs


- **Getting Started**
- [Introduction](/docs): Headroom is the context optimization layer for LLM applications. Compress tool outputs, DB results, file reads, and RAG results before they reach the model. Same answers, fraction of the tokens.
- [Quickstart](/docs/quickstart): Get Headroom running in 5 minutes. Install, compress, and send to your LLM with fewer tokens.
- [Installation](/docs/installation): Install Headroom via pip, npm, or Docker. Includes all Python extras, TypeScript setup, Docker image tags, and environment variables.
- [Docker-Native Install](/docs/docker-install): Run Headroom without installing Python or Node.js on the host. A native `headroom` wrapper keeps the proxy and CLI in Docker while your other tools run on the host OS.
- [Persistent Installs](/docs/persistent-installs): Install Headroom as a durable local runtime — background service, scheduled watchdog, or restartable Docker container — instead of starting it ad hoc.

- **Compression**
- [How Compression Works](/docs/how-compression-works): Understand Headroom's compression pipeline, automatic content routing, and how different content types are compressed.
- [SmartCrusher](/docs/smart-crusher): Statistical JSON and array compression that keeps important items and drops the rest.
- [Code Compression](/docs/code-compression): AST-aware compression that preserves imports, signatures, and types while compressing function bodies. Powered by tree-sitter.
- [Image Compression](/docs/image-compression): ML-powered image compression that reduces vision model token usage by 40-90% while maintaining answer accuracy.
- [Text & Log Compression](/docs/text-and-logs): Specialized compressors for search results, build logs, diffs, and general text. Each preserves what matters for its content type.

- **Reversible Compression**
- [Reversible Compression (CCR)](/docs/ccr): Compress-Cache-Retrieve architecture that makes compression lossless — the LLM can always get the original data back.

- **Cache & Context**
- [Cache Optimization](/docs/cache-optimization): Stabilize message prefixes for provider KV cache hits and configure provider-specific caching strategies.
- [Agent Orchestration](/docs/agent-orchestration): Keep repeated agent wakes cache-friendly while using CCR for lossless memory digest retrieval.
- [Context Management](/docs/context-management): Automatic live-zone-only context management that compresses the newest content blocks while preserving the provider cache hot zone.

- **Memory**
- [Persistent Memory](/docs/memory): Hierarchical, temporal memory for LLM applications. Enable your AI to remember across conversations with intelligent scoping and versioning.
- [SharedContext](/docs/shared-context): Compressed inter-agent context sharing. Reduce token usage by ~80% when agents hand off to each other.
- [Failure Learning](/docs/failure-learning): Offline failure analysis for coding agents. Analyzes past sessions, finds what went wrong, correlates with what fixed it, and writes project-level learnings.

- **Proxy Server**
- [Proxy Server](/docs/proxy): Run the Headroom proxy to compress LLM traffic for any client — Claude Code, Cursor, OpenAI SDK, or custom apps.
- [Local LLM Prefill Benchmark](/docs/local-llm-prefill): Measure local LLM prompt-processing savings by running Headroom in passthrough and optimized proxy modes against an OpenAI-compatible local server.

- **Integrations**
- [Vercel AI SDK](/docs/vercel-ai-sdk): Compress LLM context with the Vercel AI SDK using middleware, withHeadroom(), or standalone compression.
- [OpenAI SDK](/docs/openai-sdk): Auto-compress messages in the OpenAI Node.js SDK with a single withHeadroom() wrapper.
- [Anthropic SDK](/docs/anthropic-sdk): Auto-compress messages in the Anthropic TypeScript SDK with a single withHeadroom() wrapper.
- [LangChain & LangGraph](/docs/langchain): Compress context in LangChain chat models, memory, retrievers, and LangGraph agents.
- [Agno](/docs/agno): Automatic context compression for Agno AI agents with model wrapping and observability hooks.
- [Strands](/docs/strands): Context compression for Strands Agents via model wrapping and hook-based tool output compression.
- [CrewAI](/docs/crewai): Automatic tool output compression for CrewAI agents with per-tool metrics tracking.
- [AutoGen](/docs/autogen): Automatic tool output compression for AutoGen agents with per-tool metrics tracking.
- [LiteLLM](/docs/litellm): Add Headroom compression to LiteLLM with a single callback. Works with all 100+ supported providers.
- [Claude Code on Vertex AI](/docs/claude-code-vertex): Run Claude Code against Claude models on Google Vertex AI, with Headroom compressing your prompts — fewer input tokens, same answers, your own GCP login.
- [Claude Code on Azure AI Foundry](/docs/claude-code-azure-foundry): Run Claude Code against Claude models on Azure AI Foundry, with Headroom compressing your prompts — fewer input tokens, same answers, your own Azure credentials.
- [Use Headroom with Claude Code in VS Code](/docs/vscode-claude-code): Route the official Claude Code extension through Headroom's local compression proxy.
- [VS Code Copilot Integration](/docs/vscode-copilot): Transparently route the model selected in GitHub Copilot through Headroom on macOS, Windows, and Linux.
- [OpenCode Integration](/docs/opencode): Route OpenCode traffic through Headroom for token compression, MCP tools, and cached model access. One command to wrap, one to unwrap.
- [OpenCode + DeepSeek](/docs/opencode-deepseek): Configure OpenCode to route DeepSeek traffic through the Headroom proxy for compression, output shaping, and savings visibility.
- [Grok Build Integration](/docs/grok-build): Route Grok Build traffic through Headroom for token compression and per-project savings attribution.
- [MCP Tools](/docs/mcp): Compression, retrieval, and stats as MCP tools for Claude Code, Cursor, and any MCP-compatible host.

- **Configuration**
- [Configuration](/docs/configuration): All configuration options for the Headroom Python and TypeScript SDKs, proxy server, and per-request overrides.
- [Recover Codex State](/docs/codex-recovery): Merge sessions and configuration left in a temporary Headroom Codex home back into the durable Codex home.
- [Pipeline Extensions](/docs/pipeline-extensions): Write a request-normalization extension for a quirky upstream provider, and route requests to different upstream bases per request with x-headroom-base-url.
- [Filesystem Contract](/docs/filesystem-contract): Where Headroom writes config, runtime state, logs, and caches — the canonical two-root model, precedence rules, and Docker behavior.

- **Observability**
- [Savings Tracking](/docs/savings): Durable, over-time compression savings — cost avoided plus Today / Last 7 days / Last 30 days and per-model / per-client breakdowns via `headroom savings`.
- [Metrics & Monitoring](/docs/metrics): Monitor compression performance, cost savings, and system health with Headroom's built-in metrics, Prometheus endpoint, and SDK APIs.
- [Simulation](/docs/simulation): Preview compression results without making an LLM call. Use simulation for cost estimation, debugging, and understanding waste signals.

- **API Reference**
- [API Reference](/docs/api-reference): Complete API reference for the Headroom Python and TypeScript SDKs. Core client, configuration types, result types, errors, and utilities.

- **Architecture**
- [Architecture](/docs/architecture): How Headroom compresses LLM traffic — from request interception through the ContentRouter compression pipeline to provider cache optimization.
- [CI/CD Flow Diagrams](/docs/ci-cd-flows): Visual decision trees for pull requests, release publishing, Docker images, docs deploys, and manual validation.
- [Releases & CI/CD](/docs/releases): Automated release pipeline with release-please, semantic versioning, multi-package publishing, and changelog generation.
- [Runtime Rollouts](/docs/runtime-rollouts): Deterministic runtime feature control for installed Headroom artifacts.
- [Benchmarks](/docs/benchmarks): Compression performance, accuracy preservation, and latency overhead, measured on reproducible local benchmarks.
- [Limitations](/docs/limitations): When Headroom helps, when it does not, and what to watch out for. Honest documentation of compression constraints and safety gates.

- **Help**
- [Error Handling](/docs/errors): How to catch and handle Headroom errors in Python and TypeScript. Error hierarchy, proxy error mapping, and safety guarantees.
- [Troubleshooting](/docs/troubleshooting): Solutions for common Headroom issues including proxy startup, connection errors, no token savings, high latency, and installation problems.