# Headroom — Context Compression + MCP for Agents

> Local context optimization layer: proxy/wrap/CCR + MCP tools to compress logs/files/RAG for agents; verified 1742★, pushed 2026-05-14.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

```bash
pip install "headroom-ai[all]"
headroom wrap claude        # wrap a coding agent
headroom proxy --port 8787  # drop-in proxy mode
```

## Intro

Local context optimization layer: proxy/wrap/CCR + MCP tools to compress logs/files/RAG for agents; verified 1742★, pushed 2026-05-14.

**Best for:** Agent-heavy teams hitting context limits on logs, tool output, and long histories

**Works with:** Python/Node apps, OpenAI-compatible clients via proxy, and MCP clients via Headroom MCP tools (per README)

**Setup time:** 8-20 minutes

### Key facts (verified)

- GitHub: 1742 stars · 158 forks · pushed 2026-05-14.
- License: Apache-2.0 · owner avatar + repo URL verified via GitHub API.
- README-backed entrypoint: `pip install "headroom-ai[all]" && headroom wrap claude`.

## Main

- Start with wrap mode: `headroom wrap claude|codex|cursor` gives quick wins without rewriting your app stack.

- Use proxy mode for language-agnostic pipelines: point any OpenAI-compatible client at the proxy and keep data local (per README).

- Treat CCR as reversible: README emphasizes originals are retrievable, so you can compress aggressively without losing auditability.

- Measure savings: capture before/after token counts (README demo shows 10,144 → 1,260) and tune only where it matters.

### Source-backed notes

- README lists three usage modes: library, proxy (`headroom proxy`), and agent wrap (`headroom wrap ...`).
- README states it provides an MCP server with tools like `headroom_compress`/`headroom_retrieve`/`headroom_stats`.
- README demo includes a concrete token reduction example (10,144 → 1,260) and describes CCR as reversible.

### FAQ

- **Do I need to change my app?**: Not necessarily — start with `headroom wrap ...` or run `headroom proxy` as a drop-in endpoint.
- **Is compression reversible?**: README says CCR keeps originals; the agent can retrieve raw content on demand.
- **How do MCP clients use it?**: Install/enable the Headroom MCP server (README mentions MCP-native entrypoints) and call compress/retrieve tools.

## Source & Thanks

> Source: https://github.com/chopratejas/headroom
> License: Apache-2.0
> GitHub stars: 1742 · forks: 158

---

<!-- ZH -->

## Quick Use

```bash
pip install "headroom-ai[all]"
headroom wrap claude        # wrap a coding agent
headroom proxy --port 8787  # drop-in proxy mode
```

## Intro

Headroom 是本地上下文优化层：proxy/wrap/CCR + MCP 工具压缩日志/文件/RAG 片段以节省 token，并支持按需取回原文；已验证 1742★，更新于 2026-05-14。

**Best for:** agent 频繁读日志/工具输出/长历史而经常触顶上下文窗口的团队

**Works with:** Python/Node 应用；OpenAI 兼容客户端可走 proxy；MCP 客户端可调用 Headroom MCP tools（README）

**Setup time:** 8-20 minutes

### Key facts (verified)

- GitHub：1742 stars · 158 forks；最近更新 2026-05-14。
- 许可证：Apache-2.0；作者头像与仓库链接均已通过 GitHub API 复核。
- README 中可对照的入口命令：`pip install "headroom-ai[all]" && headroom wrap claude`。

## Main

- 先用 wrap 模式：`headroom wrap claude|codex|cursor` 不改业务代码也能立刻省 token。

- 需要语言无关就用 proxy：把任意 OpenAI 兼容客户端指向本地 proxy，数据留在本机（README）。

- 把 CCR 当成可逆压缩：README 强调原文可按需取回，因此可以更激进地压缩同时保留可审计性。

- 量化收益：记录压缩前后 token（README demo 给出 10,144 → 1,260），只在高频场景里调参。

### Source-backed notes

- README 列出三种使用模式：库、proxy（`headroom proxy`）与 agent wrap（`headroom wrap ...`）。
- README 表示提供 MCP server，并包含 `headroom_compress`/`headroom_retrieve`/`headroom_stats` 等工具。
- README demo 给出 token 压缩例子（10,144 → 1,260），并强调 CCR 为可逆压缩。

### FAQ

- **需要改应用吗？**：不一定；先用 `headroom wrap ...` 或把 `headroom proxy` 当作 drop-in 入口即可。
- **压缩可逆吗？**：README 表示 CCR 会保留原文，必要时 agent 可按需取回。
- **MCP 客户端怎么用？**：启用 Headroom 的 MCP server（README 提到 MCP-native 入口），然后调用 compress/retrieve/stats 工具。

## Source & Thanks

> Source: https://github.com/chopratejas/headroom
> License: Apache-2.0
> GitHub stars: 1742 · forks: 158


---
Source: https://tokrepo.com/en/workflows/headroom-context-compression-mcp-for-agents
Author: Agent Toolkit