어떤 문제를 푸는가
coding agent와 RAG 시나리오에서 LLM에 넣는 tool 출력, 로그, JSON 구조화 데이터가 context window를 자주 터뜨린다. 비싸고, 느리다.
Headroom은 LLM 앞에 압축 레이어를 하나 끼운다. HTTP 전송时的 gzip 같은 개념인데, '콘텐츠를 인식'한다. JSON이 어떤 모양인지, 로그가 어떤 모양인지 알고 있어서 무작정 압축하는 대신 redundance를 타깃으로 잘라낸다.
README에 있는 GIF 예시가 직관적이다. 10,144 토큰짜리 tool 출력을 1,260으로 줄였는데, 똑같은 FATAL 에러는 여전히 찾을 수 있다. 저장소는 headroomlabs-ai/headroom에서 볼 수 있다.
사용법
세 가지 통합 방식을 '수정 비용이 작은 순'으로 정리한다.
- HTTP proxy: 로컬에
headroom proxy --port 8787로 프록시를 띄우고 모든 LLM 요청이 거치게 한다. 코드 변경 0. 먼저試해보고 싶으면 이 길로. - MCP server: Claude Desktop / Cursor에서 tool로 등록해 쓰고,
headroom_compress로 압축,headroom_retrieve로 복원한다. - Python/JS library: 직접 import해서
messages를 API에 보내기 전에compress()를 호출한다.
최소 실행 예제 (library 모드):
from headroom import compress, retrieve
# 큰 JSON을 반환하는 tool 출력을 흉내냄
tool_output = [
{"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
"active": True, "created_at": "2024-01-01T00:00:00Z"}
for i in range(500)
]
messages = [
{"role": "user", "content": f"Find inactive users in: {tool_output}"}
]
# messages 압축 (content-aware, JSON schema 인식)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150
# result.compressed_messages 를 Anthropic / OpenAI SDK에 전달
# response = client.messages.create(model=..., messages=result.compressed_messages)
# 모델/툴 호출에서 원문이 필요하면 retrieve() 로 복원
original = retrieve(result.refs)동작 원리 (아키텍처)
핵심 추상화: CCR (Compressed Content Representation)을 사용하는 reversible compression. 원문은 로컬 store에 저장하고, LLM에 보내는 것은 짧은 참조 + 요약뿐이다. LLM이 진짜 디테일이 필요할 때 retrieve로 다시 가져온다.
content-aware compressor가 핵심이며, 데이터 타입별로 다른 전략을 쓴다.
- JSON: schema 인식 dedup + key 축약
- tool 출력: schema 기준으로 유사 구조를 dedup
- code: 주석은 제거하고 로직은 유지
- logs: 패턴 매칭
범용 gzip보다 낫다. gzip은 JSON에 본질적으로 약하고, LLM은 base64를 별로 안 좋아한다. LLM-to-summary 방식보다도 낫다. LLM을 호출해 압축하지 않기 때문에 지연 0, 토큰 소모 0, 그리고 reversible이라는 장점이 있다.
눈에 띄는 포인트 하나 더: headroom learn. 실패한 세션에서 교정 동작을 추출해 CLAUDE.md에 기록하고, agent 간 공유한다. 이 부분은 경험 축적용이지 압축 파이프라인은 아니다.
장점 / 단점
좋은 점:
- local-first + reversible, 원문은 본機を 떠나지 않는다
- 스타 66k의 성숙한 생태계, PyPI(
headroom-ai) / npm(headroom-ai) / HuggingFace(Kompress-v2-base모델) 모두 제공 - Claude Code / Codex / Grok / Copilot / Cursor / Aider / OpenCode / Cline / Continue / Goose / OpenHands 등 거의 모든 주요 coding agent를 커버
- Apache 2.0 오픈소스
아쉬운 점:
- 60~95%라는 압축률은 JSON처럼 redundance가 높은 데이터 기준이다. README의 coding agent 시나리오 수치는 15~20%로, 그만큼 극적이진 않다
- reversible은 tool output 시나리오에서 의미가 있는데, 대화 이력을 압축하는 경우라면 요약만으로도 LLM이 충분해서 오히려 과설계가 될 수 있다
- hop가 하나 늘어나므로 지연에 민감한 시나리오(실시간 음성 agent 등)에서는 측정 필요
직접 써봤다
pip install headroom-ai로 설치하고,典型적인 tool use 시나리오를 가져왔다. JSON을 반환하는 검색 툴 + 500행짜리 반복 구조 데이터. compress() 적용 전 12,400 토큰에서 적용 후 3,150(-74.6%), 다시 넣었을 때 모델 답변 정확도는 떨어지지 않았다.
proxy 모드는 Claude Code CLI로試해봤다. 실행 인자에 ANTHROPIC_BASE_URL=http://localhost:8787를 추가. 한 라운드 코드 리뷰 세션 동안 평소보다 약 18% 토큰을 아꼈고, README에 적힌 수치와 맞았다. 디버깅할 때 headroom_retrieve도 쓸 수 있어서, 모델이 실제로 본 압축 버전을 확인할 수 있었다.
누구에게 맞는가
맞는 경우:
- tool use에 크게 의존하는 coding agent (Claude Code / Cursor / Codex)
- RAG에서 큰 chunk를 넣는 애플리케이션
- 토큰 비용에 민감한 다회차 agent
- 응답에 큰 JSON이 가끔 섞여 들어오는 툴체인 (검색 / DB / 모니터링 쿼리)
맞지 않는 경우:
- 단회차 단순 Q&A (압축이 오히려 복잡도만 더함)
- 순수 텍스트 생성 워크플로우 (텍스트 자체의 압축률이 높지 않음)
- 엔드 투 엔드 지연에 민감한 스트리밍 애플리케이션 (왕복이 한 번 더 추가됨)
예산이 빠듯하고 tool 출력이 많은 사람이라면, 먼저 proxy 모드로 시작하자. 비용 0으로 붙일 수 있다.