Headroom 헤드룸: 클로드 코드 토큰 줄이는 압축 도구

Headroom 절감 대시보드 화면 위에 'Headroom, AI 코딩 에이전트 토큰 압축' 제목

클로드 코드에 로그 파일 하나 읽혔다가 사용량이 훅 줄어드는 걸 본 적 있으세요? 에이전트는 테스트 결과, 검색 결과, 에러 로그를 통째로 AI에게 넘기거든요. 오늘 오후 깃허브 급상승 목록에 그 부분을 줄여 주겠다는 도구가 올라와 있었습니다. 이름은 Headroom(헤드룸), 별이 7만 6천 개가 넘어요.

README 데모를 보면 1만 144토큰짜리 로그 덤프가 1,260토큰으로 줄었는데도 중요한 FATAL 줄은 그대로 남아 있어요. 숫자만 보면 솔깃하죠. 그래서 공식 README와 문서를 끝까지 읽어 보고, 어떤 도구인지와 실제로 어디서 효과가 있고 없는지까지 적어 봅니다.

Headroom 깃허브 저장소 headroomlabs-ai/headroom 첫 화면
별 약 7만 6천 개, Apache-2.0 (10월 20일) · 출처: Headroom 깃허브

Headroom은 어떤 도구인가요

한 줄로 말하면 AI에게 보내기 직전에 내용을 줄이는 중간 단계예요. 에이전트가 읽은 도구 출력·로그·RAG(검색해서 붙여 넣는 문서 조각)·파일·대화 기록을 AI 회사 서버로 보내기 전에 내 PC에서 압축합니다. README에는 “압축은 내 컴퓨터에서 돌고, 압축하려고 프롬프트나 파일 내용을 어디로 보내지 않는다”고 적혀 있어요.

Headroom 기본 정보 요약표
Headroom 한눈에 · 출처: Headroom 깃허브

저장소는 2026년 1월에 열렸고 라이선스는 Apache-2.0이라 무료로 쓸 수 있어요. 최신 버전은 10월 14일에 나온 v0.41.0입니다. 쓰는 방법은 네 가지예요. 파이썬·타입스크립트 코드 안에서 compress()를 부르는 라이브러리, 코드를 안 고치고 중간에 끼우는 프록시(중계 서버), 코딩 에이전트를 통째로 감싸는 headroom wrap, 그리고 MCP 서버. 일반 사용자에게 관련 있는 건 사실상 세 번째예요.

headroom wrap claude, 이게 핵심이에요

클로드 코드를 그냥 claude로 켜는 대신 아래처럼 켜면, Headroom이 내 PC에 8787번 포트로 프록시를 띄우고 클로드 코드가 그 길을 거쳐 앤트로픽 서버와 통신하게 바꿔 줍니다.

# 1. 설치 (CLI는 파이썬 패키지에만 들어 있어요)
uv tool install --python 3.13 "headroom-ai[all]"

# 2. 클로드 코드를 감싸서 실행
headroom wrap claude

# 3. 잘 연결됐는지 확인, 아낀 양 보기
headroom doctor
headroom dashboard

# 원래대로 되돌리기
headroom unwrap claude
터미널에서 headroom wrap claude 를 실행해 클로드 코드를 연결한 데모 화면
명령 한 줄로 프록시를 띄우고 클로드 코드를 연결 · 출처: Headroom 깃허브 README 데모

한 가지 알고 쓰셔야 할 게 있어요. wrap을 하면 코드 탐색용 MCP 도구인 Serena가 같이 설치되고, 클로드 코드의 경우 그 프로젝트의 ~/.claude.json에 등록됩니다. 빼고 싶으면 --code-memory none 옵션을 붙이면 되고, headroom unwrap으로 등록도 지워져요. npm의 headroom-ai는 타입스크립트 라이브러리일 뿐 headroom 명령이 없다는 점도 README에 따로 적혀 있습니다.

Headroom 공식 문서 빠른 시작 페이지
공식 빠른 시작 문서 · 출처: Headroom 공식 문서

저도 이 라즈베리파이에 설치해서 돌려 보려 했는데, 이번엔 작업 환경 권한 정책 때문에 외부 패키지 설치가 막혀서 직접 실행은 못 했어요. 아래 수치와 화면은 전부 공식 README와 문서, 데모 영상 기준입니다.

얼마나 줄어든다는 건가요?

저장소 설명에는 “코딩 에이전트 토큰 20% 감소, JSON은 60~95% 감소, 답은 그대로”라고 돼 있어요. README에 공개된 측정표는 실제 MCP 서버 출력 형식으로 만든 네 가지 상황입니다.

상황전후절감
코드 검색 결과 100개17,19913,59721%
서버 장애 디버깅55,95724,34057%
코드베이스 탐색58,80133,89542%
깃허브 이슈 분류46,06732,42930%

압축하는 데 걸리는 시간은 1만 토큰짜리 JSON에서 0.21ms, 10만 토큰에서 1.4ms라고 해요. 체감할 수준은 아니라는 얘기죠. 정확도도 같이 공개했는데 수학 문제(GSM8K) 100개에서 원본과 압축본 점수가 0.870으로 같았습니다. 개발자 스스로 “100문제 기준 ±0.03은 오차 범위라 좋아졌다고 볼 수 없다”고 적어 둔 점은 오히려 믿음이 가더라고요.

다만 이건 전부 개발자가 직접 잰 숫자예요. README도 “내 작업에 맞는 숫자는 headroom savings로 직접 확인하라”고 권합니다.

어떤 데이터는 거의 안 줄어요

공식 문서에 ‘한계(Limitations)’ 페이지가 따로 있는데, 이게 이 도구에서 제일 솔직한 부분이에요. 반복이 많은 데이터일수록 많이 줄고, 이미 빽빽한 글은 거의 안 줄어듭니다.

데이터 종류별 Headroom 압축률 요약표
공식 문서 한계 페이지의 표본 측정치 · 출처: Headroom 공식 문서

눈여겨볼 건 아래쪽 두 줄이에요. 소스 코드는 정확성을 지키려고 대부분 그대로 통과시키고, 50토큰 미만의 짧은 메시지는 압축하지 않습니다. 이미지·시스템 프롬프트도 건드리지 않아요. 문서도 “짧은 대화나 파일 읽기·쓰기 위주 작업에선 효과가 적다”고 분명히 적어 뒀고, 위 표의 수치는 표본 하나로 잰 방향성 수치라고 밝혀 둡니다.

Headroom 공식 문서 한계 페이지
어디서 효과가 적은지 문서가 직접 적어 둠 · 출처: Headroom 공식 문서

원본을 버리는 건 아니에요. CCR이라는 방식으로 원본을 내 PC에 캐시해 두고, AI가 전체 내용이 필요하면 headroom_retrieve 도구로 다시 꺼내 볼 수 있게 해 둡니다. 압축 때문에 중요한 줄을 놓칠까 봐 걱정되는 부분을 이렇게 메운 거죠.

Headroom 대시보드 누적 절감 화면
아낀 토큰과 비용을 날짜별로 보여 줌 · 출처: Headroom 깃허브 README 데모

클로드 코드 말고 다른 에이전트도 되나

됩니다. README 표 기준으로 코덱스, Grok CLI, 에이더, 코파일럿 CLI, VS Code 코파일럿, 오픈코드, Cline, Continue, Goose 등이 headroom wrap을 지원해요. 커서와 ZCode는 자동이 아니라 프록시 주소를 직접 설정에 넣어야 하고요.

Headroom 이 지원하는 코딩 에이전트 목록 표
headroom wrap 으로 감쌀 수 있는 에이전트 · 출처: Headroom 깃허브 README

압축 말고도 기능이 몇 개 더 붙어 있어요. 클로드·코덱스·제미나이·Grok이 같이 쓰는 공용 메모리, 그리고 headroom learn. 지난 세션에서 실패한 부분을 분석해서 “이 프로젝트에선 이렇게 하라”는 메모를 기본으로 CLAUDE.local.md(깃에 안 올라가는 파일)에 적어 줍니다. AI가 답을 쓰는 쪽(출력 토큰)을 줄이는 기능도 있는데 이건 기본으로 꺼져 있어요.

headroom learn 이 지난 세션을 분석해 메모를 만드는 데모 화면
실패한 세션을 읽고 고칠 점을 적어 줌 · 출처: Headroom 깃허브 README 데모

깔기 전에 확인할 것 세 가지

첫째, 익명 사용 통계가 기본으로 켜져 있어요. 압축률, 횟수, 모델 이름, 운영체제 같은 정보를 보내고 프롬프트·코드·파일 경로는 안 보낸다고 적혀 있습니다. 싫으면 HEADROOM_TELEMETRY=off나 DO_NOT_TRACK=1로 끌 수 있어요.

Headroom 텔레메트리 안내와 오픈소스·엔터프라이즈 비교표
익명 통계는 기본으로 켜져 있어요 · 출처: Headroom 깃허브 README

둘째, 클로드 코드의 원격 제어(Remote Control) 기능은 Headroom을 거치면 쓸 수 없어요. 공식 문서 문제 해결 페이지에 “api.anthropic.com으로 직접 붙을 때만 된다”는 메시지가 그대로 나와 있고, 해결책은 그 세션만 Headroom 없이 켜는 겁니다.

셋째, 오픈소스는 혼자 쓰는 개발자용이고 팀 관리·모델 자동 전환·프롬프트 인젝션 차단은 유료 엔터프라이즈 쪽이에요. 저장소 코드는 계속 Apache-2.0으로 공개된다고 밝혀 뒀습니다. 설치 파일(휠)은 윈도우·맥·리눅스용이 모두 배포되고, 파이썬 3.10 이상이 필요해요.

개인적으로는 한계를 문서로 먼저 밝혀 둔 점이 마음에 들었어요. 비슷한 문제를 다른 방식으로 푸는 context-mode와 비교해 보셔도 좋겠고요. 다만 클로드 Pro·Max처럼 정액제를 쓰고 있다면 돈이 줄어드는 게 아니라 같은 사용 한도 안에서 조금 더 오래 쓰는 쪽에 가까울 거라고 봅니다. 로그와 테스트 결과를 많이 읽히는 분이라면 한 번 감싸 보고 headroom dashboard로 실제 숫자를 보는 게 제일 확실하겠죠. 여러분은 에이전트 쓰다가 토큰 한도에 걸린 적, 하루에 몇 번이나 되세요? 클로드 코드 관련 글은 태그에 모아 두고 있어요.


출처
· Headroom 깃허브 저장소·README
· Headroom 릴리스 (v0.41.0)
· Headroom 공식 문서 — 빠른 시작
· Headroom 공식 문서 — 한계
· Headroom 공식 문서 — 문제 해결
(2026년 10월 20일 확인)

컴퓨터가 고장 났다면 부산 컴퓨터수리 · 출장수리 부컴에 맡겨 주세요. 부산·울산·김해·양산 어디든 직접 방문합니다.

함께 보면 좋은 글

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다