headroomlabs-ai/headroom

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.

What it solves

Headroom reduces the number of tokens sent to and received from LLMs, lowering costs and latency for AI agents. It specifically targets the "ceremony" and repetitive data found in tool outputs, logs, RAG chunks, and conversation history that often bloat agent prompts without adding unique value.

How it works

Headroom acts as a local compression layer between the agent and the LLM provider. It uses a ContentRouter to detect the type of data and apply the appropriate compression method:

  • SmartCrusher: Handles JSON data using field-variance statistics to keep critical values while removing repetitive patterns.
  • CodeCompressor: Uses AST-aware compression for multiple programming languages.
  • Kompress-v2-base: A specialized HuggingFace model for compressing prose and text.
  • CacheAligner: Ensures volatile content doesn't break the provider's KV-cache prefix.
  • CCR (Context Compression & Retrieval): Caches original text locally, allowing the model to retrieve the full version via a tool if needed.

It can be deployed as a library (Python/TypeScript), a transparent proxy for zero-code changes, or an MCP server.

Who it’s for

Developers and power users who run coding agents (like Claude Code, Cursor, Aider) daily and want to reduce token usage, as well as developers building AI agent applications who need a way to compress large contexts across multiple agents.

Highlights

  • Broad Agent Compatibility: Supports wrapping for a wide range of tools including Claude Code, Cursor, Aider, and Copilot.
  • Cross-Agent Memory: Provides a shared memory store across different LLMs (e.g., Gemini, Grok, Claude) with automatic deduplication.
  • Output Token Reduction: Trims model responses by steering verbosity and adjusting reasoning effort for routine tasks.
  • Local Execution: Compression runs entirely on the user's machine; no prompt or file content is sent to external servers for compression.
  • headroom learn: Analyzes failed sessions to write corrections to local agent configuration files.

Related

  • Project
    gglucass/headroom-desktop

    A cross‑platform desktop tray app that intercepts Claude Code, Codex, OpenCode and Grok Build requests, compresses prompts and tool output locally, and cuts token usage by about 50 % while keeping the original results.

  • Project
    ranxianglei/billion-context

    A context-compression proxy for AI agents that uses model-driven summaries to reduce token usage and enable month-long coding sessions within small context windows.

  • Project
    vllm-project/llm-compressor

    A genuine, actively maintained Python library that quantizes and compresses large language‑model checkpoints (including MoE, vision‑language, and audio‑language models) for fast, low‑VRAM inference with vLLM. It offers many algorithms (GPTQ, AWQ, AutoRound, REAP), supports INT4/FP8/NVFP4/MXFP4 and mixed‑precision formats, provides Triton‑accelerated kernels, DDP and disk‑offloading for huge models, and outputs checkpoints in the `compressed‑tensors` format ready for vLLM.

  • Project
    TencentCloud/TencentDB-Agent-Memory

    TencentDB Agent Memory is an open‑source memory hub for LLM agents. It captures conversations, extracts reusable skills, builds a Wiki from docs, and indexes code into a CodeGraph. A central UI (Memory Hub) lets teams manage assets, set fine‑grained ACLs, and bind specific memory pieces to individual agents. Agents talk to a uniform proxy, so any framework (Claude Code, DeepSeek Harness, OpenClaw, etc.) can use the same memory without code changes. Benchmarks show a 59 % boost in persona retention. The repo provides one‑click Docker deployment, migration tools, and a roadmap for zero‑config cold starts and more integrations.

  • Dispatch
    Codemode in Pi: JavaScript sandbox for orchestrating tool calls

    Codemode is a sandboxed JavaScript layer in the Pi harness that lets LLMs compose and manage tool calls without flooding the model context, enabling richer workflows and tighter integration with MCP servers.