headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

Headroom – AI 에이전트를 위한 컨텍스트 압축 레이어

개요 – Headroom은 언어 모델 기반 에이전트가 전송하는 입력(도구 출력, 로그, RAG 청크, 파일, 대화 기록)을 압축하고, 모델이 작성하는 출력도 트리밍할 수 있는 라이브러리, CLI 및 프록시입니다. 압축은 전적으로 사용자의 로컬 머신에서 이루어지며, 처리를 위해 데이터가 원격 서비스로 전송되지 않습니다.

중요성 – 대규모 언어 모델(LLM) API는 토큰 단위로 과금됩니다. 코딩 어시스턴트 워크플로우에서는 단일 요청에 수만 개의 토큰(예: 긴 로그 덤프나 검색 결과)이 포함될 수 있습니다. Headroom은 모델의 답변을 변경하지 않으면서 실제 시나리오에서 토큰 수를 20‑60% 절감합니다. 처리가 로컬에서 빠르게(10 K‑token 페이로드당 1밀리초 미만) 이루어지므로 지연 시간 영향은 무시할 수 있습니다.

핵심 구성 요소

구성 요소	역할
`compress(messages)` (Python / TypeScript)	채팅 메시지 목록의 압축 버전을 얻기 위해 모든 코드에서 호출할 수 있는 인라인 함수.
`headroom proxy`	OpenAI 호환 클라이언트가 연결할 수 있는 로컬 HTTP 프록시(기본값 `--port 8787`). 코드 변경이 필요 없습니다.
`headroom wrap <agent>`	인기 코딩 에이전트(Claude, Codex, Grok, Cursor, Copilot 등)를 위한 원커맨드 래퍼. 프록시 시작, 선택적 도우미(예: Serena 코드 내비게이션 도구) 설치, 에이전트의 Headroom 라우팅 설정을 수행합니다.
MCP server	모든 Multi‑Component Protocol 클라이언트를 위한 RPC 엔드포인트(`headroom_compress`, `headroom_retrieve`, `headroom_stats`)를 제공합니다.
에이전트 간 메모리	서로 다른 에이전트 간에 압축된 컨텍스트를 중복 제거하는 공유 저장소. Claude, Codex, Gemini 등이 동일한 압축 페이로드를 재사용할 수 있습니다.
CCR (가역 압축)	원본 비압축 텍스트는 로컬에 캐시됩니다. LLM이 전체 콘텐츠를 필요로 할 때 `headroom_retrieve`로 요청할 수 있습니다.
`headroom learn`	실패한 세션을 분석하고 수정 프롬프트를 추출하여 Markdown 파일(`CLAUDE.local.md`, `AGENTS.md` 등)에 기록하여 향후 실행에 활용합니다.

작동 원리(개요)

ContentRouter가 각 데이터(JSON, 소스 코드, 일반 텍스트, 이미지)를 검사하고 적절한 압축기를 선택합니다.
SmartCrusher가 범용 JSON을 처리하고, CodeCompressor가 여러 프로그래밍 언어의 AST를 처리하며, Kompress‑v2‑base(HuggingFace 모델)가 자연어 텍스트를 압축합니다.
CacheAligner가 공급자의 KV 캐시 접두사를 손상시킬 수 있는 휘발성 조각을 표시하여 압축이 캐시 적중을 방해하지 않도록 합니다.
압축된 페이로드가 LLM 공급자(Anthropic, OpenAI, Bedrock 등)로 전송됩니다. 모델이 나중에 전체 텍스트를 요청하면 CCR이 로컬 캐시에서 원본을 가져옵니다.
모델 응답 후 Headroom은 출력을 형성할 수도 있습니다. 시스템 프롬프트에 간결한 지침을 추가하고 순수 연속 턴에서 모델의 "사고 부하"를 줄여 실무에서 출력 토큰을 약 30% 절감합니다.

퀵 스타트 (≈60초)

# 설치 (Python, CLI 및 선택적 프록시 확장 기능)
uv tool install --python 3.13 "headroom-ai[all]"   # 또는 pip install "headroom-ai[all]"
npm install headroom-ai                               # TypeScript SDK 전용

# 로컬 프록시 배포 및 에이전트 래핑 (예: Claude Code)
headroom deploy               # 로컬 서버 및 설정 파일 설정
headroom wrap claude          # 프록시를 시작하고 Claude Code를 통해 실행

# 작동 확인 및 절감량 확인
headroom doctor               # 상태 점검
headroom dashboard            # 실시간 토큰 절감 뷰 (프록시 실행 중 필수)

코드 내에서 라이브러리를 직접 호출할 수도 있습니다:

from headroom import compress
from openai import OpenAI

msgs = [{"role": "user", "content": "Analyze these results"}]
compressed = compress(msgs, model="gpt-4o")
client = OpenAI()
resp = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
print(f"Saved {compressed.tokens_saved} tokens ({compressed.compression_ratio:.0%})")

에이전트 호환성

Headroom은 많은 코딩 어시스턴트(Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenHands, Mistral Vibe, Kimi CLI, ZCode 등)에 대해 즉시 사용 가능한 wrap 명령을 제공합니다. OpenAI 호환 클라이언트라면 로컬 프록시 URL을 지정하는 것만으로 사용할 수 있습니다.

성능 측정

시나리오	압축 전 토큰	압축 후 토큰	절감량
SRE 인시던트 디버깅	55,957	24,340	57 %
코드 검색 (100개 결과)	17,199	13,597	21 %
코드베이스 탐색	58,801	33,895	42 %
GitHub 이슈 분류	46,067	32,429	30 %

지연 시간: 10 K‑token JSON 페이로드에서 p50 0.21밀리초, 100 K 토큰에서 1.4밀리초로 일반적인 LLM 요청 지연 시간보다 훨씬 낮습니다.

정확도: GSM8K, TruthfulQA, SQuAD v2 및 도구 사용 제품군 벤치마크에서 모델 품질의 측정 가능한 저하는 나타나지 않았습니다(예: TruthfulQA 0.530 → 0.560, 신뢰 구간 내).

사용 시기 / 건너뛸 시기

적합한 경우 – 대량의 도구 출력, 로그 또는 RAG 청크를 정기적으로 수집하는 코딩 에이전트를 사용하는 경우. 기존 코드를 수정하지 않고 토큰 비용을 절감하려는 경우. 가역 압축이나 에이전트 간 메모리 공유가 필요한 경우.

건너뛸 경우 – 워크로드가 이미 작거나(짧은 대화 턴, 밀도 높은 글), 공급자의 내장 압축 기능에만 의존하며 에이전트 간 메모리가 필요 없는 경우.

제한 사항 및 주의 사항

압축은 반복적이거나 구조화된 데이터(JSON 배열, 로그)에 가장 효과적입니다. 순수 산문이나 이미 압축된 페이로드는 절감 효과가 거의 없습니다.
min_input_words 임계값보다 짧은 블록은 KV 캐시 접두사를 유지하기 위해 그대로 둡니다.
출력 형성은 홀드아웃 세트(HEADROOM_OUTPUT_HOLDOUT)를 예약하지 않는 한 추정치입니다. 대시보드는 신뢰 구간을 보고합니다.
래핑된 에이전트를 사용하려면 프록시를 계속 실행해야 합니다. 중지하면 headroom unwrap을 통해 원래 설정으로 복원됩니다.

추가 정보

문서 및 아키텍처 – https://docs.headroomlabs.ai/docs/architecture
모델 카드 – https://huggingface.co/chopratejas/kompress-v2-base
라이브 데모 GIF – 10 K‑token 로그가 FATAL 라인을 유지한 채 1.2 K 토큰으로 압축되는 모습.
Discord 커뮤니티 – https://discord.gg/yRmaUNpsPJ

요약

Headroom은 로컬에서 실행되는 오픈소스 압축 레이어로, 코딩 어시스턴트 워크플로우에서 LLM과 주고받는 토큰 수를 대폭 줄여줍니다. 라이브러리, 드롭인 HTTP 프록시 또는 수십 개의 인기 에이전트용 원커맨드 래퍼로 작동하며, 1밀리초 미만의 오버헤드로 20‑60%의 토큰 절감 효과를 제공하고 답변 품질을 저하시키지 않습니다.