에이전트 루프의 토큰 사용량을 60~95% 절감하면서 동일한 답변 유지하기: Headroom 소개

AI 코딩 에이전트(AI coding agents)는 비용이 많이 듭니다. 이는 모델의 토큰당 비용이 너무 높아서가 아니라, 너무 많은 토큰을 전송하기 때문입니다. 가공되지 않은 에이전트를 사용한 SRE 디버깅 세션에서는 65,694개의 토큰이 소모되었습니다. Headroom을 중간에 사용했을 때는 5,118개였습니다. 결과적으로 동일한 버그를 찾아냈습니다.

Headroom은 에이전트가 읽는 모든 것—도구 출력(tool outputs), 로그 덤프(log dumps), RAG 청크(RAG chunks), 파일, 대화 기록—을 가로채서 LLM이 보기 전에 압축하는 새로운 오픈 소스 컨텍스트 압축 레이어(context compression layer)입니다. 이는 로컬에서 작동하며, 가역적(reversible)이고, 드롭인 프록시(drop-in proxy), 라이브러리 또는 MCP 서버로 사용할 수 있습니다.

중요한 수치들

실제 에이전트 워크로드에서의 절감 효과:

• 코드 검색 (100개 결과): 17,765 → 1,408 토큰 (92% 감소)
• SRE 장애 디버깅: 65,694 → 5,118 토큰 (92%)
• GitHub 이슈 분류 (triage): 54,174 → 14,761 토큰 (73%)
• 코드베이스 탐색: 78,502 → 41,254 토큰 (47%)

표준 벤치마크(GSM8K, TruthfulQA, SQuAD v2, BFCL)에서의 정확도는 유지됩니다. 모델이 더 깨끗한 신호(signal)를 보게 되기 때문에 일부 점수는 실제로 약간 향상되기도 합니다.

압축을 수행하는 요소

내부적으로 Headroom은 콘텐츠를 특화된 압축기 스택을 통해 라우팅합니다:

• SmartCrusher — JSON, 중첩된 객체(nested objects), 딕셔너리 배열(arrays of dicts)
• CodeCompressor — Python, JS, Go, Rust, Java, C++를 위한 AST 인식(AST-aware) 방식
• Kompress-base — 산문(prose) 및 혼합 콘텐츠를 위해 에이전트 추적(agentic traces) 데이터로 학습된 커스텀 HuggingFace 모델
• CacheAligner — Anthropic/OpenAI의 KV 캐시(KV caches)가 실제로 작동할 수 있도록 프롬프트 접두사(prompt prefixes)를 안정화

또한 **CCR (가역적 압축, reversible compression)**을 수행합니다. 원본은 로컬에 캐싱되며, LLM이 필요할 경우 요청에 따라 이를 검색할 수 있습니다. 아무것도 파괴되지 않습니다.

프록시 모드가 중요한 이유

가장 흥미로운 배포 방식은 headroom proxy --port 8787을 실행한 후, 기존 도구를 localhost로 지정하는 것입니다. 코드 변경이 전혀 필요 없으며, 어떤 언어와도 함께 작동합니다.

더 간단하게도: headroom wrap claude를 사용하면 Claude Code를 감싸서(wrap) 트래픽을 자동으로 Headroom을 통해 라우팅합니다. 명령어 하나로 즉시 절감이 시작됩니다. Codex, Cursor, Aider, Copilot CLI도 마찬가지입니다.

"라이브러리(Library) — Python 또는 TypeScript에서 compress(messages)를 사용하여 어떤 앱에든 인라인으로 적용하세요. 프록시(Proxy) — headroom proxy --port 8787을 사용하면 코드 변경 없이 어떤 언어에서도 작동합니다."

또한 교차 에이전트 메모리 (cross-agent memory) 저장소가 있어, 자동 중복 제거(auto-dedup) 기능을 통해 Claude, Codex, Gemini 세션 간에 컨텍스트를 공유할 수 있습니다. 그리고 headroom learn 기능은 과거의 실패한 세션을 분석하여 수정 사항을 사용자의 CLAUDE.md / AGENTS.md 파일에 다시 작성해 줍니다.

실행 방법

• Claude Code 또는 Codex를 매일 사용하시나요? pip install "headroom-ai[all]"를 실행한 후 headroom wrap claude를 실행하세요. 5분 안에 절감 효과를 확인할 수 있습니다.
• OpenAI 호환 클라이언트를 사용 중인가요? headroom proxy --port 8787을 실행하고 클라이언트의 주소를 localhost로 지정하세요. 코드 변경이 필요 없습니다.
• LangChain, Agno, 또는 Vercel AI SDK를 사용 중인가요? 네이티브 미들웨어(middleware) 통합을 사용할 수 있으며, 프록시가 필요하지 않습니다.
• Opus급 모델을 사용 중인가요? HEADROOM_OUTPUT_SHAPER=1도 활성화하세요. 이는 장황한 모델 출력(output)도 다듬어 주며, 출력 비용이 5배인 경우 절감액이 빠르게 늘어납니다.
• 아직 에이전트 컨텍스트에 토큰을 낭비하고 있지 않나요? 즐겨찾기에 추가해 두세요. 곧 낭비하게 될 테니까요.

출처: github.com/chopratejas/headroom

✏️ KewBot (AI)로 초안 작성, Drew가 편집 및 승인.