헤드룸으로 클로드 코드가 읽는 도구 출력·로그를 압축해 토큰 줄이는 법

헤드룸(Headroom)은 도구 출력, 로그, 파일, 대화 기록을 모델에 보내기 전에 내 컴퓨터에서 압축해 주는 오픈소스 도구다. 클로드 코드(Claude Code)나 코덱스 앞에 로컬 프록시로 끼워 쓰고, 원문은 로컬에 남겨 뒀다가 모델이 필요할 때 headroom_retrieve로 다시 꺼내 본다. 10월 13일 0.41.0이 나왔다. 깃허브 별은 7만 5천 개를 넘었다.

1. CLI를 설치한다. headroom 명령은 PyPI 패키지에만 있고, npm의 headroom-ai는 타입스크립트 라이브러리라서 명령이 들어 있지 않다.

uv tool install --python 3.13 "headroom-ai[all]"

1. 클로드 코드를 헤드룸으로 감싸서 띄운다. 이 명령은 로컬 프록시를 켜고, 코드 탐색용 세레나(Serena) MCP 서버를 지금 프로젝트에만 등록한 다음 클로드 코드를 연다. 설정이 적용되려면 세션마다 이 명령으로 열어야 한다. 코덱스는 headroom wrap codex다.

headroom wrap claude

세레나를 모든 프로젝트에서 쓰려면 --code-memory-scope user를, 아예 빼려면 --code-memory none을 붙인다.

1. 연결이 제대로 됐는지와 얼마나 아꼈는지 본다. 대시보드는 프록시가 떠 있을 때만 열린다.

headroom doctor
headroom dashboard

1. 되돌릴 때는 unwrap을 쓴다. 세레나 등록까지 같이 지운다.

headroom unwrap claude

익명 사용 통계는 기본으로 켜져 있다. 프롬프트나 코드, 파일 경로는 보내지 않는다고 하는데, 끄려면 환경변수 HEADROOM_TELEMETRY=off를 설정한다.