mcpField
H
headroom

headroom

github.com/l3ad3r1Agent workflows077 installsUpdated 15w ago
Repository

About headroom

headroom compresses context for agents, helping developers reduce the content sent to an LLM. It detects JSON, code, and text, and can cache originals locally for retrieval on demand.

Key features

  1. 01Compress tool outputs and conversation history
  2. 02Detect JSON, code, and text
  3. 03Cache originals locally for retrieval
  4. 04Inspect compression and token savings
  5. 05Provide a CLI and MCP server

Use cases

  1. 01Reduce verbose logs entering context
  2. 02Compress search results and large files
  3. 03Retrieve full content only when needed

MCP support

The headroom MCP server exposes tools for compressing content, retrieving originals, and viewing statistics. Register it with `headroom mcp install` or run `headroom mcp serve`.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/l3ad3r1/hermes-skills --skill headroom

After installing, type/headroomin Claude Code to confirm it loaded.

Bundled filesNOTICE.md

Details

From the project README

Headroom

Context compression for AI agents — reduce the tokens sent to an LLM by 60–95% while preserving meaning, by compressing tool outputs, logs, search results, RAG chunks, files, and conversation history before they reach the model. It auto-detects content type (JSON / code / text) and supports CCR (Compress-Cache-Retrieve): originals are cached locally and fetched on demand.

Upstream: headroom by chopratejas (Apache-2.0); published on PyPI as headroom-ai.

When to Use

  • A tool/command returns a large dump (verbose logs, big JSON, long file listings, search results, large files) that would bloat the context window.
  • The user asks to compress context, shrink a payload, or save tokens.
  • Compress before the large content is committed to context.

Setup

pip install "headroom-ai[mcp]"      # or [all] for every compressor / extra

Register the MCP server (exposes headroom_compress / headroom_retrieve / headroom_stats):

headroom mcp install        # auto-configures detected coding agents
# or run the server directly: headroom mcp serve

For full automatic compression of all traffic, run the proxy and point the client at it. This routes every API request through a local proxy, so enable it deliberately:

headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

Tools (MCP, shown as mcp__headroom__*)

  • headroom_compress — compress a blob of context/content
  • headroom_retrieve — fetch the original uncompressed content (CCR)
  • headroom_stats — compression statistics / token savings

Use headroom_compress on a large output, keep the compressed summary in context, and call headroom_retrieve only when the full original is actually needed.

CLI extras: headroom perf (savings), headroom output-savings, headroom learn --verbosity, headroom update. Env toggles: HEADROOM_OUTPUT_SHAPER=1, HEADROOM_UPDATE_CHECK=off, HF_HUB_OFFLINE=1.

Installation notes & known issues

Windows source build fails — install inside WSL2 instead. headroom-ai includes a Rust extension (crates/headroom-py, built via maturin/cargo). On Windows there is no prebuilt wheel for recent Python, so pip/uv fall back to compiling from source — which fails when a GNU link (from Git / coreutils) shadows the MSVC link.exe linker (link: extra operand → could not compile target-lexicon → maturin failed). Rather than untangle the Windows Rust toolchain, install on the Linux side where wheels build cleanly:

# inside WSL2 Ubuntu (no sudo needed):
curl -LsSf https://astral.sh/uv/install.sh | sh      # if uv isn't present
uv tool install "headroom-ai[mcp]"                   # -> ~/.local/bin/headroom

Then register the MCP server from your Windows client by wrapping into WSL:

claude mcp add-json headroom \
  '{"command":"wsl.exe","args":["-d","Ubuntu","-e","bash","-lc","export PATH=$HOME/.local/bin:$PATH; exec headroom mcp serve"]}' \
  --scope user

On Linux/macOS, pip install "headroom-ai[mcp]" works directly — skip the WSL wrapper and register headroom mcp serve straight.

Credits

Upstream project: headroom by chopratejas (Apache-2.0); distributed on PyPI as headroom-ai. This skill documents and wires up the upstream tool for the Agent Skills format; the source is not vendored — install it from PyPI / the upstream repo.

Skill by Rinu (l3ad3r1) in collaboration with Claude (Anthropic).

Comments

Markdown supported