github: https://github.com/chopratejas/headroom

도구 출력, 로그, 파일, 대화 기록을 LLM에 보내기 전에 60~95% 압축해 토큰 비용과 지연을 줄여 줘요. 압축이 로컬에서 이뤄져 데이터가 외부로 나가지 않는다는 점이 핵심입니다.

1 Install

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

기본 명령어는 아래와 같아요.

headroom wrap claude                    # wrap a coding agent

Claude Code를 욜로 모드로 실행하려면 zshrc에 별칭을 추가하면 돼요.

vi ~/.zshrc
alias headroomyolo='headroom wrap claude -- --dangerously-skip-permissions'

영구 프록시로 실행하기 (한 번 설정하면 계속)

headroom이 이미 설치돼 있다면, 영구 서비스로 한 번 등록해 두는 게 여러 터미널을 오갈 때 가장 깔끔해요. 아래 한 줄이 launchd 서비스 기동과 ~/.zshrc(또는 ~/.bashrc) 라우팅 블록 주입, claude 연결까지 한 번에 끝냅니다.

headroom install apply --preset persistent-service --runtime python --scope user --providers auto --port 8787 --mode token

기본 포트는 8787이에요. 포트를 바꾸고 싶다면 headroom proxy --port 8282로 실행하면 돼요.

이어서 도구 스키마가 미리 로딩되는 걸 막는 한 줄을 보강해요. 토큰 절약을 유지하려면 필요합니다.

echo 'export ENABLE_TOOL_SEARCH="true"' >> ~/.zshrc

설정을 마쳤으면 새 터미널을 엽니다. 기존 터미널에는 환경변수가 반영되지 않아요. 새 창에서는 claude만 쳐도 요청이 프록시를 거쳐 갑니다. 제대로 됐는지는 echo $ANTHROPIC_BASE_URL이 http://127.0.0.1:8787로 찍히고 아래 health 확인이 UP인지로 판단하면 돼요.

몇 가지 참고할 점이 있어요. 그 기기가 Linux면 같은 명령이 launchd 대신 systemd 서비스로 설치됩니다. 그리고 claude는 해당 기기에서 한 번 로그인(자체 인증)이 돼 있어야 해요. 프록시는 인증을 대신하지 않고 그대로 전달만 합니다. 되돌리려면 headroom install remove를 쓰면 됩니다.

프록시가 살아 있는지 확인하기

가장 빠른 "살았나?" 한 줄은 readyz 확인이에요. 200이 떨어지면 살아 있는 겁니다.

curl -sf http://127.0.0.1:8787/readyz && echo UP

더 자세한 내부 상태가 궁금하면 health 엔드포인트를 봅니다.

curl -s http://127.0.0.1:8787/health | python3 -m json.tool

이 밖에 상황별로 쓰는 확인 명령은 이렇습니다.

배포 상태: headroom install status로 포트와 모드, healthy 여부를 봐요. 다만 실제로 돌고 있는데도 "Status: stopped"로 잘못 표기될 때가 있으니 위 readyz를 함께 확인하세요.
성능과 절감 리포트: headroom perf로 토큰 절감 리포트를 다시 뽑을 수 있어요.
보조 확인: launchctl list | grep headroom으로 서비스 등록 여부를, lsof -iTCP:8787 -sTCP:LISTEN으로 포트 점유를 확인해요.

정상적으로 실행되면 브라우저에 Serena 대시보드가 열립니다.

Serena 대시보드

대시보드는 검색-편집에 쓰는 도구(tool)가 아니에요. Serena MCP 서버가 띄우는 웹 모니터링 창으로, Serena를 터미널에서 실행하면 함께 뜹니다.

실제로 Serena MCP 프로세스(PID 69934)가 해당 포트를 사용하고 있는 것도 확인했어요.

Serena 자체는 코드를 의미 단위로 다루는 도구 모음이에요. 파일 전체를 읽는 대신 심볼(함수-클래스) 단위로 찾고 고쳐서 토큰을 아껴요. 실제 "도구"는 find_symbol, get_symbols_overview, find_referencing_symbols, replace_symbol_body 등이며 이 세션에서도 mcp__serena__*로 로드됩니다. 대시보드 화면은 이 도구들의 상태, 버전, 활성 프로젝트, 로그만 보여줘요.

Serena는 MCP 서버라 자체 화면 없이 백그라운드에서 돌아가요. 대시보드는 "지금 Serena가 무슨 일을 하고 있나"를 사람이 들여다보는 유일한 창이에요. 용도는 크게 네 가지입니다.

로그 실시간 추적: find_symbol 같은 도구가 언제 호출됐고 어떤 작업을 했는지 확인해요. 디버깅하거나 "Claude가 코드에 무슨 짓을 했나" 살펴볼 때 유용해요. 대시보드에 get_log_messages 엔드포인트가 실제로 떠 있는 것도 확인했습니다(HTTP 415 — 존재하되 형식 필요).
현재 상태 확인: 스크린샷의 CURRENT CONFIGURATION 영역에서 버전, 활성 프로젝트, 언어, 등록된 프로젝트, 사용 가능한 도구 목록을 볼 수 있어요.
서버 종료: 대시보드에서 Serena MCP 서버를 직접 끌 수 있어요.
연결 상태 확인: 스크린샷의 "Ready to accept connections"처럼 IDE-에이전트 연결 가능 여부를 보여줘요.

검색과 편집은 Claude가 도구로 처리해요. 대시보드는 그 과정을 살펴보고 관리하는 관제판에 가깝습니다. 대시보드 자체가 토큰을 아껴 주는 것은 아니고 Serena가 파일 전체 대신 심볼 단위로 읽기 때문에 절약 효과가 생겨요.

압축 토큰 절약을 확인하는 곳

작업을 마친 뒤 절약 효과를 확인하는 방법은 세 가지예요. 각각 용도가 조금씩 다릅니다.

가장 정확한 CLI 명령은 headroom perf예요. ~/.headroom/logs/proxy.log를 읽어 토큰 절약과 압축 효과, 캐시 적중률, 개선 권고까지 보여줘요. 기본 조회 범위는 최근 7일입니다. 방금 작업한 내역만 보려면 headroom perf --hours 1, 기계 판독용 결과가 필요하면 headroom perf --format json을 쓰면 돼요. 저장소 작업을 끝낸 뒤 누적 효과를 확인할 때 가장 잘 맞습니다.

세션 단위 실시간 수치는 Claude Code 안에서 headroom MCP의 headroom_stats 도구로 확인해요(앞 답변에서 호출했던 그것). 현재 세션의 압축 건수, 압축률, 비용 절감을 바로 보여줘요.

원천 데이터는 ~/.headroom/proxy_savings.json(누적 요약)과 ~/.headroom/logs/proxy.log(원시 로그)에 있어요. perf와 headroom_stats는 이 파일들을 가공해 결과를 보여줘요.

한 가지 헷갈리기 쉬운 부분이 있어요. CLI에는 headroom stats나 headroom gain 같은 명령이 없어요(직접 실행해 No such command 확인). CLI는 perf, MCP 도구는 headroom_stats로 이름이 다릅니다. 압축 효과는 큰 도구 출력과 긴 컨텍스트가 쌓여야 나타나요. 실제 저장소에서 파일 여러 개를 읽고 코드를 분석한 뒤 headroom perf --hours 1로 확인하면 의미 있는 절약 수치가 나옵니다.

headroom perf에서 토큰 절약 리포트를 확인할 수 있어요. 실제로 써 보니 초기 단계에서는 압축보다 캐시가 토큰을 더 많이 절약하고 있었습니다.

여기서 말하는 캐시는 headroom의 로컬 캐시가 아니에요. Anthropic(클로드 API) 서버의 "프롬프트 캐싱(prompt caching)"이에요. headroom이 만든 기능이 아니라 Claude Code가 원래 사용하던 API 기능이고 headroom은 그 효과를 측정해 보여줍니다.

프롬프트 캐싱이란

대화를 한 번 주고받을 때마다 똑같은 앞부분이 Claude에 반복해서 전송돼요. 시스템 프롬프트, 도구 정의, 지금까지의 대화 기록 전체가 여기에 해당해요.

프롬프트 캐싱은 반복되는 앞부분(prefix, 프롬프트 앞쪽 고정 구간)을 Anthropic 서버가 기억해 두는 기능이에요. 다음 요청에 같은 앞부분이 들어오면 처음부터 다시 계산하지 않고 캐시에서 꺼내 약 90% 싼 값으로 읽습니다.

리포트에 나온 두 숫자가 바로 이 부분을 가리켜요. 캐시 쓰기(cache write)는 내용을 캐시에 처음 저장할 때라 평소보다 약간 비싸요. 캐시 읽기(cache read)는 저장한 내용을 재사용할 때라 비용이 매우 저렴합니다. 적중률 76%라면 이번 요청의 입력 토큰 가운데 76%를 새로 계산하지 않고 캐시에서 읽은 거예요.

압축과 캐시의 차이

"초기에는 압축보다 캐시가 토큰을 절약한다"는 관찰은 맞아요. 다만 둘이 아끼는 대상은 다릅니다.

압축은 전송하는 토큰 개수 자체를 줄여요(이번 리포트의 47만 7천 토큰 감소).
캐시는 토큰 개수는 그대로 두고 해당 토큰의 단가를 약 90% 낮춰요.

엄밀히 말하면 캐시는 "토큰을 줄인다"기보다 "토큰 비용을 줄인다"고 보는 편이 정확해요. 앞선 세션 통계에서 절감액 대부분이 압축($0.01)이 아니라 캐시($0.53)에서 나온 이유도 여기에 있어요. 시스템 프롬프트와 대화 기록은 요청할 때마다 반복되니 캐시는 곧바로 큰 효과를 냅니다. 반면 압축은 큰 파일 출력이 쌓이고 학습 엔진이 익어야 효과가 커져요.

headroom은 캐시에 어떻게 관여하나

headroom이 캐시를 직접 만들지는 않아요. 대신 프롬프트 앞부분을 흔들지 않고 안정적으로 유지(prefix stability, 앞부분 안정성)해 캐시가 깨지지 않도록 돕습니다.

리포트의 "불안정 23/98건"과 "대화가 길어질수록 캐시 안정화"가 그 지표예요. 다만 압축이 프롬프트 앞부분을 지나치게 건드리면 캐시가 깨져 오히려 손해가 나요. 그래서 headroom은 압축과 캐시 유지 사이에서 균형을 잡으려 합니다. "오래된 읽기 출력만 골라서 압축"하라는 권고가 나온 배경도 이 때문이에요.

리포트의 캐시는 Anthropic 서버의 프롬프트 캐싱이에요. 토큰 수가 아니라 토큰 비용을 약 90% 낮춘다는 점이 핵심이에요.

TOIN

TOIN은 "Tool Output Intelligence Network(도구 출력 인텔리전스 네트워크)"의 약자예요. 어떤 도구 출력에 어떤 압축이 잘 적용되는지 기록하며 배우는 학습 장부입니다. 소스 첫 줄에 적힌 "observation-only"가 핵심이에요. 당장의 압축 방식을 바꾸지 않고 관찰 데이터부터 쌓은 뒤, 그 데이터로 다음 압축을 개선해요.

어떻게 학습하나

headroom은 도구 출력을 압축할 때마다 "어떤 종류의 출력을, 어떤 전략으로, 얼마나 줄였고, 그게 나중에 다시 필요했는지"를 디스크(~/.headroom/toin.json)에 기록해요. 데이터가 충분히 쌓이면 별도 명령(toin_publish)이 이를 집계해 추천 파일(recommendations.toml)을 만듭니다. 프록시는 다음에 시작할 때 이 파일을 읽고 "이런 출력엔 이 전략을 써라"라는 추천을 적용해요. 쓸수록 성능을 개선하는 구조이고 모든 기록은 로컬에 남아 외부로 나가지 않아요.

"패턴"이란 무엇인가

여기서 패턴은 형태가 비슷한 도구 출력을 묶은 그룹이에요. 인증 모드, 모델 종류, 도구 출력의 모양을 요약한 해시값(서명, 내용 자체가 아니라 형태만)을 기준으로 묶습니다. 같은 모양의 출력은 같은 패턴으로 보는 셈이에요.

TOIN은 각 패턴에서 세 가지를 학습해요.

최적 압축 전략: 해당 출력에 어떤 방식이 가장 잘 맞는지 판단해요(소스의 optimal_strategy와 전략별 성공률). 리포트의 "전략 분포: 10개 default, 2개 kompress"가 여기에 해당해요. 19개 패턴 가운데 10개는 아직 기본 전략을 쓰고 2개는 더 공격적인 kompress 전략이 낫다고 학습한 상태입니다.
다시 꺼내지는 비율(retrieval rate, 회수율): 압축해 둔 내용을 나중에 Claude가 다시 찾는 빈도예요. 자주 찾는 내용은 함부로 압축하면 안 되는 중요한 정보라는 신호입니다. 거의 찾지 않는 내용은 안전하게 압축해도 돼요. 리포트의 "회수 3건(10.7%)"은 압축한 내용 중 10.7%만 다시 꺼냈다는 의미라, 대체로 적절하게 압축하고 있어요.
표본 수(sample size): 위 판단을 믿을 만큼 관찰 데이터가 쌓였는지를 보여줘요.

왜 아직 "워밍업"인가

리포트의 "0/12 패턴이 10샘플 도달" 상태에서는 추천을 만들 만큼 데이터가 쌓인 패턴이 아직 하나도 없어요. 표본이 적을 때 "이 출력엔 이 전략이 최적"이라고 단정하면 결론이 우연(노이즈)에 좌우돼요. 그래서 일정한 관찰 수를 넘기 전까지 추천을 보류하도록 보수적으로 설계돼 있습니다(프로덕션 집계 기준은 패턴당 50건).

앞서 "데이터를 더 쌓자"고 선택한 이유도 여기에 있어요. 긴 작업 세션을 더 진행하면 패턴별 표본이 쌓이고 추천도 만들어지기 시작해요.

수집은 자동, 적용은 수동

데이터는 자동으로 쌓이지만 학습 결과가 실제 압축에 저절로 반영되지는 않아요. "충분히 사용 → headroom perf로 확인 → 직접 publish 명령 실행 → 프록시 재시작" 순서는 사용자가 직접 밟아야 해요. 소스와 실제 파일을 확인한 근거를 하나씩 살펴볼게요.

데이터 수집은 자동

패턴은 완전히 자동으로 쌓여요. 실제로 ~/.headroom/toin.json 파일이 73KB로 존재하며 방금(6월 10일 07:23) 갱신됐어요. 이 파일이 학습 장부입니다. 프록시는 도구 출력을 압축할 때마다 내용을 자동으로 기록해요.

프록시 안에서는 TOIN(도구 출력 학습 엔진) 통계를 로그에 남기는 백그라운드 작업도 5분마다 돌아가요(_log_toin_stats_periodically, 300초 간격). 평소처럼 사용하기만 해도 별도 조작 없이 표본이 계속 쌓여요.

학습 결과 적용은 수동

쌓인 학습 결과를 실제 압축에 반영하려면 사용자가 두 가지 작업을 해야 해요.

먼저 결과를 집계해야 해요. 소스에서 반복해서 "오프라인 집계기(offline aggregator)"라고 설명하듯, 학습 결과로 추천 파일(recommendations.toml)을 만드는 자동 스케줄은 없어요. 다음 명령을 직접 실행해야 파일이 생깁니다. grep으로 자동 publish 코드가 없다는 점도 확인했어요.

python -m headroom.cli.toin_publish

그다음은 추천 파일 적용이에요. 이 파일은 "프록시가 시작할 때 한 번 읽는다(reads it once at startup)"고 명시돼 있어요. 실행 중 다시 읽는 핫 리로드(hot reload, 재시작 없이 갱신) 방식은 아닙니다. 추천 파일을 새로 만든 뒤 프록시를 재시작해야 학습 결과가 반영돼요.

패턴이 쌓였는지 확인하는 방법

가장 간단한 방법은 headroom perf의 "TOIN Learning"과 "TOIN Highlights" 섹션을 보는 거예요. 여기서 패턴 수, 전략 분포(default/kompress), "몇 개 패턴이 10샘플에 도달했는지"를 확인해요.

집계 과정을 자세히 보고 싶다면 점검 모드로 실행하면 돼요.

python -m headroom.cli.toin_publish --verbose

이 명령은 어떤 패턴이 문턱을 넘었는지 보여줘요. 원본 데이터는 ~/.headroom/toin.json에 있고 5분 단위 통계는 ~/.headroom/logs에 남아요.

여기서 문턱값이 두 개라는 점은 꼭 기억해 두는 편이 좋아요. headroom perf 리포트의 "10샘플 도달"은 후보 자격을 나타내요. 실제 추천 파일을 만드는 publish 명령의 기본 문턱은 패턴당 50건(--min-observations 50)입니다. 리포트에 10샘플 패턴이 보이더라도 기본값으로 publish하면 50건을 넘긴 패턴만 추천에 들어가요. 더 일찍 반영하고 싶다면 --min-observations 값을 낮춰 실행하면 됩니다.

실제 절차는 단순해요. 평소처럼 긴 작업을 계속하면 데이터가 자동으로 쌓여요. headroom perf에서 10샘플 또는 목표한 50건에 도달한 패턴이 보이고 절약 효과가 정체되면 python -m headroom.cli.toin_publish로 추천 파일을 만든 뒤 프록시를 재시작하면 됩니다. 그 시점이 오면 정확한 명령과 재시작 방법을 함께 확인해 드릴게요.

한마디로 수집은 자동, 적용은 수동이에요. headroom perf로 상태를 확인한 뒤 publish 명령을 실행하고 프록시를 재시작해야 학습 결과가 실제 압축에 반영돼요.

참고로 이름이 비슷한 headroom learn 명령은 TOIN과 다른 기능이에요. headroom learn은 과거 도구 호출의 "실패"(잘못된 경로, 없는 모듈 등)를 분석해 같은 문제가 반복되지 않게 해요. TOIN은 압축 최적화를 학습합니다.

TOIN은 도구 출력별 최적 압축 전략과 회수율을 관찰하며 배우는 로컬 장부예요. 표본이 패턴당 임계값을 넘으면 추천을 만들고 프록시 압축을 개선해요.

headroom 을 이용하여 proxy 연결을 통한 토큰 비용 절감 비교