Headroom 리뷰: AI 에이전트 토큰을 줄이는 컨텍스트 압축 오픈소스, 설치와 사용법

Headroom은 AI 에이전트가 모델에 보내는 도구 출력, 로그, 검색 결과, 파일, 대화 기록을 모델에 닿기 전에 압축해 입력 토큰을 줄이는 오픈소스입니다. Claude Code, Codex 같은 코딩 에이전트에는 headroom wrap 한 줄로 끼우고(Cursor는 프록시 주소를 직접 설정), 직접 만든 앱에는 compress() 함수로 넣을 수 있습니다. 2026년 11월 13일 기준 GitHub 별 79,482개를 받았고 최신 버전은 v0.44.0입니다. 이 글은 Headroom 저장소의 README, 릴리스 노트, 공식 문서, 패키지 등록 정보를 2026년 11월 13일에 읽고 정리한 소개와 사용법 리뷰입니다. 직접 설치해 측정하지는 않았고, 절감률 같은 숫자는 모두 프로젝트가 밝힌 값입니다.

스크린샷: headroomlabs-ai/headroom GitHub 저장소의 대시보드 예시 이미지(v0.3.0 화면 일부), Apache License 2.0

핵심 요약

• 무엇인가요: 에이전트와 LLM 사이에서 도구 출력·로그·JSON·대화 기록을 압축하는 도구입니다. 프로젝트 설명에 따르면 압축은 내 컴퓨터에서 이루어지고, 원본은 로컬에 저장돼 모델이 필요할 때 다시 가져올 수 있습니다.
• 쓰는 방법 네 가지: 파이썬·타입스크립트 라이브러리, 로컬 프록시, 에이전트 래퍼(headroom wrap), MCP 서버입니다.
• 프로젝트가 밝힌 절감률: 에이전트 시나리오 네 가지에서 입력 토큰 21~57% 감소, 반복되는 JSON 배열이나 로그 줄은 90% 이상입니다. 산문은 거의 줄지 않습니다.
• 설치: uv tool install --python 3.13 "headroom-ai[all]" 후 headroom wrap claude로 시작합니다. 파이썬 3.11 이상이 필요합니다.
• 주의할 점: 익명 사용 통계 전송이 기본으로 켜져 있고, 버전 업데이트가 잦아 호환이 깨지는 변경도 나옵니다. 짧은 대화나 코드 위주 작업에서는 효과가 작다고 공식 문서가 밝힙니다.

Headroom은 어떤 프로젝트인가요

AI 코딩 에이전트는 파일을 읽고 명령을 실행하고 검색할 때마다 그 결과를 모델에 보냅니다. 이 결과에는 반복되는 JSON 필드, 수천 줄의 정상 로그, 같은 구조의 검색 결과처럼 모델이 꼭 읽을 필요가 없는 내용이 섞이기 쉽습니다. 프로젝트는 이런 반복이 많을수록 절감이 커진다고 설명하고, Headroom은 그 부분을 모델 앞에서 줄여 주는 압축 계층입니다.

저장소 설명과 README를 정리하면 동작 방식은 이렇습니다.

• ContentRouter가 내용 종류를 감지해 알맞은 압축기에 넘깁니다.
• 압축기는 내용별로 나뉩니다. JSON은 SmartCrusher, 소스 코드는 문법 트리 기반 CodeCompressor(기본값에서는 제한적으로 동작, 아래 한계 항목 참고), 일반 텍스트는 프로젝트가 직접 학습해 허깅페이스에 올린 Kompress-v2-base 모델이 맡습니다.
• CacheAligner는 제공사의 프롬프트 캐시를 깨뜨릴 수 있는 변동 내용을 표시만 하고, 프롬프트를 고쳐 쓰지는 않는다고 설명합니다.
• CCR(되돌릴 수 있는 압축)은 원본을 로컬에 보관하고, 모델이 headroom_retrieve 도구로 원문을 다시 요청하게 합니다.
• 압축 대상은 새로 들어온 부분(최신 도구 출력, 마지막 턴)입니다. 앞쪽 대화는 바이트 단위로 그대로 두어 제공사 프롬프트 캐시가 유지되게 하고, 대화 기록은 지우지 않는다고 설명합니다.
• 압축하려고 프롬프트나 파일 내용을 외부로 보내지 않고 내 컴퓨터에서 처리한다는 점을 README가 강조합니다. 다만 별도의 사용 통계 전송이 있으니 아래 주의할 점을 확인하세요.

Headroom 프로젝트 현황

2026년 11월 13일에 GitHub API와 패키지 저장소에서 확인한 값입니다.

저장소를 만든 지 약 열 달인데 최근 정식 릴리스는 5~12일 간격으로 이어지는, 빠르게 움직이는 프로젝트입니다. v0.44.0 릴리스 노트에는 [all] 설치 항목에서 PyTorch 계열 추가 패키지를 뺀 변경이 호환이 깨지는 변경(BREAKING CHANGES)으로 올라 있고, Hermes 에이전트 래핑 지원도 새로 들어갔습니다. 기능이 빠르게 늘어나는 만큼 버전을 올릴 때는 릴리스 노트를 확인하는 편이 안전합니다.

어떻게 쓰나요: 네 가지 방식

설치와 사용법

1. 코딩 에이전트에 붙이기

README가 코딩 에이전트 사용자에게 권하는 순서입니다.

uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude

headroom wrap은 로컬 프록시를 시작하고, 그 프록시를 거치도록 설정한 에이전트를 실행합니다. 이 프록시는 에이전트가 끝나면 같이 종료됩니다. README 표에 따르면 Claude Code에는 --memory, --code-graph, --1m, --tool-search 옵션이 있습니다. 되돌리려면 headroom unwrap <도구>를 씁니다.

재부팅 후에도 프록시를 유지하려면 headroom deploy(한 번에 로컬 배포와 에이전트 설정)나 headroom install apply를 쓰라고 안내합니다.

2. 직접 만든 앱에 넣기

pip install headroom-ai

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%})")

이 함수는 API 키나 모델 내려받기 없이 프로세스 안에서 실행되고, 환경 변수 HEADROOM_OFFLINE=1을 주면 네트워크 접근도 하지 않는다고 합니다. 기본 설정에서는 도구·어시스턴트 메시지만 압축 대상이고, 사용자 메시지까지 압축하려면 compress_user_messages=True를 지정해야 합니다. 위 예제는 README의 코드이며 메시지가 한 줄뿐이라 실제로는 거의 줄지 않습니다. 도구 출력이 큰 대화에서 효과가 나는 구조입니다.

타입스크립트 앱은 npm install headroom-ai로 SDK를 설치하되, 압축은 로컬 프록시가 맡습니다. pip install "headroom-ai[proxy]" 후 headroom proxy --port 8787로 프록시를 먼저 띄워야 합니다. npm 패키지는 라이브러리일 뿐 headroom 명령은 들어 있지 않습니다.

3. 프록시만 쓰기

공식 퀵스타트의 예시입니다.

headroom proxy --port 8787

# Claude Code가 프록시를 거치게 하기
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# OpenAI 호환 클라이언트
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

4. 절감량 확인하기

headroom doctor      # 상태 점검: 라우팅이 되는지 확인
headroom perf
headroom dashboard   # 실시간 절감 화면(프록시가 실행 중이어야 함)
headroom savings     # 내 트래픽 기준 절감량
curl http://localhost:8787/stats

프로젝트가 발표한 절감률이 내 작업에도 그대로 나온다는 보장은 없습니다. README도 자기 트래픽에 해당하는 숫자는 headroom savings로 직접 확인하라고 안내합니다.

5. 업데이트

headroom update가 pip, pipx, uv tool 중 설치 방식을 알아내 그 방식대로 올립니다. 확인만 하려면 headroom update --check입니다.

6. 윈도우에서 설치할 때

• v0.44.0 릴리스 자산에는 윈도우(win_amd64)·리눅스·맥용 휠(미리 빌드한 설치 파일)이 들어 있습니다. 사내망 설명 항목에서도 윈도우 휠이 있어 로컬에서 Rust를 빌드할 필요가 없다고 적혀 있습니다.
• 회사 보안 장비가 SSL 검사를 하는 환경을 위한 안내가 따로 있습니다. 실행할 때 운영체제 인증서 저장소를 읽고, headroom doctor --network로 확인할 수 있으며, 인증서를 못 찾으면 HEADROOM_CA_BUNDLE을 지정합니다.
• 윈도우에서 GitHub Copilot CLI 구독으로 쓰려면 headroom copilot-auth login을 먼저 실행하라고 합니다.
• 환경 변수는 PowerShell에서는 보통 $env:이름 = "값" 형식으로 지정합니다. 문서에는 bash의 export 예시만 있어서 PowerShell 동작은 확인하지 못했습니다.
• README의 다른 항목은 네이티브 휠이 현재 애플 실리콘 맥과 리눅스를 다룬다고도 적어, 설치 안내가 문서 안에서 엇갈립니다. 윈도우에서 설치가 막히면 v0.44.0 릴리스의 휠 파일 목록과 이슈 목록을 먼저 확인하세요.

Headroom 대시보드에서 보이는 것

스크린샷: headroomlabs-ai/headroom GitHub 저장소의 대시보드 예시 이미지(v0.3.0 화면 일부), Apache License 2.0

위 대표 이미지와 이 이미지는 저장소에 올라 있는 예시 화면입니다. 제가 측정한 값이 아니고, 현재 버전(v0.44.0)보다 한참 앞선 v0.3.0 화면이라 지금은 모양이 다를 수 있습니다. 화면에는 요청 128건, 압축 전 388.0k 토큰이 압축 후 245.0k가 된 것(절감 143.0k, 36.9%), 제거된 내용이 JSON 군더더기 95.0k와 반복 48.0k로 나뉜 것, 오버헤드 14ms가 보입니다. 이 14ms는 요청 전체가 프록시를 거치는 구간의 값으로 보이고(제 해석입니다), 아래에서 소개하는 README의 압축 단계 측정값(0.21ms)과 측정 대상이 달라 직접 비교할 수 없습니다. 이 화면이 보여 주려는 것은 토큰이 얼마나 줄었는지, 무엇이 줄었는지, 제공사 프롬프트 캐시가 깨지지 않았는지를 한 화면에서 확인하게 하는 설계입니다.

프로젝트가 제시한 성능 근거

입력 토큰 절감

README에 따르면 실제 MCP 서버의 출력 형식을 흉내 낸 시나리오 네 가지를 제공사 토크나이저로 쟀고, 난수 시드를 고정해 누구나 같은 숫자를 재현할 수 있습니다. 재현 명령은 uv run python benchmarks/index_proof_table.py --seed 20260902입니다.

반복되는 JSON 배열과 로그 줄은 90%를 넘고 산문이나 이미 촘촘한 출력은 거의 줄지 않는다는 설명이 붙어 있습니다. 압축에 드는 시간은 JSON 검색 결과 1만 토큰에서 중앙값 0.21ms, 10만 토큰에서 1.4ms라고 합니다.

정확도

같은 기준(python -m headroom.evals suite --tier 1)으로 낸 표입니다.

README 스스로 문항이 100개라 ±0.03 차이는 오차 범위 안이라고 설명하고, TruthfulQA도 개선이 아니라 차이를 확인하지 못한 것으로 봐야 한다고 적었습니다. 이 점은 제 판단으로도 맞다고 봅니다. 문항 100개로는 "정확도가 유지된다"는 방향을 보여 줄 뿐 강한 증거는 못 됩니다. 모든 수치는 프로젝트 자체 측정이며 제3자 검증은 확인하지 못했습니다.

출력 토큰도 줄일 수 있나요

모델이 쓰는 출력 토큰은 입력보다 비싸다는 점(README는 Opus급 모델에서 5배라고 설명)에 착안해, Headroom은 프록시 단계에서 답변 길이를 줄이는 기능도 따로 둡니다. 시스템 프롬프트 맨 끝에 "간결하게 답하라"는 취지의 안내를 붙이는 방식이라 프롬프트 캐시는 유지된다고 합니다. 기본값은 꺼짐이고 다음처럼 켭니다.

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

절감량은 "만약 이 기능이 없었다면 모델이 얼마나 썼을지"를 알 수 없어 추정치로만 나옵니다. headroom output-savings가 신뢰구간과 함께 [estimated]로 표시하고, HEADROOM_OUTPUT_HOLDOUT=0.1로 대화의 10%를 대조군으로 빼 두면 측정값으로 바꿀 수 있습니다.

지원하는 에이전트와 연동

README의 호환 표는 Claude Code, Codex, Grok CLI, Aider, GitHub Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Factory Droid, Kimi CLI, ZCode를 headroom wrap 지원으로 적고, Cursor는 프록시를 시작해 주소를 알려 주는 수동 설정, Cortex Code는 라이브러리 전용으로 구분합니다. v0.44.0에서는 Hermes 에이전트 지원도 릴리스 노트에 추가됐습니다. Hermes Agent를 다룬 이전 글 Hermes Agent 설치부터 Oh My Hermes 얹기까지도 함께 보세요.

프레임워크 쪽은 LangChain, LiteLLM, Agno, Strands, Vercel AI SDK와 Anthropic·OpenAI SDK 래퍼, ASGI 미들웨어를 문서가 안내합니다. 에이전트 여러 개가 쓰는 공유 메모리와, 실패한 세션에서 교정 내용을 뽑아 CLAUDE.local.md(기본, 깃에서 제외), CLAUDE.md, AGENTS.md 같은 파일에 써 주는 headroom learn도 들어 있습니다.

Headroom의 아쉬운 점과 주의할 점

• 효과가 작은 경우가 명확합니다. 공식 한계 문서는 짧은 대화, 코드만 읽고 쓰는 세션, 누적된 맥락이 없는 단발 요청에서는 효과가 작거나 오버헤드가 이득보다 클 수 있다고 적습니다. 50토큰 미만 메시지, 시스템 프롬프트, 이미지(고정 토큰 비용)는 압축하지 않습니다.
• 코드 압축은 문서마다 설명이 다릅니다. 한계 문서에 따르면 최근 4개 메시지의 코드와, 마지막 사용자 메시지에 analyze·review·explain·fix·debug 같은 단어가 있을 때의 모든 코드는 보호됩니다. README는 문법 트리 기반 코드 압축기를 내세우지만 퀵스타트 표는 소스 코드 압축을 기본 꺼짐(opt-in)이라고 적고, 한계 문서는 최신 도구 출력에는 적용한다고도 적어 서로 어긋납니다. 이미지도 README는 40~90% 압축을 내세우는데 한계 문서는 고정 토큰 비용으로 계산할 뿐 압축하지 않는다고 적습니다. 직접 확인하지 못해 어느 쪽이 맞는지는 단정할 수 없고, 제 판단으로는 코딩 에이전트에서의 절감은 주로 JSON·로그 같은 도구 출력에서 나올 가능성이 큽니다. 한계 문서에는 "Headroom 0.37.0"이라는 옛 버전 표기가 남아 있어 최신 상태가 아닌 부분이 있을 수 있습니다.
• 익명 사용 통계가 기본으로 켜져 있습니다. 압축 비율, 카운터, 제공사·모델 ID, 운영체제와 아키텍처를 보내고 프롬프트·응답·코드·파일 경로는 보내지 않는다고 합니다. 끄려면 HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1, HEADROOM_OFFLINE=1 중 하나를 씁니다. 한계 문서는 인식하지 못한 값이면 전송된다고 적으므로 이 목록의 값을 정확히 쓰는 편이 안전합니다. 프록시는 시작할 때 하루 한 번까지 PyPI에서 새 버전을 확인하는데(HEADROOM_UPDATE_CHECK=off로 끔), 이것도 네트워크 요청입니다. 회사 코드를 다룬다면 켜기 전에 정책을 확인하세요.
• 프록시 설정을 잘못하면 키가 다른 곳으로 갈 수 있습니다. 코딩 에이전트에 붙이면 요청이 로컬 프록시를 거칩니다. README는 서드파티 OpenAI 호환 서비스(DeepSeek, OpenRouter 등)를 쓸 때 --openai-api-url로 업스트림 주소를 지정하지 않으면 기본 업스트림인 OpenAI로 키가 보내져 401 오류가 난다고 경고합니다.
• 변화가 빠릅니다. 최근 정식 릴리스는 5~12일 간격이고, v0.44.0(11월 10일 릴리스)에도 호환이 깨지는 변경이 있었습니다. 열린 이슈·PR은 299건입니다(PR 포함 수치라 품질과는 별개입니다). 팀 환경이라면 버전을 고정하고 올리기 전에 릴리스 노트를 읽는 방식이 어울립니다.
• 절감 수치는 프로젝트 자체 측정입니다. README는 이 오픈소스가 한 개발자의 노트북에서 가능한 것을 보여 주려고 만든 프레임워크라 가능한 만큼 줄이지는 못한다고 설명하고, 더 큰 절감을 내는 Headroom Enterprise를 만들고 있으니 팀·기업은 문의하라고 안내합니다. 저장소 자체는 Apache 2.0 오픈소스로 남는다고 밝혔습니다.

어떤 사람에게 맞을까요

• 맞는 경우: 도구 호출이 많은 에이전트나 긴 세션을 돌려 JSON·로그 출력이 큰 사람, API 비용을 줄이고 싶은데 코드를 못 고치는 클라이언트를 쓰는 사람, 여러 에이전트에서 같은 메모리를 공유하고 싶은 사람.
• 건너뛰어도 되는 경우: 짧은 대화 위주로 쓰거나, 제공사의 자체 압축 기능으로 충분하고 원본 복원이나 에이전트 간 메모리가 필요 없는 사람. README도 이 경우 Headroom이 필요 없을 수 있다고 적습니다.
• 써 보려면: 문서 기준으로는 처음에 headroom wrap claude로 한 세션만 돌려 보고 headroom dashboard와 headroom savings로 내 작업에서 실제로 얼마나 줄었는지 확인한 다음, 이득이 있을 때 headroom deploy 같은 상시 설정으로 넘어가는 순서가 안전해 보입니다.

마무리

Headroom은 에이전트가 읽는 반복적인 출력을 로컬에서 줄이겠다는 목적이 분명한 도구입니다. 문서 기준으로는 로컬 실행, 원본 복원(CCR), 에이전트별 한 줄 연동, 직접 돌려 볼 수 있는 재현 명령을 갖춘 점이 장점으로 보입니다. 반면 효과는 입력의 반복 정도에 크게 좌우되고, 공개된 수치는 자체 측정이며, 사용 통계 기본 전송과 빠른 버전 변화는 도입 전에 확인할 부분입니다. 이 글은 문서 기준 정리라서 실제 체감 절감량은 직접 headroom savings로 재 보시길 권합니다.

참고 링크

• headroomlabs-ai/headroom 저장소
• v0.44.0 릴리스 노트
• 공식 문서: 퀵스타트, 한계(Limitations)