skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
l3ad3r1/hermes-skills80 installs

headroom

Context compression for AI agents — 60–95% fewer tokens by compressing tool outputs, logs, files, and conversation history before they reach the model. MCP tools headroom_compress/retrieve/stats plus an optional traffic-compressing proxy. Wraps the open-source headroom-ai; on Windows install via WSL2.

How do I install this agent skill?

npx skills add https://github.com/l3ad3r1/hermes-skills --skill headroom
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides documentation and setup instructions for the 'headroom' context compression tool. It guides users through installing the 'headroom-ai' package from PyPI and the 'uv' tool from Astral's official site to enable token savings by compressing agent context, logs, and search results.

  • Socketpass

    No alerts

  • Snykfail

    Risk: CRITICAL · 1 issue

What does this agent skill do?

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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/l3ad3r1/hermes-skills/headroom">View headroom on skillZs</a>