headroom

Level ALocal

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.

Overview

Headroom is a context compression layer for AI agents. It compresses tool outputs, logs, files, RAG chunks, and conversation history before they reach the LLM, aiming for the same answers with fewer tokens. It is available as a library, proxy, and MCP server. Compression runs locally, and originals are cached for on-demand retrieval. Coding agents see about 20% fewer tokens, while repetitive JSON can drop 60–95%.

⭐ 80.2kSearch & InfoPythonRepo ↗Updated 2026-11-20

Installation

MCP client config (paste into mcp.json)

{
  "mcpServers": {
    "headroom": {
      "command": "uvx",
      "args": [
        "--from",
        "headroom-ai[mcp]",
        "headroom",
        "mcp",
        "serve"
      ]
    }
  }
}

Agent install prompt

Copy and paste into Cursor / Claude / other agents to install this MCP for you

Please read this MCP repository and install it into my current environment:
https://github.com/headroomlabs-ai/headroom

Known working client config (can write into mcp.json):
{
  "mcpServers": {
    "headroom": {
      "command": "uvx",
      "args": [
        "--from",
        "headroom-ai[mcp]",
        "headroom",
        "mcp",
        "serve"
      ]
    }
  }
}

Please: 1) check README for deps and env vars; 2) write config for my client; 3) if secrets are missing, tell me what to fill — do not invent values.

Related servers