Headroom
모델에 닿기 전에 도구 출력을 압축하는 로컬 미들웨어
uv tool install --python 3.13 "headroom-ai[all]"에이전트가 읽는 도구 출력, 로그, RAG 청크, 파일, 대화 이력을 모델에 닿기 전에 압축합니다. 압축은 로컬에서 돌고 프롬프트나 파일 내용은 어디로도 보내지 않습니다. 쓰는 방법이 네 가지입니다. 파이썬이나 타입스크립트에서 compress 를 부르는 라이브러리, 코드 변경 없이 끼우는 프록시, 코딩 에이전트를 감싸는 headroom wrap, 그리고 MCP 서버입니다. 내용 종류를 감지해 JSON 은 SmartCrusher, 소스코드는 CodeCompressor, 산문은 Kompress-v2-base 로 나눠 처리하고, 원본은 로컬에 남겨 두어 모델이 필요할 때 다시 꺼내 갑니다.
판단
이럴 때 씁니다
- 도구 출력이나 로그가 커서 컨텍스트를 금방 채울 때
- 코드를 고치지 않고 프록시만 끼워 토큰을 줄이고 싶을 때
- 압축을 외부 서비스에 보내지 않고 로컬에서 끝내야 할 때
이럴 땐 쓰지 마세요
- 이미 압축된 산문 위주 입력에서는 줄어드는 양이 거의 없습니다
- npm 패키지만 깔고 CLI 를 기대하면 명령이 없습니다
- 모델 응답 품질을 한 자릿수까지 고정해야 하는 평가 환경에는 변수를 하나 더 넣는 셈입니다
차별점
- 라이브러리, 프록시, 에이전트 감싸기, MCP 서버 네 가지 진입점을 한 패키지가 제공합니다.
- 내용 종류를 감지해 JSON, 소스코드, 산문에 각각 다른 압축기를 붙입니다.
- 원본을 로컬에 남겨 두어 모델이 필요할 때 전체 텍스트를 다시 꺼내 갑니다.
워크플로
- 01CLI 가 들어 있는 파이썬 패키지를 설치합니다.
- 02라이브러리, 프록시, 에이전트 감싸기, MCP 서버 중 쓸 방식을 고릅니다.
- 03headroom doctor 로 경로가 제대로 잡혔는지 확인합니다.
- 04headroom dashboard 로 실제로 얼마나 줄었는지 봅니다.
주요 명령
| 명령 | 설명 |
|---|---|
uv tool install --python 3.13 "headroom-ai[all]" | 독립 환경에 CLI 를 설치합니다. |
headroom proxy --port 8787 | 코드 변경 없이 끼우는 프록시를 띄웁니다. |
headroom wrap claude | 코딩 에이전트를 감싸 프록시를 거치게 합니다. |
headroom unwrap claude | 감싼 설정을 되돌립니다. |
headroom doctor | 경로와 설정을 점검합니다. |
함정
설치 전에 확인하세요
- npm 의 headroom-ai 는 타입스크립트 SDK 뿐이고 headroom 명령을 제공하지 않습니다. CLI 는 PyPI 패키지에만 들어 있습니다.
- headroom wrap 은 코드 탐색용 Serena 를 사용자 범위에 등록합니다. 클로드 코드라면 ~/.claude.json 에 남아 다른 프로젝트에서도 계속 보이고, unwrap 하기 전까지 유지됩니다.
- 감축 폭은 입력이 얼마나 반복적인지에 좌우됩니다. 반복 JSON 과 로그는 크게 줄지만 산문은 거의 줄지 않습니다.
비교
컨텍스트를 줄이는 방법은 보통 요약이나 잘라내기라서 되돌릴 수 없습니다. 이쪽은 원본을 로컬 캐시에 두고 압축본만 보내며, 모델이 필요하면 도구로 원문을 요청합니다. 다만 압축기가 하나 더 끼는 만큼 파이프라인에 검증할 지점이 늘어납니다.
최근 변경
0.37.0 이 2026년 8월 27일에 나왔습니다. 세션을 인식하는 사이드카 모드 압축 엔드포인트와 사용량 중계가 들어갔고, 프록시가 세션 상태를 스스로 제한하도록 바뀌었습니다.