Claude Code는 매번 전체 컨텍스트 재전송 — Headroom이 줄입니다

Claude Code에서 메시지를 보낼 때마다, 이 도구는 새로 입력한 한 줄만 보내지 않습니다. 지금까지의 전체 대화를 다시 업로드합니다. 세션이 길어지면 이 동작이 조용히 토큰 비용의 대부분을 차지하게 됩니다.

Claude Code가 매번 전체 대화를 다시 보내는 이유

Claude Code는 API 호출 사이에 상태를 유지하지 않기 때문에, 전체 메시지 기록, 모든 도구 출력, MCP 서버 메타데이터를 매번 나가는 요청에 붙입니다. Anthropic의 자체 비용 문서도 누적된 컨텍스트에 따라 토큰 지출이 늘어난다고 확인합니다. 세션이 길수록 모델이 이미 본 내용을 다시 보내는 데 더 많은 비용을 내게 됩니다 . 프롬프트 캐싱이 이를 완화하기는 합니다. Anthropic은 안정적인 prefix에 대해 대략 90%의 읽기 할인을 제공합니다. 하지만 도구 결과, 파일 읽기, 가변적인 JSON 페이로드가 계속 prefix를 바꾸면서 캐시를 깨고, 오래된 출력이 이후 턴에서 전체 입력 요율로 다시 과금되게 만듭니다 .

Headroom은 provider에 도달하기 전에 나가는 페이로드를 가로채는 로컬 미들웨어 계층입니다. 요청은 Input Received → ContentRouter → Compressed → Pre-Send로 이어지는 단계형 lifecycle을 지나며, 로그, 검색 덤프, 반복된 파일 읽기처럼 중복되는 블록이 전송 중 제거되거나 압축됩니다 . 현재 `headroom-ai` 패키지는 2026년 7월 29일에 공개된 0.33.0 버전입니다 .

효과는 콘텐츠에 따라 달라집니다. Headroom의 README는 코딩 에이전트에서 전체적으로 15~20% 절감을 언급하며, JSON 배열과 빌드 로그 같은 구조화된 페이로드는 70~95%까지 줄어든다고 설명합니다 . 다만 독립적인 기대치는 보수적으로 잡는 편이 좋습니다. 한 실무자는 한 달 사용 후 실제 절감률이 약 26%였다고 보고했습니다 .

Claude Code에 Headroom을 붙이려면 필요한 것

Headroom은 두 가지 런타임 전제 조건만 있으면 Claude Code에 붙일 수 있고, API 키 변경은 필요 없습니다. 설치 경로는 하나를 고르면 됩니다. pip install "headroom-ai[all]"을 쓰려면 Python 3.10 이상, npm install headroom-ai를 쓰려면 Node 18 이상이 필요합니다 . 현재 PyPI 패키지는 headroom-ai 0.33.0 버전이며 2026년 7월 29일에 릴리스되었으므로, 새로 설치하면 이 흐름에서 설명하는 compressor stack이 이미 포함됩니다 .

빌드 단계는 없습니다. Windows, Linux(x86-64 및 aarch64), macOS(x86-64 및 ARM64)용 prebuilt wheel이 제공되므로, 해당 플랫폼에서는 컴파일러 toolchain 없이 설치가 해결됩니다 .

Anthropic 인증 정보는 그대로 둡니다. Headroom은 localhost에서 실행되며 Claude Code가 api.anthropic.com 대신 127.0.0.1을 바라보게 리디렉션합니다. 키는 여전히 upstream 인증에 쓰이고, base URL만 바뀝니다 .

무언가 연결하기 전에 먼저 확인하세요. headroom --version은 0.33.0을 출력해야 합니다 . 다음 단계에서 붙인 뒤에는 실제 Claude Code 호출 한 번으로 왕복이 끝까지 되는지 확인할 수 있습니다.

Claude Code에 Headroom 끼워 넣기

Claude Code 트래픽을 Headroom으로 보내는 방법은 세 가지입니다. 수동 작업이 적은 순서부터 많은 순서로 정리했습니다. 무엇을 압축할지 얼마나 직접 제어하고 싶은지에 따라 하나를 고르면 됩니다.

경로 A — agent wrap(코드 변경 없음). headroom wrap claude를 실행합니다. Headroom이 Claude Code를 subprocess로 실행하고, 모든 페이로드가 사용자의 머신을 떠나기 전에 process 안에서 압축합니다. 설정의 다른 부분은 바뀌지 않습니다 . 어떤 블록이 중요한지 따지지 않고 바로 절감 효과를 얻고 싶다면 가장 빠른 경로입니다.

경로 B — 투명한 로컬 proxy. headroom proxy --port 8787을 시작한 다음, claude를 호출하기 전에 ANTHROPIC_BASE_URL=http://localhost:8787을 설정합니다. 모든 트래픽은 소스나 config 파일을 건드리지 않고 Headroom을 통과하며, 요청은 기존 키로 인증된 상태로 Anthropic upstream에 계속 전달됩니다 .

경로 C — MCP 서버. headroom mcp install을 실행해 headroom_compress, headroom_retrieve, headroom_stats를 호출 가능한 도구로 노출합니다. 모든 트래픽을 압축하는 대신 Claude가 필요할 때 특정 블록을 압축하고, 1시간 TTL 안에서 원본을 다시 가져올 수 있습니다 . 이 방식은 Claude가 언제 호출할지 선택한다는 비용을 감수하는 대신, 블록 단위 제어권을 줍니다.

압축이 안전하게 동작하는 이유는 CCR, 즉 Compress-Cache-Retrieve입니다. Headroom은 원본 콘텐츠를 content hash 아래 로컬에 저장하고, 모델에는 더 짧은 표현과 retrieval 수단을 함께 전달합니다. 문서의 예시는 grep 출력 5,000줄을 12,000토큰에서 3,200토큰으로 줄입니다. 73.3% 절감이며, 전체 원본은 1시간 동안 headroom_retrieve로 다시 가져올 수 있게 대기합니다 .

어떤 경로를 쓰든 ContentRouter는 각 블록의 유형(JSON, 로그, diff, HTML, 일반 텍스트)을 자동 감지하고 알맞은 compressor로 넘깁니다. JSON에는 SmartCrusher, 소스 코드(Python, JS/TS, Go, Rust, Java, C/C++)에는 AST를 인식하는 CodeCompressor, 서술형 텍스트에는 149M parameter extractive prose model인 Kompress-v2-base가 쓰입니다 . 사용자가 직접 콘텐츠에 태그를 붙일 필요는 없습니다. 라우팅은 자동입니다.

Headroom이 압축을 아예 건너뛰는 경우

Headroom은 모든 것을 압축하지 않으며, 무엇을 그대로 두는지 알아야 현실적인 기대치를 잡을 수 있습니다. 대략 300토큰 미만의 메시지는 그대로 통과합니다. 이 정도 규모에서는 압축기 오버헤드가 절감분보다 크기 때문입니다 . 소스 코드 압축은 선택 사항이며 기본값은 꺼짐이고, 짧은 대화식 교환은 중앙값 기준 4.8%만 압축됩니다 . 이미지, grep/검색 결과, 시스템 프롬프트도 파이프라인을 우회할 수 있습니다.

효과는 길고 도구 사용이 많은 세션에 집중됩니다. 25~50턴의 에이전트형 대화는 56~81% 압축되지만, 단일 턴이나 세션 초반 호출에서는 감소폭이 거의 0에 가까울 수 있습니다 . 60~95%라는 대표 수치는 구조화된 페이로드, 즉 JSON 배열과 빌드/테스트 로그에만 적용되며, 산문이 많은 턴에는 해당하지 않습니다. README 자체의 코딩 에이전트 수치도 15~20%입니다 .

독립적인 신호는 많지 않습니다. 한 실무자는 한 달 뒤 실제 환경에서 약 26% 절감됐다고 보고했습니다 . 마케팅에서 제시하는 범위보다 훨씬 낮은 수치입니다. 공개된 모든 숫자는 Headroom 자체 제품군에서 나온 것이며, 전체 코퍼스 압축률 66.1%를 측정한 v0.5.18 재현 가능 벤치마크도 여기에 포함됩니다 . 2026년 8월 현재 독립적이고 동료 검토를 거친 벤치마크는 없습니다. 벤더 수치는 상한선으로 보고, 플랜을 두 배로 아낄 수 있다고 가정하기 전에 headroom_stats로 자신의 작업 부하를 먼저 측정하세요.

처음 연결한 뒤 살펴볼 기능

압축이 문제없이 동작하기 시작하면, 네 가지 기능으로 Claude Code 워크플로에서 Headroom의 활용 범위를 넓힐 수 있습니다. 가장 유용한 것은 headroom learn입니다. 과거 Claude Code 트랜스크립트를 읽고, 반복되는 오류와 패턴을 찾아내며, 정리된 결과를 CLAUDE.md에 직접 기록하는 오프라인 실패 마이닝 단계입니다 Headroom README. 실시간 트래픽이 아니라 저장된 세션에서 실행되므로, 대화 중 추가 토큰 비용이 들지 않습니다.

Claude와 Codex를 병렬로 사용한다면, Headroom은 두 에이전트에 걸쳐 공유 압축 코퍼스를 유지하고 겹치는 컨텍스트를 중복 제거합니다. 그래서 같은 파일 읽기와 도구 출력이 두 번 저장되거나 다시 전송되지 않습니다 Headroom README. 두 에이전트가 같은 저장소를 동시에 탐색할 때 특히 중요합니다.

대화에서 나가지 않고 이를 측정하려면, headroom_stats MCP 도구를 호출해 턴별 압축률과 누적 토큰 차이를 확인하세요 Claude plugin manifest. 마지막으로 CacheAligner를 조정하세요. CacheAligner는 KV 캐시 접두사를 깨뜨리는 변동성 콘텐츠를 표시하는 구성 요소입니다. 더 많은 접두사가 안정적으로 유지되도록 설정하면, 압축에 더해 Anthropic의 약 90% 캐시 읽기 할인까지 받을 수 있어 두 절감 효과가 함께 쌓입니다.

구체적인 다음 단계는 이렇습니다. 프록시를 통해 연결하고, headroom_stats를 켠 뒤, 실제 세션 하나를 실행하세요. 그런 다음 headroom learn과 CacheAligner 조정이 자신의 코드베이스에서 설정 비용을 감당할 만큼 가치 있는지 판단하면 됩니다.

자주 묻는 질문

Headroom은 Claude의 답변을 바꾸거나 정보를 버리나요?

아니요. Headroom은 정보를 손실하는 방식이 아니라 되돌릴 수 있는 방식으로 설계되어 있습니다. CCR(Compress-Cache-Retrieve) 구조는 원본 콘텐츠를 해시 기준으로 로컬에 저장하고, 모델에는 압축된 표현과 검색 수단을 함께 전달합니다. 그래서 세부 정보가 필요할 때 Claude가 headroom_retrieve를 호출해 1시간 TTL 안에서 전체 원문을 가져올 수 있습니다 . 문장 압축기인 Kompress-v2-base는 추출식 방식이며, 7,037개의 보류 평가 예제에서 F1 0.918, 반드시 보존해야 하는 항목의 재현율 0.974를 기록했습니다. 즉 강제로 유지해야 하는 구간이 누락되는 경우가 매우 적다는 뜻입니다 .

실제 Claude Code 세션에서 Headroom은 얼마나 절약해 주나요?

작업 유형에 따라 크게 달라집니다. README는 코딩 에이전트 전반에서 15~20% 정도의 완만한 절감을 주장하지만, 구조화된 페이로드에서는 훨씬 큰 효과가 나옵니다. Headroom 자체 벤치마크 기준 JSON 배열은 70~90%, 빌드/테스트 로그는 80~95%까지 줄어듭니다 . 짧은 대화형 교환은 중앙값 기준 4.8% 압축되는 반면, 25~50턴의 에이전트형 세션은 56~81% 압축됩니다 . 한 실무자는 한 달 사용 후 실제 환경에서 약 26% 절감됐다고 보고했습니다 . 의미 있는 절감은 세션에 도구 출력 이력이 상당히 쌓인 뒤부터 나타납니다.

Anthropic API 키로 Headroom의 로컬 프록시를 실행해도 안전한가요?

같은 머신에서 사용하는 경우에는 그렇습니다. 프록시는 127.0.0.1에만 바인딩되므로 Claude Code에서 Headroom으로 가는 트래픽은 사용자의 머신 밖으로 나가지 않습니다. 이후 Headroom이 요청을 Anthropic API로 전달합니다 . 저장소는 Apache 2.0 라이선스이며 GitHub에서 전체 코드를 확인할 수 있고, Headroom 자체는 자격 증명을 저장하지 않습니다 .

프록시 모드, 랩 모드, MCP 모드는 무엇이 다른가요?

프록시 모드(headroom proxy와 ANTHROPIC_BASE_URL 오버라이드)는 모든 트래픽을 투명하게 가로챕니다. 코드 변경이 필요 없고 어떤 도구와도 함께 쓸 수 있습니다. 랩 모드(headroom wrap claude)는 Headroom을 앞단에 둔 상태로 Claude Code를 하위 프로세스로 실행하며, CLI 사용에는 가장 단순한 경로입니다. MCP 모드(headroom mcp install)는 모든 요청을 가로채는 대신, Claude가 도구 호출을 통해 필요한 때에만 선택적으로 압축하게 합니다. 문서에는 grep 출력에서 12,000 → 3,200 토큰으로 줄어든 대표 사례가 언급되며, 원본은 로컬에 1시간 동안 보관됩니다 .

Headroom은 Claude Code가 아닌 다른 편집기에서도 작동하나요?

네. 문서화된 통합에는 프록시 또는 랩 모드를 통한 Cursor, Aider, Cline, Continue, Goose가 포함되며, ANTHROPIC_BASE_URL을 따르는 모든 HTTP 클라이언트는 프록시 모드와 함께 사용할 수 있습니다 . 라이브러리 측면에서는 Headroom이 compress(messages) API를 통한 Vercel AI SDK 미들웨어와 LangChain, Agno, Strands 통합을 문서화하고 있습니다 .

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기