headroom

빠른 시작 ·
팀용 헤드룸 ·
설치 ·
검증 ·
에이전트 ·
문서 ·
Discord ·
llms.txt

AI 에이전트 / LLM: 여기서 /llms.txt를 읽거나,
라이브 인덱스 ·
전체 문서 블롭을 가져오세요.

헤드룸은 AI 에이전트가 읽는 모든 것 — 도구 출력, 로그, RAG
청크, 파일, 대화 기록 — 을 LLM에 도달하기 전에 압축합니다. 동일한
답변, 토큰은 일부만. 압축은 여러분의 머신에서 실행되며, 압축을 위해 프롬프트나
파일 내용이 어디로도 전송되지 않습니다.

10,144 → 1,260 토큰. 동일한 FATAL 발견.

기능

라이브러리 — Python 또는 TypeScript에서 compress(messages), 어떤 앱에도 인라인으로.
프록시 — headroom proxy --port 8787, 코드 변경 없음, 모든 언어.
에이전트 래핑 — headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode 를 한 명령으로; headroom unwrap <tool> 로 되돌리기.
MCP 서버 — 모든 MCP 클라이언트를 위한 headroom_compress, headroom_retrieve, headroom_stats.
교차 에이전트 메모리 — Claude, Codex, Gemini, Grok 전반에 걸친 하나의 공유 저장소, 자동 중복 제거 포함.
headroom learn — 실패한 세션을 마이닝하고 수정 사항을 CLAUDE.local.md(기본값, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md 또는 GROK.md에 기록합니다.
출력 토큰 감소 — 여러분이 보내는 것뿐 아니라 모델이 다시 쓰는 것도 줄입니다. 아래 참조.
가역적 (CCR) — 원본은 로컬에 캐시되고 필요 시 검색됩니다.

작동 방식
여러분의 에이전트 / 앱
(Claude Code, Cursor, Codex, LangChain, Agno, Strands, 여러분의 코드…)
│ 프롬프트 · 도구 출력 · 로그 · RAG 결과 · 파일
▼
┌────────────────────────────────────────────────────┐
│ Headroom (로컬 실행 — 데이터는 여기에 머뭅니다) │
│ ──────────────────────────────────────────────── │
│ CacheAligner → ContentRouter → CCR │
│ ├─ SmartCrusher (JSON) │
│ ├─ CodeCompressor (AST) │
│ └─ Kompress-v2-base (텍스트, HF) │
│ │
│ 교차 에이전트 메모리 · headroom learn · MCP │
└────────────────────────────────────────────────────┘
│ 압축된 프롬프트 + 검색 도구
▼
LLM 제공자 (Anthropic · OpenAI · Bedrock · …)

ContentRouter는 콘텐츠 유형을 감지하고 그에 맞는 압축기를 선택합니다.
SmartCrusher / CodeCompressor / Kompress-v2-base는 각각 JSON, 소스 코드, 산문을 처리합니다.
CacheAligner는 제공자의 KV-캐시 접두사를 무효화할 휘발성 콘텐츠를 표시합니다. 프롬프트를 절대 재작성하지 않습니다.
CCR은 원본을 로컬에 저장하여 모델이 전체 텍스트가 필요할 때 headroom_retrieve를 호출할 수 있게 합니다.

→ 아키텍처 ·
CCR ·
Kompress-v2-base 모델 카드

시작하기 (60초)
# 1 — 설치
uv tool install --python 3.13 " headroom-ai[all] " # 자체 포함 환경의 CLI
pip install " headroom-ai[all] " # Python — `headroom` CLI 포함
npm install headroom-ai # TypeScript SDK 전용 — CLI 없음

# 2 — 모드 선택
headroom deploy # 턴키 로컬 배포 + 에이전트 구성
headroom wrap claude # 코딩 에이전트 래핑
headroom proxy --port 8787 # 드롭인 프록시, 코드 변경 없음
# 또는: from headroom import compress # 인라인 라이브러리

# 3 — 확인하고 절감 효과 지켜보기
headroom doctor # 상태 점검 — 라우팅 작동 확인
headroom perf
headroom dashboard # 실시간 절감 (프록시 실행 중이어야 함)
Python에서 인라인:

from headroom import compress
from openai import OpenAI

messages = [{ "role" : "user" , "content" : "Analyze these results" }]
result = compress ( messages , model = "gpt-4o" )

client = OpenAI ()
response = client . chat . completions . create ( model = "gpt-4o" , messages = result . messages )
print ( f"Saved { result . tokens_saved } tokens ( { result . compression_ratio :.0% } )" )
설정이 실행되도록 매번 래핑된 에이전트 세션을 실행하세요. headroom wrap
은 로컬 프록시를 시작하고, 의미론적 코드 탐색을 위한 Serena를
설치하며, Headroom을 통해 라우팅하도록 구성된 에이전트를 실행합니다. Claude Code의 경우 Serena는 래핑된 프로젝트에만 등록됩니다
(~/.claude.json의 로컬 범위 MCP 서버로). 모든 프로젝트에서 사용 가능하게 하려면
--code-memory-scope user 를, 건너뛰려면
--code-memory none 을 사용하세요. headroom unwrap 은 두 등록 중 하나를 제거합니다.

headroom CLI는 PyPI 패키지에만 포함됩니다. npm headroom-ai 패키지는
TypeScript SDK — 여러분이 임포트하는 라이브러리
( import { compress } from 'headroom-ai' ) — 이며 headroom 명령을 제공하지 않습니다.

검증
실제 MCP 서버 출력 형식으로 구성된 네 가지 시나리오를
제공자 토크나이저와 함께 제공되는 compress() 로 측정했습니다. 시드 고정 및 오프라인이라, 우리와 동일한 수치를 얻을 수 있습니다:

uv run python benchmarks/index_proof_table.py --seed 20260902

시나리오
이전
이후
절감

코드 검색 (100개 결과)
17,199
13,597
21%

SRE 인시던트 디버깅
55,957
24,340
57%

코드베이스 탐색
58,801
33,895
42%

GitHub 이슈 트리아지
46,067
32,429
30%

절감은 페이로드가 얼마나 반복적인지에 따라 확장됩니다. 반복되는 JSON 배열과 로그
라인은 benchmarks/bench_latency.py 에서 90%를 넘습니다; 산문과 이미 밀도 높은 출력은
거의 압축되지 않습니다. 여러분의 트래픽에 적용되는 수치는 headroom savings 를 실행하세요.

압축 비용은 1밀리초 훨씬 아래입니다 — 10K 토큰 JSON
검색 결과에서 p50 0.21 ms, 100K 토큰에서 1.4 ms — 따라서 에이전트 지연에 나타나지 않습니다.

정확도. python -m headroom.evals suite --tier 1 :

벤치마크
카테고리
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% 압축에서

N=100에서 ±0.03의 델타는 신뢰 구간 안에 들어가므로, TruthfulQA는
개선이 아니라 감지 가능한 차이가 없음을 보여줍니다.
방법론 →

출력 토큰 감소
위의 모든 것은 여러분이 보내는 프롬프트를 줄입니다. 여러분은 또한 모델이 다시 쓰는 모든 토큰에
비용을 지불하며, Opus급 모델에서는 출력 비용이 입력의 5배입니다. 그 출력의 상당 부분은
의례적인 것입니다: "좋아요, 제가…" 서두, 코드를 그대로 다시 인쇄하는 것, 그리고 파일 읽기 같은
일상적 단계에 쏟는 깊은 추론.

Headroom은 코드 변경 없이 프록시에서 이를 줄입니다:

Verbosity steering은 시스템 프롬프트 끝에 짧은 "간결하게, 컨텍스트를 재진술하지 마세요" 노트를 추가하므로, 프롬프트 캐시는 여전히 적중합니다.

Anthropic /v1/messages 와 OpenAI 호환
/v1/chat/completions 및 /v1/responses 에 적용되며, 모든 경로에서 동일한 output_shaper:*
레이블을 사용합니다.

export HEADROOM_OUTPUT_SHAPER=1 # 기본값은 꺼짐
headroom proxy --port 8787

이미 프록시를 실행 중이신가요? 이 스위치들은 매 요청마다 실시간으로 읽히므로,
headroom wrap 이 시작하지 않고 재사용한 프록시는 이후에 export한 값을 보지 못합니다 — 환경이
실행 시점에 스냅샷되었기 때문입니다. headroom wrap 은 현재 설정을 루프백
POST /admin/runtime-env 를 통해 실행 중인 프록시에 핫-동기화하므로, 재시작도 요청 손실도 없이
적용됩니다. 공유 프록시에서는 이 재정의가 전역입니다; 마지막 명시적
설정이 우선합니다.

구성할 필요 없는 간결함. 사람들은 답변이 얼마나 간결하길 원하는지 좀처럼 말하지 않습니다 — 긴 답변을 중단하거나
다 읽기도 전에 넘어가면서 보여줍니다. headroom learn --verbosity 는 과거 세션을 읽고
레벨을 선택합니다:

headroom learn --verbosity # 드라이 런 — 발견한 내용 미리보기
headroom learn --verbosity --apply # 저장하고 실행 중인 프록시에 적용
캐시 모드(기본값)의 프록시는 학습된 레벨을 다시 읽지 않습니다, 대화 중간에
변경되는 레벨은 프롬프트 캐시를 무효화하기 때문입니다. 그곳에서는 --apply 가
HEADROOM_VERBOSITY_LEVEL 로 고정합니다; 재시작 후에도 유지하려면 해당 변수를 직접 설정하세요.

측정. 출력 절감은 반사실적입니다 — 모델이 무엇을 썼을지 우리는 결코 보지 못합니다 — 따라서 Headroom은
신뢰 범위가 있는 추정치를 보고하고 이를 추정치로 표시합니다:

headroom output-savings
# Reduction: 31.7% (95% CI 27.7% … 35.7%) [estimated]
측정된 수치를 원한다면, 대화의 10%를 셰이핑되지 않은
대조군으로 남겨두세요: export HEADROOM_OUTPUT_HOLDOUT=0.1 . 그러면 대시보드의 Output Tokens
Saved 카드가 추정치가 아니라 측정됨 으로, 범위와 함께 표시됩니다.

→ 출력 토큰 감소

에이전트 호환성

에이전트
headroom wrap
비고

Claude Code
✅
--memory · --code-graph · --1m · --tool-search

Codex
✅
Claude와 메모리 공유

Grok CLI
✅
GROK_MODELS_BASE_URL을 통해 라우팅

Cursor
수동 설정
프록시를 시작하고 Cursor 설정용 base URL을 출력

Aider
✅
프록시 시작 + 실행

Copilot CLI
✅
프록시 시작 + 실행

VS Code Copilot
✅
투명 프록시; 선택된 모델 유지

OpenClaw
✅
ContextEngine 플러그인으로 설치

OpenCode
✅
구성 주입 · 프록시 시작 + 실행 1

Cline
✅
프록시 시작 + 구성 주입

Continue
✅
프록시 시작 + 구성 주입

Goose
✅
프록시 시작 + 실행

OpenHands
✅
프록시 시작 + 실행

Mistral Vibe
✅
프록시 시작 + 실행

Oh My Pi
✅
구성 주입 · 프록시 시작 + 실행

Cortex Code
라이브러리 전용
라이브러리 모드에서 60–65% 절감; wrap 없음

Kimi CLI
✅
OAuth bearer 전달됨 — 한 번 로그인

ZCode
✅
프록시를 시작하고 ZCode 설정용 base URL을 출력

모든 OpenAI 호환 클라이언트는 headroom proxy 를 통해 작동합니다. MCP 네이티브 클라이언트:
headroom mcp install . 영구 래핑 해제는 headroom unwrap <tool>
( claude , copilot , codex , grok , kimi , omp , opencode , openclaw ,
zcode )로. 레지스트리 작성자는 산문에서 headroom mcp serve 계약을 재구성하기보다
정식 server.json 을 사용해야 합니다.

Anthropic /v1/messages 의 경우, --mode cache 는 자동 --memory 컨텍스트 주입을 건너뛰어 제공자 접두사가 안정적으로 유지됩니다. OpenAI chat/responses와 Gemini는 메모리를 라이브 존 꼬리에 추가합니다. Anthropic 경로에서 자동 메모리 컨텍스트가 필요하면 --mode token 을 사용하세요.

GitHub Copilot CLI 구독 모드
Headroom은 Copilot CLI 구독 트래픽을 로컬 프록시를 통해 라우팅할 수 있습니다:

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o
래퍼는 Headroom의 재사용 가능한 GitHub OAuth 토큰을 Copilot의
단기 API 토큰으로 교환하고, 실행 시 업스트림 엔드포인트를
COPILOT_PROVIDER_API_URL=... 로 출력합니다. headroom copilot-auth login 은
일반 GitHub 또는 Copilot CLI 토큰에 의존하는 대신 Headroom 전용 Copilot OAuth 토큰을 저장합니다 — 일반 토큰은 계정 메타데이터를 읽을 수 있지만 Copilot의 토큰 교환 엔드포인트에서 여전히 거부됩니다.

GitHub Enterprise Server 또는 커스텀 도메인 Copilot 배포의 경우, 실행 전에
다음 중 하나를 설정하세요. 둘 다 설정되면 URL이 우선합니다:

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com
github.com/enterprises/your-enterprise 같은 GitHub.com Enterprise Cloud URL의 경우,
둘 다 설정하지 마세요 — Headroom은 GitHub의
일반 토큰 교환 엔드포인트와 로그인한 계정에 대해 광고된 Copilot API 엔드포인트를 사용합니다.

플랫폼 지원. Copilot CLI Keychain 저장소를 통한 macOS 인증 재사용과
Windows 디바이스 인증은 실측 테스트되었습니다. Copilot CLI 1.0.81은
Headroom이 읽는 레거시 Credential Manager 스키마를 통해 Windows 로그인을 노출하지 않으므로,
Windows에서는 headroom copilot-auth login 을 실행하세요. Linux Secret Service /
secret-tool 재사용은 구현되었지만 실제 데스크톱에서 아직 검증되지 않았습니다. Docker와 CI에서는
호스트 키체인 접근에 의존하는 대신 명시적 GITHUB_COPILOT_TOKEN 또는
GITHUB_COPILOT_GITHUB_TOKEN 을 전달하세요.

VS Code의 GitHub Copilot
Headroom은 Copilot의 API 프록시 엔드포인트를 재정의하므로, VS Code 모델 선택기가
권위를 유지합니다. GPT-5.5, GPT-5.6 Luna/Sol/Terra, Claude Sonnet/Opus 및
기타 Copilot 모델은 트래픽이 로컬 압축 프록시를 통과하는 동안 원래 모델 ID를 유지합니다. Headroom은 VS Code를 패치하거나 Codex
설정을 변경하지 않습니다.

headroom copilot-auth login
headroom wrap vscode
명령을 계속 실행하고 Copilot을 평소처럼 사용하세요. 단기 업스트림
Copilot 토큰은 프록시 프로세스에만 보관됩니다.
전체 가이드 →

VS Code의 Claude Code
공식 Claude Code 확장은 Claude Code를 내장하고 CLI와 동일한 사용자
설정을 읽습니다. 프록시 추가 기능을 설치한 다음, VS Code에서 열 프로젝트에서 래퍼를 실행하세요:

pip install " headroom-ai[proxy] "
headroom wrap vscode-claude
# 선택 사항: Claude Code의 클라이언트 소유 1M 모델 선택기 유지
headroom wrap vscode-claude --1m
첫 실행 시 VS Code 창을 다시 로드하세요. 래퍼 터미널을 계속 실행해 두세요…