AI 에이전트의 '압축' 도구 Headroom을 사용해 보았다 ― 그 압축의 정체를 확인하다

서론

안녕하세요. FLINTERS의 Kawauchi입니다.

사내에서 열리는 AI 스터디 모임인 「AI 소믈리에」에서, 2026-06-15에 Headroom이라는 도구를 다루었습니다. AI 에이전트에게 전달하는 컨텍스트 (Context)를 압축하여 토큰 (Token)을 절약하는 OSS (Open Source Software)로, 이날 발표 담당이었던 Nishida 씨가 실제로 컨테이너에서 구동해 주었기에, 그 모습을 보며 다 함께 토론한 회차입니다.

계기는 요금입니다. 마침 최근 몇 주 사이에 GitHub Copilot과 Claude의 요금 체계가 연달아 바뀌면서, 「무제한에 가까운 정액제」에서 「사용한 만큼 지불하는 종량제 (usage-based billing)」로 흐름이 바뀌고 있습니다. 이러한 전환기에는 절약할 수 있는 방법을 하나라도 더 많이 확보해 두는 것 자체에 가치가 있다고 생각합니다.

다만, Headroom의 「토큰 60~95% 절감」이라는 수치는 광고 문구로서는 잘 만들어졌지만, 그대로 받아들이면 오해하기 쉽습니다. 제가 가장 알고 싶었던 것은 「여기서 말하는 압축이란 결국 무엇을 하고 있는가」였습니다. 가역적인 것인지, 요약 (Summarization)인지, 아니면 다른 장소에 원문을 두기만 하는 것인지. 스터디 모임에서는 그 부분을 실제 문서를 보며 추적해 나갔습니다.

본 기사는 스터디 모임의 내용을 AI를 활용하여 정리한 것입니다.

왜 지금 「토큰 절약」인가

Headroom 이야기를 하기 전에, Nishida 씨가 전제로 정리해 준 요금 흐름에 대해 언급해 두겠습니다.

먼저 GitHub Copilot입니다. 2026년 6월 1일부터 종량제 (usage-based billing)로 이행되었습니다. 기존의 고정 구독으로 「거의 무제한처럼」 사용할 수 있었던 것이, 소비 토큰에 따른 AI Credits (1 크레딧 = $0.01) 소비로 바뀌었습니다. 채팅이나 에이전트 실행과 같이 무거운 사용 방식일수록 비용 부담이 커지는 설계로, 이행 직후에는 「몇 시간 만에 월간 크레딧을 다 썼다」는 보고가 잇따랐으며, 해외 개발자 커뮤니티에서는 강한 반발이 나오고 있습니다.

그리고 Claude입니다. 2026년 6월 15일부터 이용 범위가 「대화형 이용」과 「프로그램적 이용」으로 분리되었습니다.

대화형 이용 (기존과 동일하게 구독 범위 내에서 사용하며, 상한에 도달하면 잠금이 걸림): 일반적인 채팅, 터미널에서의 Claude Code (대화 모드), Claude Cowork
프로그램적 이용 (플랜별 월간 크레딧에서 API 레이트 (Rate)로 소비): Claude Agent SDK, Claude Code의 비대화 모드 (claude -p), GitHub Actions에서의 자동 실행, 구독 인증으로 동작하는 서드파티 앱

월간 크레딧은 플랜별로 Pro가 $20, Max 5x가 $100, Max 20x가 $200 상당으로 되어 있습니다. 자율 에이전트를 돌리는 것과 같은 헤비한 사용 방식에서는 이 부분이 중요해집니다.

이 변경에 대해, 스터디 모임에서는 제가 배경을 보충했습니다. Anthropic의 이용 약관에서는 원래 OpenClaw와 같은 제3자 도구가 구독 인증 정보 (OAuth 토큰)를 사용하여 Claude를 프로그램적으로 호출하는 것이 금지되어 있었으며, 2026년 초에는 그 단속이 실제로 이루어지고 있습니다. 이번 6월 15일의 변경은 그 연장선상에 있는 것으로, 공식 도구 내의 프로그램적 이용 (Agent SDK나 claude -p, GitHub Actions)에 대해서도 대화형 이용 범위와는 별도로 크레딧에서 과금하는 형태로 정리했다는 위치 설정입니다. Nishida 씨로부터는 다음과 같은 의견이 돌아왔습니다.

있어야 할 형태가 되었다는 뜻이군요. 지금까지는 과한 혜택을 받고 있었다고.

반발의 목소리를 받아 구독 계약자에게는 약간의 배려가 들어간 것이 이번의 타협점이며, Anthropic의 입장으로는 「가격 인상이 아니다」라는 정리입니다. 그렇긴 하지만 추론 (Inference) 비용이 고공행진하고 있는 것은 사실이며, 각 기업 모두 「구독으로 무제한 사용」이 지속 불가능해짐에 따라 종량제나 크레딧제로 시프트 (Shift)하고 있는 것이 전체적인 흐름입니다.

이러한 「사용한 만큼 지불하는」 시대에, 전달하는 컨텍스트 자체를 줄일 수 없을까. 거기서 Headroom의 차례가 됩니다.

Headroom이란 무엇인가

Headroom은 LLM에 데이터가 도달하기 전에 컨텍스트를 압축하는 레이어 (Layer)입니다. Netflix의 엔지니어인 Tejas Chopra 씨가 만든 OSS로, 도구 출력, 로그, 파일, RAG チャンク (Chunk)와 같이 에이전트가 주고받는 「대부분 정형화된」 데이터를 모델에 도달하기 전에 압축합니다.

도입 방법은 세 가지가 준비되어 있습니다. Python / TypeScript 라이브러리로서 함수를 호출하거나, 프록시 서버 (Proxy Server)로서 기존 에이전트의 전단에 끼워 넣거나, 혹은 MCP 서버로 사용하는 방식입니다. Claude Code, Codex, Cursor, Aider와 같은 코딩 에이전트 외에도 LangChain이나 Strands와 같은 자체 제작 에이전트에도 대응합니다. 니시다(Nishida) 씨는 이번에 프록시로서 경유시키는 형태를 테스트하고 있었습니다.

특징적인 것은 **CCR (Compress-Cache-Retrieve)**이라는 메커니즘입니다. 압축할 때마다 원문을 로컬의 SQLite 캐시에 저장하고, 압축 후의 출력에는 "여기에 원문이 있음"이라는 참조 마커를 삽입합니다. 모델이 "역시 모든 데이터가 필요하다"라고 판단하면, headroom_retrieve라는 도구를 해시와 함께 호출하여 원문을 되찾을 수 있는 설계입니다. 기존의 요약이나 절삭 방식에서는 "중요한 것을 놓친 후에 다시 보고 싶다"라고 할 때 정보가 사라졌지만, 이 방식은 그 문제에 대한 해답이 되어 줍니다.

벤치마크 읽는 법

공식 벤치마크에서는 빌드 로그에서 93.9%, JSON 배열에서 최대 90% 초과와 같은 높은 토큰 절감률이 나열됩니다. 하지만 니시다 씨는 이 부분을 냉정하게 보충해 주었습니다. 실운용에서의 절감률은 중앙값으로 4~5% 정도, 평균으로도 11% 정도라는 데이터가 나오고 있습니다.

왜 이렇게 차이가 나는 걸까요? 니시다 씨와의 대화를 통해 납득할 수 있었습니다.

짧은 대화가 대량으로 있고, 가끔 거대한 것이 툭 튀어나온다. 그것에 대해 방어할 수 있다는 이미지인가요?

짧은 대화가 대량으로 있기 때문에 중앙값은 낮게 나오지만, 로그나 도구 출력처럼 무거운 데이터가 흘러들어왔을 때 절감률이 확 올라가는 성질을 가지고 있습니다. 평균 연봉 이야기와 마찬가지로, 큰 수치가 전체를 끌어올립니다. 즉, Headroom은 "항상 60% 줄어드는" 도구가 아니라, "무거운 입력이 왔을 때 효과를 발휘하는" 도구라고 이해하는 것이 정확해 보입니다. 홍보 문구의 숫자는 그 "맛있는 부분"만을 잘라낸 것이라고 파악해 두면 오해하지 않을 것입니다.

참고로, 이 실운용 데이터는 2026년 3~4월의 5만 건 이상의 프록시 세션, 250개 이상의 환경에서 익명 텔레메트리 (Telemetry)로 수집된 것이라고 합니다.

실제로 작동시켜 보았다

여기서부터는 니시다 씨가 데모해 준 내용입니다. 이번에는 컨테이너 환경에서 Headroom을 실행하고, Claude의 Base URL을 변경하여 프록시로서 경유시키는 구성이었습니다.

주의할 점으로, 텔레메트리가 기본적으로 ON으로 되어 있으므로 OFF로 설정합니다. 이는 절감된 토큰 수, 압축률, 캐시 히트율(Cache Hit Rate)과 같은 익명의 집계 통계를 제작자에게 보내는 설정으로, 실제 대화 내용 자체가 전송되는 것은 아니지만, 꺼두는 것이 좋습니다. 환경 변수 HEADROOM_TELEMETRY=off로 무효화할 수 있습니다.

FROM python:3.11
RUN pip install --no-cache-dir "headroom-ai[all]"
# 텔레메트리를 끔
...

services:
headroom:
build: .
...

docker compose up --build -d로 실행하여, 로그에 Headroom proxy running on ...이 뜨면 성공입니다. 그다음 Claude Code 측에서 Base URL을 향하게 하여 호출합니다.

ANTHROPIC_BASE_URL="http://localhost:8787" claude

이 상태에서 "프로젝트 내에 있는 가장 큰 로그 파일을 읽어서 에러 경향을 분석해 줘"와 같이 무거워 보이는 지시를 던지며 데모를 진행했습니다.

다만 니시다 씨로부터 더 간편한 방법도 보충 설명이 있었습니다. 공식적으로 준비된 래퍼 (Wrapper) 명령어를 사용하는 것이 더 빠르다는 것입니다.

# 설치
pip install "headroom-ai[all]" # Python
npm install headroom-ai # Node / TypeScript
...

headroom wrap claude

headroom wrap claude가 무엇을 하는지는 제가 보충 설명을 덧붙였습니다. 이것은 로컬에서 프록시 (Proxy)를 실행하고, 환경 변수를 설정하여 Claude Code를 기동하는 일련의 작업을 한꺼번에 처리해 주는 것입니다. 컨테이너는 사용하지 않습니다. 데모를 위해 일부러 컨테이너를 구성해 주었지만, 단순히 테스트해 보고 싶은 것이라면 래퍼 (Wrapper) 명령어를 사용하는 것이 압도적으로 편합니다.

절감량을 확인하는 방법도 여러 가지가 있습니다. http://localhost:8787/stats를 호출하면 통계를 JSON으로 얻을 수 있고, http://localhost:8787/dashboard를 열면 GUI로 확인할 수 있습니다.

curl -s http://localhost:8787/stats | jq . > stats.json

대시보드를 보면 얼마나 많은 토큰 (Token)이 절약되었고, 비용이 얼마나 절감되었는지 알 수 있습니다. 처음에는 별로 압축되지 않지만, 대화를 반복하다 보면 30% 정도 절약되는 상황도 나타났습니다. Headroom 측에서 캐시 (Cache)를 많이 보유하고 있다는 점도 확인할 수 있었는데, 이전과 변하지 않은 파일 등을 프로바이더 (Provider)에게 보내기 전에 효과적으로 생략하고 있는 듯했습니다.

실행 속도에 대해서는, 직접 사용해 본 범위 내에서는 큰 변화를 느끼지 못했습니다. 이론적으로는 중간에 Headroom를 끼워 넣는 만큼의 처리 시간 (프록시의 오버헤드 (Overhead)는 약 52ms로 알려져 있습니다)이 소요되지만, 컨텍스트 (Context)가 압축되기 때문에 프로바이더 측의 처리 시간은 짧아집니다. 공식 측정에서도 테스트한 12개 시나리오 중 11개에서 "압축에 걸리는 시간은 절감으로 만회할 수 있다"라고 밝혀졌으며, 거대한 컨텍스트를 다루는 경우에는 오히려 빨라질 가능성도 있습니다.

「압축」의 정체를 쫓다

이 부분이 저의 가장 큰 관심사였습니다. stats를 보면 JSON은 0%, Python 소스는 0%와 같이, 콘텐츠 종류에 따라 절감률이 완전히 다릅니다. 애초에 이 「압축」이란 무엇인가. 저는 이렇게 물었습니다.

"절감 후의 토큰 열로부터 절감 전의 토큰 열을 복원할 수 있습니까? 그것이 불가능하다면, SQLite에 원문을 저장해 두고 참조하는 것뿐인데, 그것을 압축이라고 부를 수 있습니까?"

답을 찾기 위해 Headroom의 문서를 함께 읽어 내려갔습니다.

알 수 있었던 점은, Headroom는 콘텐츠의 종류에 따라 압축 방법을 전환하고 있다는 것입니다.

JSON → SmartCrusher: Rust로 제작된 엔진으로, 통계적으로 배열을 압축합니다. 처음과 마지막 항목을 남기고, 에러나 이상치, 관련 아이템, 변화점과 같이 "절대로 놓치고 싶지 않은 것"을 유지하면서 그 외의 것들을 솎아냅니다. 100개·500개 규모의 JSON 배열에서 70~90% 절감이라는 결과가 있었습니다.
코드 → AST 분석: Python, JavaScript, Go, Rust, Java, C++ 등을 구문 트리 (AST, Abstract Syntax Tree)로 해석하여, 시그니처 (Signature)나 핸들러 (Handler)는 남기되 함수 본체, 주석, docstring을 선택적으로 삭제합니다. 문서에는 함수의 내용이 삭제되고 "생략됨" 표시로 대체되는 예시가 실려 있었습니다.
텍스트 → Kompress: ModernBERT 기반의 경량 모델을 사용하는 경로입니다. 이 부분만 로컬 언어 모델이 작동하고 있으며, 그 외에는 대부분 프로그램적인 구문 분석으로 압축하고 있는 듯했습니다.

스터디에서는 "사용되는 것이 MiniLM인가, 아니면 Microsoft 제작의 BERT 계열인가"라는 이야기도 나왔지만, 정확하게는 텍스트 경로는 ModernBERT 기반의 Kompress라는 컴포넌트였습니다. 한편, 실제로 구동했을 때 절감률이 0%가 되는 케이스도 있었습니다. grep 결과처럼 이미 컴팩트 (Compact)하여 형식을 바꾸면 깨져버리는 것은 무리하게 압축하지 않는 동작을 하는 듯합니다. 코드 또한 AST로 크게 깎아낼 수 있는 것은 함수 본체와 같은 중복된 부분이 있을 때이며, 짧은 소스라면 거의 줄어들지 않습니다. "중복된 부분은 대담하게 솎아내되, 이미 최소한인 것은 건드리지 않는다"는 식의 구분 사용이라고 이해했습니다.

여기까지 보고 나서, 저의 질문에 대한 결론이 났습니다.

이 압축은 비가역 압축 (Lossy Compression)이며, 요약에 가깝군요. 불필요한 부분을 생략하고, 오리지널은 다른 곳에 있으니 필요하면 그것을 보라는 식입니다.

CCR의 「가역」이란, 압축 알고리즘 자체가 가역이라는 의미가 아닙니다. 압축 자체는 요약적으로 솎아내는 비가역적인 처리이며, 원문을 SQLite에 보관하고 headroom_retrieve

로 되돌릴 수 있다는 **이중 구조 (two-step approach)**를 통해 '잃어버리지 않음'을 보장하고 있는 것입니다. 이 부분을 올바르게 이해해 두면, '중요한 정보가 컨텍스트에서 누락되어 모델이 가져오지 못하게 될' 리스크가 어디에 숨어 있는지도 보입니다. 정말로 필요한 부분이 생략되지 않았을까 하는 불안감은 행사장에서도 남아 있었습니다.

어디까지 직접 구현할 것인가

마지막으로, 스터디 모임에서 가장 뜨거웠던 논점입니다. Headroom와 같은 전처리를 언제까지 직접 감당해야 하는가 하는 문제입니다.

니시다(Nishida) 씨로부터는 "프로바이더(Provider) 측도 개선되고 있으므로, Headroom를 어디까지 사용할 것인가"라는 질문이 나왔습니다. 참가자들로부터도 다음과 같은 목소리가 있었습니다.

지금은 의식해야 하지만, 조만간 파운데이션 모델 (Foundation Model) 측에서 해 주겠지 하는 낙관론도 있습니다. 이것을 언제까지 직접 해야만 하는가 하는 점은 상당히 번거로운 문제입니다.

실제로 저 자신도 큰 문제를 느끼지 못하게 되고 있습니다. Claude Code는 버전 2.1.0 (2026년 1월) 무렵부터, 툴(Tool)이나 커맨드(Command)의 출력이 클 때는 버리지 않고 일단 파일로 저장한 뒤, "여기에 저장했다"라고만 전달하고 필요에 따라 읽으러 가는 동작을 하게 되었습니다. 그 이후로 컨텍스트 압박이 그렇게 심각하다고 느끼는 장면은 줄어들었습니다. 참가자들로부터도 "최근 2주 정도 토큰의 가성비가 좋아졌다는 이야기가 팀 내에서 나오고 있다"라는 공유가 있어, 프로바이더 측이 배후에서 개선을 진행하고 있다는 기색이 느껴집니다.

비슷한 맥락의 사례로, 이전에 다른 참가자가 소개했던 Serena MCP 이야기도 나왔습니다. 이것은 LSP (Language Server Protocol)를 내부적으로 사용하여 코드를 검색하는 메커니즘으로, grep을 사용하면 미스 히트(Miss-hit)가 많이 섞이는 반면, 타입 정보 등을 바탕으로 정확한 심볼(Symbol)만을 가져올 수 있습니다. 파일 전체를 읽지 않고 필요한 부분만 전달할 수 있으므로, 이 또한 토큰 절약 전략이 된다는 정리입니다. "정확하게 좁힌 뒤에 전달한다"라는 발상은 Headroom와 맞닿아 있습니다.

그리고 보안입니다. 프록시(Proxy)로 사용하는 이상, LLM과의 통신이 모두 Headroom를 경유합니다. 기본적으로는 로컬에서 완결되며 외부 서버에서 처리되는 것은 아니지만, 만약 악의적인 제작자가 섞여 있다면 그 모든 통신을 가로채는 장치를 심어버릴 수도 있습니다. 니시다 씨가 "사용해도 될지 망설여진다"라고 말한 것은 바로 이 점이었습니다.

그 점만 아니라면 사용 편의성은 변하지 않으므로, 충분히 쓸만하다고 생각합니다.

설정 측면에서도 텔레메트리 (Telemetry)를 기본적으로 OFF로 설정하는 것, --host 0.0.0.0과 같이 전체 공개를 해버리지 않는 것 (누구나 접속할 수 있는 상태로 만들지 않는 것)은 최소한의 주의 사항으로 꼽혔습니다.

요약

요금이 종량제로 움직이고 있는 지금, Headroom와 같은 "전달하기 전에 줄이는" 도구는 절약을 위한 선택지로서 알아둘 가치가 있습니다. 한편, 직접 사용해 보고 다시금 느낀 점은, 광고 문구인 "60~95% 삭감"을 그대로 기대하면 빗나간다는 것입니다. 효과가 있는 것은 무거운 입력이 들어왔을 때이며, 중앙값은 몇 % 수준입니다. 그리고 "압축"의 실체는 요약적으로 솎아내는 비가역적인 처리와, 원문을 캐시하여 되돌릴 수 있는 메커니즘의 이중 구조였습니다. 이 부분을 이해한 상태라면 로그 분석과 같이 무거운 데이터를 다루는 장면에서 충분히 유용할 것 같습니다.

동시에 파운데이션 모델이나 에이전트 측의 개선도 빠릅니다. Claude Code의 파일 퇴피(evacuation)처럼, 직접 하던 궁리들이 어느샌가 표준으로 흡수되어 가는 흐름도 있습니다. 그렇기에 "어디까지 직접 가져갈 것인가"를 그때마다 판단해 나가는 자세가 필요할 것 같습니다. 이번 Headroom는 그 판단 재료를 하나 늘려준 회였습니다.