Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server.
이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.
Headroom은 AI 에이전트가 읽는 모든 것(도구 출력, 로그, RAG 청크, 파일, 대화 기록)을 LLM에 도달하기 전에 압축합니다. 동일한 답변을 유지하면서 토큰을 획기적으로 줄입니다.
compress(messages)를 인라인으로 사용headroom proxy --port 8787로 코드 변경 없이 사용headroom wrap claude|codex|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe 한 줄 명령어; headroom unwrap <tool>으로 해제headroomcompress, headroomretrieve, headroom_stats 제공headroom learn — 실패한 세션을 분석하여 CLAUDE.local.md(기본값, gitignored) 또는 CLAUDE.md/AGENTS.md/GEMINI.md에 수정 사항 기록 에이전트/앱
(Claude Code, Cursor, Codex, LangChain, Agno, Strands, 사용자 코드...)
│ 프롬프트 · 도구 출력 · 로그 · RAG 결과 · 파일
▼
┌────────────────────────────────────────────────────┐
│ Headroom (로컬 실행 — 데이터는 여기에 유지) │
│ ──────────────────────────────────────────────── │
│ CacheAligner → ContentRouter → CCR │
│ ├─ SmartCrusher (JSON) │
│ ├─ CodeCompressor (AST) │
│ └─ Kompress-base (텍스트, HF) │
│ │
│ 에이전트 간 메모리 · headroom learn · MCP │
└────────────────────────────────────────────────────┘
│ 압축된 프롬프트 + 검색 도구
▼
LLM 제공자 (Anthropic · OpenAI · Bedrock · …)headroom_retrieve 호출# 1 — 설치
pip install "headroom-ai[all]" # Python
npm install headroom-ai # Node / TypeScript
# 2 — 모드 선택
headroom wrap claude # 코딩 에이전트 래핑
headroom proxy --port 8787 # 드롭인 프록시, 코드 변경 불필요
# 또는: from headroom import compress # 인라인 라이브러리
# 3 — 설정 확인 및 절감량 확인
headroom doctor # 상태 확인 — 라우팅 작동 확인
headroom perf
headroom dashboard # 실시간 절감 대시보드 (프록시 실행 중이어야 함)세부 옵션: [proxy], [mcp], [ml], [code], [memory], [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU 메모리 임베더 오프로드 — HEADROOMEMBEDDERRUNTIME=pytorch_mps 설정). Python 3.10+ 필요.
실제 에이전트 워크로드 절감:
| 워크로드 | 이전 | 이후 | 절감율 | ||
|---|---|---|---|---|---|
| 코드 검색 (100개 결과) | 17,765 | 1,408 | 92% | ||
| SRE 장애 디버깅 | 65,694 | 5,118 | 92% | ||
| GitHub 이슈 분류 | 54,174 | 14,761 | 73% | ||
| 코드베이스 탐색 | 78,502 | 41,254 | 47% |
표준 벤치마크에서 정확도 유지:
| 벤치마크 | 카테고리 | N | 기준 | Headroom | 차이 | ||
|---|---|---|---|---|---|---|---|
| GSM8K | 수학 | 100 | 0.870 | 0.870 | ±0.000 | ||
| TruthfulQA | 사실 | 100 | 0.530 | 0.560 | +0.030 | ||
| SQuAD v2 | QA | 100 | — | 97% | 19% 압축률 | ||
| BFCL | 도구 | 100 | — | 97% | 32% 압축률 |
재현: python -m headroom.evals suite --tier 1
위의 모든 내용은 보내는 프롬프트를 줄입니다. 하지만 모델이 작성하는 토큰에 대해서도 비용을 지불하며, Opus급 모델에서는 출력 비용이 입력의 5배입니다. 출력 중 많은 부분이 낭비입니다: "좋아요, 먼저..." 서문, 방금 보여준 코드 재인쇄, 파일 읽기와 같은 일상적인 단계에 대한 깊은 "사고".
Headroom은 프록시에서 코드 변경 없이 이를 줄일 수 있습니다:
활성화:
export HEADROOM_OUTPUT_SHAPER=1 # 기본적으로 꺼짐
headroom proxy --port 8787이미 프록시를 실행 중인가요? 이 스위치는 요청마다 실시간으로 읽히므로,
headroom wrap이 재사용한(시작하지 않은) 프록시는 이후 내보낸 값을 보지 못합니다. 환경이 시작 시 스냅샷되었기 때문입니다.headroom wrap은 이제 현재 설정을 루프백POST /admin/runtime-env를 통해 실행 중인 프록시에 핫싱크하므로 재시작 없이 즉시 적용됩니다(콜드 스타트 없음, 요청 손실 없음, 캐시 손실 없음).wrap하기 전에 설정하세요. 공유 프록시에서는 이러한 재정의가 전역적입니다 — 마지막 명시적 설정이 우선합니다.
적절한 간결함을 학습하세요. 사람들은 답변을 얼마나 간결하게 원하는지 말하지 않습니다 — 행동으로 보여줍니다 (긴 답변을 중단하거나, 읽기 전에 넘어감). headroom learn --verbosity는 과거 세션을 읽고 자동으로 수준을 선택합니다:
headroom learn --verbosity # 찾은 내용 미리보기 (드라이 런)
headroom learn --verbosity --apply # 저장; 프록시가 이후부터 사용절약한 출력 토큰 확인. 출력 절감은 반사실적입니다 — 모델이 작성했을 내용을 볼 수 없으므로 Headroom은 신뢰 구간이 있는 추정치를 보고하며, 조작된 숫자가 아닙니다:
headroom output-savings
# Reduction: 31.7% (95% CI 27.7% … 35.7%) [추정]추정치 대신 측정된 숫자를 원하시나요? 대화의 10%를 조정되지 않은 대조군으로 남겨두세요: export HEADROOMOUTPUTHOLDOUT=0.1. 대시보드에는 입력 압축 옆에 출력 토큰 절약 카드가 표시되며, measured 또는 estimated 레이블과 신뢰 구간이 함께 표시됩니다.
| 에이전트 | headroom wrap |
참고 사항 | ||
|---|---|---|---|---|
| Claude Code | ✅ | --memory · --code-graph · --1m · --tool-search |
||
| Codex | ✅ | Claude와 메모리 공유 | ||
| Cursor | 수동 설정 | 프록시 시작 후 Cursor 설정에 기본 URL 출력 | ||
| Aider | ✅ | 프록시 시작 + 실행 | ||
| Copilot CLI | ✅ | 프록시 시작 + 실행 | ||
| OpenClaw | ✅ | ContextEngine 플러그인으로 설치 | ||
| OpenCode | ✅ | 설정 주입 · 프록시 시작 + 실행 | ||
| Cline | ✅ | 프록시 시작 + 설정 주입 | ||
| Continue | ✅ | 프록시 시작 + 설정 주입 | ||
| Goose | ✅ | 프록시 시작 + 실행 | ||
| OpenHands | ✅ | 프록시 시작 + 실행 | ||
| Mistral Vibe | ✅ | 프록시 시작 + 실행 | ||
| Cortex Code | ✅ | 60–65% 절감 · 라이브러리 모드 |
OpenAI 호환 클라이언트는 headroom proxy를 통해 작동합니다. MCP 네이티브: headroom mcp install. headroom unwrap <tool>으로 지속적 래핑 해제 가능 (지원: claude, copilot, codex, opencode, openclaw).
Headroom은 GitHub Copilot CLI 구독 트래픽을 로컬 프록시를 통해 라우팅할 수 있습니다:
headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o이를 통해 Headroom이 OpenAI 호환 Copilot CLI 요청을 가로채서 GitHub Copilot의 호스팅 API로 전달하기 전에 동일한 프록시 압축 파이프라인을 적용할 수 있습니다. 래퍼는 Headroom의 재사용 가능한 GitHub OAuth 토큰을 Copilot의 단기 API 토큰으로 교환합니다.