Headroom: 에이전트가 읽는 도구 출력·로그·파일을 LLM에 보내기 전에 로컬에서 압축하고, 필요하면 원문을 되찾는 도구
headroomlabs-ai/headroom은 Apache-2.0 Python 프로젝트로 작성 시점에 별이 약 7만 5천 개다. 에이전트가 읽는 도구 출력, 로그, 검색 조각, 파일을 모델에 보내기 전에 내 컴퓨터에서 압축한다. 라이브러리, 프록시, wrap 명령으로 쓸 수 있고 원문은 로컬 캐시에 남아 되찾을 수 있다. README 벤치마크는 토큰 21~57% 절감을 보이지만 모두 프로젝트 자체 측정이다.
headroomlabs-ai/headroom은 Python으로 쓴 오픈소스 프로젝트로 Apache-2.0 라이선스입니다. 2026년 1월 7일에 만들어졌고 마지막 푸시는 10월 13일이며, 작성 시점에 별 약 75,257개와 포크 5,838개가 있습니다. 소개는 한 문장입니다. AI 에이전트가 읽는 모든 것, 즉 도구 출력, 로그, RAG 조각, 파일, 대화 기록을 LLM에 닿기 전에 압축해서 답은 같게 하고 토큰은 일부만 남긴다는 것입니다. README는 압축이 내 컴퓨터에서 이루어지며 압축을 위해 프롬프트나 파일 내용이 어디로도 전송되지 않는다고 강조합니다. 에이전트 사용에서 흔한 낭비를 노립니다. 검색이 결과 100개를 돌려주고 로그가 같은 줄을 천 번 반복하며, 이 모든 것이 컨텍스트에 들어가 창을 차지하고 토큰 단위로 과금됩니다.
구조는 세 부분입니다. ContentRouter가 내용 유형을 판별해 압축기를 고릅니다. JSON에는 SmartCrusher, 소스 코드에는 구문 트리를 쓰는 CodeCompressor, 일반 텍스트에는 Kompress-v2-base입니다. CacheAligner는 공급자의 KV 캐시 앞부분을 깨뜨릴 변동성 있는 내용에 표시만 하며 프롬프트를 고쳐 쓰지 않는다고 README는 말합니다. 핵심은 가역 압축인 CCR로, 원문을 로컬에 캐시해 두고 모델이 전문이 필요할 때 headroom_retrieve를 호출해 되찾습니다. 정보를 잃지 않을까 하는 압축의 흔한 걱정에 답하는 설계입니다. 연결도 유연합니다. 코드에서 compress(messages)를 부르거나, headroom proxy로 애플리케이션을 바꾸지 않고 프록시를 띄우거나, headroom wrap으로 Claude Code, Codex, Cursor, Aider 등 긴 목록의 코딩 에이전트를 감싸거나, 세 가지 도구를 가진 MCP 서버로 쓸 수 있습니다.
관련 기능도 몇 가지 있습니다. 하나는 에이전트 간 공유 기억으로, Claude, Codex, Gemini, Grok이 하나의 저장소를 쓰며 자동으로 중복을 제거합니다. 또 하나는 headroom learn으로 실패한 세션을 분석해 수정 사항을 CLAUDE.local.md(기본값, git 제외), CLAUDE.md, AGENTS.md, GEMINI.md, GROK.md에 씁니다. 세 번째는 출력 토큰 절감입니다. 보내는 내용을 줄일 뿐 아니라 모델이 써서 돌려보내는 내용도 프록시에서 줄이는데 방법은 두 가지입니다. “장황함 유도”는 시스템 프롬프트 끝에 “간결하게, 문맥을 되풀이하지 말라”는 짧은 안내를 붙여 프롬프트 캐시가 계속 적중하게 합니다. “노력 라우팅”은 파일 읽기 같은 도구 결과 뒤에 모델이 작업을 재개할 뿐인 차례에서는 사고 강도를 낮추고, 새 질문과 오류에는 전체 강도를 유지합니다. README는 Opus급 모델에서 출력 비용이 입력의 5배라고 말하므로 이 부분이 실익이 있습니다.
수치를 보면 README 벤치마크는 실제 MCP 서버 출력 형식으로 만든 시드 고정 시나리오 네 가지를 씁니다. 코드 검색(결과 100개)은 17,199에서 13,597 토큰으로 21% 절감, SRE 장애 대응은 55,957에서 24,340으로 57%, 코드베이스 탐색은 58,801에서 33,895로 42%, GitHub 이슈 분류는 46,067에서 32,429로 30%입니다. 프로젝트는 절감이 내용의 반복 정도에 비례한다고 말합니다. 반복되는 JSON 배열과 로그 줄은 지연 벤치마크에서 90%를 넘고 산문이나 이미 촘촘한 출력은 거의 압축되지 않습니다. 압축은 빠르며 10K 토큰 JSON 검색 결과에서 중앙값 0.21밀리초, 100K 토큰에서 1.4밀리초입니다. 정확도는 N=100에서 GSM8K가 기준과 Headroom 모두 0.870이고 TruthfulQA는 0.530에서 0.560이지만 프로젝트 스스로 신뢰구간 안이라고 하므로 검출 가능한 차이가 없다고 읽어야 합니다. SQuAD v2는 97%(압축 19%), BFCL은 97%(압축 32%)입니다.
안전하게 쓰려면 어떻게 할까요? 첫째, 모든 수치는 작은 표본에서 프로젝트가 스스로 보고한 벤치마크입니다. 도입 전에 자기 실제 트래픽에서 headroom savings를 실행해 절감률을 확인하고, 이미 간결한 출력에서 큰 효과를 기대하지 마세요. 둘째, headroom wrap은 얇은 포장만이 아닙니다. 로컬 프록시를 띄우고 감싼 프로젝트에 의미 기반 코드 탐색을 위한 Serena를 설치하며, Claude Code에서는 ~/.claude.json에 로컬 범위 MCP 서버를 등록합니다. 되돌리려면 headroom unwrap을 쓰고 원치 않으면 옵션으로 건너뛰세요. 셋째, 원문은 로컬에 캐시되지만 모델이 보는 것은 압축된 텍스트이므로 에이전트 동작을 디버깅할 때 이를 기억해야 합니다. 전체적으로 생각이 분명하고 가역적이며 시험하기 쉬운 비용 절감 도구이고, 먼저 테스트 환경에서 평가하기에 알맞습니다.
Sources
FAQ
Headroom은 무엇을 압축하고 어떻게 붙이나요?
에이전트가 LLM에 보내려는 도구 출력, 로그, RAG 조각, 파일, 대화 기록을 압축합니다. 압축은 내 컴퓨터에서 이루어지며 README는 압축을 위해 프롬프트나 파일 내용을 어디로도 보내지 않는다고 말합니다. 연결 방법은 네 가지입니다. Python이나 TypeScript에서 compress(messages)를 호출하거나, headroom proxy --port 8787로 코드 변경 없이 프록시를 띄우거나, headroom wrap claude, codex 등으로 코딩 에이전트를 감싸거나, headroom_compress, headroom_retrieve, headroom_stats를 제공하는 MCP 서버로 쓸 수 있습니다.
얼마나 절감한다고 하고 믿을 수 있나요?
README 벤치마크는 실제 MCP 서버 출력 형식으로 만든 네 가지 시나리오를 쓰며 시드가 고정되어 오프라인에서 재현됩니다. 코드 검색(결과 100개)은 17,199에서 13,597 토큰으로 21% 절감, SRE 장애 대응은 55,957에서 24,340으로 57%, 코드베이스 탐색은 58,801에서 33,895로 42%, GitHub 이슈 분류는 46,067에서 32,429로 30%입니다. 반복되는 JSON 배열과 로그 줄은 90%를 넘을 수 있고 산문이나 이미 촘촘한 출력은 거의 압축되지 않는다고도 밝힙니다. 이는 프로젝트 자체 시험이므로 자기 트래픽에서 headroom savings를 확인하세요.
압축으로 답이 나빠질 수 있나요? 주의할 점은?
프로젝트의 정확도 표(N=100)에서 GSM8K는 Headroom 사용 여부와 상관없이 0.870이고 TruthfulQA는 0.530에서 0.560이 되지만, 프로젝트 스스로 N=100에서 ±0.03은 신뢰구간 안이라며 개선이 아니라 차이를 검출하지 못했다고 밝힙니다. SQuAD v2는 97%(압축 19%), BFCL은 97%(압축 32%)입니다. 또한 headroom wrap은 로컬 프록시를 띄우고 감싼 프로젝트에 Serena를 MCP 서버로 설치합니다. Claude Code에서는 ~/.claude.json에 로컬 범위 항목을 쓰며 headroom unwrap으로 되돌릴 수 있고 옵션으로 건너뛸 수도 있습니다.