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에 도달하기 전에 압축합니다. 동일한 답변을 유지하면서 토큰을 60-95% 절감합니다.
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_statsheadroom 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%) [estimated]추정치 대신 측정된 숫자를 원하시나요? 대화의 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 토큰으로 교환합니다.