ONEDEV

headroom

AI GatewaysCLIPython

★ 71,756주당 +936조회 6

무엇인가

Headroom은 에이전트와 LLM 제공자 API 사이에 놓이는 컨텍스트 압축 계층이다. 프롬프트가 모델에 도달하기 전에 도구 출력, 로그, 파일, RAG 청크, 대화 이력을 압축한다. 압축은 사용자 머신에서 실행되며 프롬프트나 파일 내용이 압축을 위해 외부로 전송되지 않는다. 같은 압축기를 Python 라이브러리, 로컬 프록시, MCP 서버, 에이전트 래퍼 네 가지 형태로 노출한다.

어떻게 동작하나

내부에서 ContentRouter가 콘텐츠 유형을 판별해 압축기를 고른다. JSON은 SmartCrusher, 소스 코드는 CodeCompressor, 산문은 Kompress-v2-base가 처리한다. CacheAligner는 제공자 KV 캐시 프리픽스를 깨뜨릴 휘발성 콘텐츠를 표시하며 프롬프트를 재작성하지 않는다. 원본은 CCR 로컬 캐시에 저장되고 모델이 필요할 때 headroom_retrieve로 가져온다. 압축 비용은 10K 토큰 JSON 검색 결과에서 p50 0.21ms, 100K 토큰에서 1.4ms다.

무엇과 다른가

단순 절단이나 요약과 달리 원본을 로컬에 보관해 되돌릴 수 있다. 제공자 프롬프트 캐시를 건드리지 않는다는 점에서 캐시 무효화형 압축과 구분된다. 입력뿐 아니라 모델이 되돌아 쓰는 출력 토큰도 줄인다. Verbosity steering은 시스템 프롬프트 끝에 간결 지시를 덧붙여 프롬프트 캐시 적중을 유지하고, effort routing은 도구 결과를 받아 이어가는 턴에서 추론 예산을 낮춘다. 두 기능은 Anthropic /v1/messages와 OpenAI 호환 /v1/chat/completions, /v1/responses에 적용되며 reasoning_effort, thinking.budget_tokens, output_config.effort를 조정한다.

어떻게 쓰나

`headroom proxy --port 8787`로 로컬 프록시를 띄우면 코드 변경 없이 어떤 언어의 클라이언트든 연결된다. `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode`는 프록시를 시작하고 Serena를 설치한 뒤 에이전트를 Headroom 경유로 실행한다. Serena는 사용자 스코프(~/.claude.json)에 등록되고 --code-memory none으로 건너뛴다. 되돌리려면 `headroom unwrap <agent>`를 쓴다. MCP 클라이언트에는 `headroom mcp install`로 headroom_compress, headroom_retrieve, headroom_stats를 노출한다. `headroom learn`은 실패한 세션을 분석해 CLAUDE.local.md, CLAUDE.md, AGENTS.md, GEMINI.md, GROK.md에 교정 내용을 기록한다.

전제와 한계

headroom CLI는 PyPI 패키지에만 포함된다. npm headroom-ai는 import해서 쓰는 TypeScript SDK이며 headroom 명령을 제공하지 않는다. 압축률은 페이로드의 반복도에 따라 달라져 반복 JSON 배열과 로그는 90%를 넘기지만 산문과 이미 밀도 높은 출력은 거의 줄지 않는다. 출력 토큰 절감량은 기본적으로 추정치이며 HEADROOM_OUTPUT_HOLDOUT=0.1로 10%를 대조군으로 남겨야 실측으로 표시된다. 공유 프록시에서 런타임 설정은 전역이고 마지막 명시 설정이 이긴다.

관련 논문 4

유사 도구