# Headroom Token Compression

> Compress AI Agent tool outputs, logs, and RAG content using Headroom — reduce token usage by 20-95%

- Skill: `johnsonbuilds/headroom-token-compression` (Agent Skill)
- Install (CLI): `npx skillmds@latest add johnsonbuilds/headroom-token-compression`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnsonbuilds/headroom-token-compression/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: johnsonbuilds (https://skillmd.com/u/johnsonbuilds)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/johnsonbuilds/headroom-token-compression

---


# Headroom Token Compression

Compress content sent to LLMs (tool outputs, logs, RAG chunks, files) while maintaining answer quality — reduces token consumption by 20-95%.

## 🚨 Privacy & Data Security Warning (Read Before Use)

Headroom caches **raw uncompressed content** locally (for later retrieval). This means:
- Your prompts, tool outputs, logs, etc. will be cached on your local machine
- Data is **NOT sent to external services** (all processing is local)
- But cached files are stored on local disk — ensure your device is secure

**Data that should NOT be processed:**
- Content containing API keys, passwords, or private tokens
- Personally identifiable information (PII)
- Internal company code or proprietary business information
- Any content you don't want stored on local disk

If processing sensitive data, ensure: ① device has encrypted storage; ② regularly clean headroom cache directory (`~/.headroom/cache`).

---

## Trigger Conditions

**Only use this skill in the following explicit scenarios:**

- You **actively request** compression of specific content (e.g., "compress these logs", "reduce tokens in this code search")
- You are dealing with obvious **large redundant data** (e.g., 100+ search results, extremely long logs, duplicate JSON)
- You have confirmed the content does **NOT contain sensitive information** (see privacy warning above)
- You are experiencing high token costs in Claude Code, Codex, Cursor, etc.

**NOT suitable for:**
- Routine conversations or general Q&A
- Processing logs or code containing sensitive data
- Ordinary tasks without explicit compression needs

---

## Source

- GitHub: https://github.com/headroomlabs-ai/headroom
- Stars: ~71,000
- License: MIT

---

## Installation

```bash
# Using uv (recommended)
uv tool install --python 3.13 "headroom-ai[all]"

# Or using pip
pip install "headroom-ai[all]"
```

---

## Usage

### 1. One-Click Deploy (Simplest)
```bash
headroom deploy
```
Automatically configures local deployment and agent integration.

### 2. Wrap Common Agents
```bash
# Wrap Claude Code
headroom wrap claude

# Wrap Codex
headroom wrap codex

# Wrap OpenCode
headroom wrap opencode
```
Use `headroom unwrap <tool>` to remove wrapping.

> **Note**: Wrap operations modify agent startup configuration. Make sure you know what you're doing.

### 3. Proxy Mode (Zero Code Changes)
```bash
headroom proxy --port 8787
```
Any OpenAI-compatible client can use this proxy by setting API base URL.

### 4. Python Library (Inline Use)
```python
from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
```

### 5. MCP Server Mode
```bash
headroom mcp install
```
Provides `headroom_compress`, `headroom_retrieve`, `headroom_stats` tools to any MCP client.

---

## Verify Installation

```bash
# Health check
headroom doctor

# View savings stats
headroom perf

# Real-time dashboard (requires running proxy)
headroom dashboard
```

---

## Compression Results

| Scenario | Before | After | Savings |
|----------|--------|-------|---------|
| Code search (100 results) | 17,199 tokens | 13,597 tokens | **21%** |
| SRE incident debugging | 55,957 tokens | 24,340 tokens | **57%** |
| Codebase exploration | 58,801 tokens | 33,895 tokens | **42%** |
| GitHub Issue classification | 46,067 tokens | 32,429 tokens | **30%** |

JSON duplicate data can save 90%+. Plain text content compresses less.

---

## Output Compression (Reduce Model Response Tokens)

```bash
# Enable output compression
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

# Auto-learn your verbosity preferences
headroom learn --verbosity
headroom learn --verbosity --apply
```

---

## Supported Agents

| Agent | Support |
|-------|---------|
| Claude Code | ✅ |
| Codex | ✅ |
| OpenCode | ✅ |
| Cursor | Manual config |
| Aider | ✅ |
| Copilot CLI | ✅ |
| Cline | ✅ |
| Continue | ✅ |
| Goose | ✅ |
| OpenHands | ✅ |

---

## Pitfalls

- **Local caching**: Raw content cached on local disk, models can retrieve full content via `headroom_retrieve`. To clear cache, delete `~/.headroom/cache` directory.
- **Proxy mode**: When using proxy mode, configure client to use `http://localhost:8787` as API base.
- **Output shaping is optional**: Disabled by default, must be enabled manually.
- **Sensitive data risk**: As mentioned, raw data is cached locally. Ensure device security before processing sensitive content.

---

## References

- GitHub: https://github.com/headroomlabs-ai/headroom
- Docs: https://docs.headroomlabs.ai/docs
- Benchmarks: https://docs.headroomlabs.ai/docs/benchmarks