headroom

Compress accumulated LLM context locally via a port 8790 proxy.

3|2|Updated Mar 13, 2026
One-click install
npx skills add https://github.com/yoonhwan/ai-feature-pack --skill headroom-yoonhwan
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: headroom
Source: https://github.com/yoonhwan/ai-feature-pack/tree/main/feature-pack/headroom
Command: npx skills add https://github.com/yoonhwan/ai-feature-pack --skill headroom-yoonhwan

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Long AI coding sessions accumulate massive context that gets resent every turn, burning through cache and rate limits. headroom compresses that context locally before it reaches the LLM, cutting re-prefill costs and extending productive work time before hitting hard limits.

Core Features & Use Cases

  • Per-project toggle: Enable compression only for specific projects via /headroom on so it never activates without explicit user consent.
  • Fail-open proxy: Routes through a local compression proxy on port 8790, but falls back to direct connection if the proxy dies, preventing session-wide outages.
  • Cache-preserving compression: Uses deterministic output alignment to keep prefix cache hits intact while shrinking the middle context band.

Quick Start

Use the headroom skill to enable context compression for your current project by running /headroom on and then launch Claude Code through the claude-hr wrapper to start saving tokens on long sessions.

Frequently Asked Questions about headroom

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reduce token costs for long AI coding sessions?

You can reduce token costs in long AI coding sessions by compressing accumulated context locally before sending it to the LLM, cutting down re-prefill spend and rate-limit consumption. headroom applies this compression automatically.

How does context compression work without breaking LLM prefix cache hits?

Context compression preserves prefix cache hits by using deterministic output alignment to shrink the middle context band while keeping the prefix intact. This maintains cache efficiency while reducing overall token transmission size.

How do I enable context compression for a specific project?

To enable context compression for a specific project, run the `/headroom on` command to opt in via the per-project registry, then launch Claude Code through the `claude-hr` wrapper to start routing through the local proxy and saving tokens.

What happens if the local LLM proxy crashes during a coding session?

If the local LLM proxy crashes during a coding session, the fail-open wrapper logic automatically falls back to a direct connection, preventing session-wide outages and ensuring your AI coding work continues without interruption.

Can I use context compression for multi-agent swarms and repeated document processing?

Yes, context compression applies to multi-agent swarms and repeated document processing where context re-prefill dominates spend. By shrinking accumulated context before transmission, it extends productive work time before hitting hard rate limits.