Headroom 완전 가이드 2026: 오픈소스 도구로 LLM 토큰 비용 60-95% 절감하기

# 전체 버전 설치(proxy, MCP, ML 등 모든 기능 포함)
pip install "headroom-ai[all]"

# 또는 필요 모듈만 설치
pip install "headroom-ai[proxy]"   # 프록시 모드만
pip install "headroom-ai[mcp]"     # MCP 서버만
pip install "headroom-ai[ml]"      # 머신러닝 압축 모델

npm install headroom-ai

# 버전 및 기능 확인
headroom --version

# 성능 테스트 실행, 현재 환경의 압축 효과 확인
headroom perf

# Claude Code 래핑
headroom wrap claude

# Codex 래핑
headroom wrap codex

# Cursor 래핑
headroom wrap cursor

# Aider 래핑
headroom wrap aider

# GitHub Copilot CLI 래핑
headroom wrap copilot

$ headroom wrap claude

✅ Headroom proxy started on port 8787
✅ Claude Code config updated

To verify, run:
  claude "What is 2+2?"

You should see compression stats in the output.

# 프록시 시작, 8787 포트 리스닝
headroom proxy --port 8787

from openai import OpenAI

# 원래 설정
# client = OpenAI(api_key="sk-...")

# Headroom 프록시 통해 사용
client = OpenAI(
    api_key="sk-...",
    base_url="http://localhost:8787/v1"  # Headroom 프록시 지정
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "이 코드 설명해줘"}]
)

from headroom import compress

messages = [
    {"role": "user", "content": "이 로그 파일 분석해줘"},
    {"role": "assistant", "content": "로그 내용을 제공해주세요"},
    {"role": "user", "content": "[... 10000줄 로그 ...]"}
]

# 메시지 압축
compressed = compress(messages, model="claude-3-sonnet")

print(f"원본 토큰: {compressed.original_tokens}")
print(f"압축 후 토큰: {compressed.compressed_tokens}")
print(f"절감: {compression.savings_percent}%")

# LLM으로 전송
response = anthropic_client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1024,
    messages=compressed.messages  # 압축된 메시지 사용
)

import { compress } from 'headroom-ai';

const messages = [
  { role: 'user', content: 'Analyze this codebase' },
  { role: 'assistant', content: 'Please provide the files' },
  { role: 'user', content: '[... 50 files ...]' }
];

const compressed = await compress(messages, { model: 'gpt-4' });

console.log(`Saved ${compressed.savingsPercent}% tokens`);

from headroom import SmartCrusher

data = {
    "users": [
        {"id": 1, "name": "Alice", "email": "alice@example.com", "created_at": "2024-01-01"},
        {"id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2024-01-02"},
        # ... 1000개 이상 레코드
    ]
}

crusher = SmartCrusher()
compressed = crusher.compress(data)

# 키워드 필드 유지, 불필요한 메타데이터 제거
# 원본: 50,000 토큰 → 압축 후: 5,000 토큰 (90% 절감)

from headroom import CodeCompressor

code = """
def calculate_total(items):
    '''Calculate total price with tax'''
    total = 0
    for item in items:
        if item.active:
            total += item.price * item.quantity
    tax = total * 0.08
    return total + tax
"""

compressor = CodeCompressor(language="python")
compressed = compressor.compress(code)

# 함수 시그니처, 제어 흐름, 핵심 변수 유지
# 주석, 공백, 비핵심 구현 세부사항 제거

# 첫 사용 시 모델 자동 다운로드(약 500MB)
headroom proxy

# 모델 캐시 위치: ~/.cache/headroom/kompress-base

# 공유 메모리 활성화
headroom wrap claude --memory
headroom wrap codex --memory

# MCP 서버 설치
headroom mcp install

# 사용 가능한 MCP 도구:
# - headroom_compress: 임의 콘텐츠 압축
# - headroom_retrieve: 원본 데이터 검색
# - headroom_stats: 압축 통계 확인

// claude_desktop_config.json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}

headroom wrap claude
claude "사용자 인증 모듈 구현 찾아줘"

# 1단계: Claude Code 스캔 및 캐싱
headroom wrap claude --memory
claude "src/auth/ 디렉토리 코드 품질 리뷰해줘"

# 2단계: Codex 캐시 재사용
headroom wrap codex --memory
codex "src/auth/ 단위 테스트 생성해줘"
# Codex가 Claude의 캐시된 인덱스 직접 사용, 재스캔 불필요

# 3단계: Cursor 계속 재사용
headroom wrap cursor --memory
cursor "src/auth/ 에러 핸들링 리팩토링해줘"

from headroom import compress
import anthropic

# 로그 읽기
with open("production.log") as f:
    logs = f.read()

messages = [
    {"role": "user", "content": f"이 로그 분석해서 에러 원인 찾아줘:\n{logs}"}
]

# 압축
compressed = compress(messages, model="claude-3-sonnet")

print(f"원본: {compressed.original_tokens} 토큰")
print(f"압축 후: {compressed.compressed_tokens} 토큰")
print(f"절감: {compressed.savings_percent}%")

# 전송
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=2048,
    messages=compressed.messages
)

print(response.content[0].text)

python -m headroom.evals suite --tier 1

from headroom import CompressionMiddleware

# ASGI 앱에 미들웨어 추가
app.add_middleware(CompressionMiddleware)

# 학습 모드 활성화
headroom wrap claude --learn

# Claude Code가 잘못된 답변을 줄 때 Headroom은:
# 1. 실패 원인 분석
# 2. 수정 프롬프트 생성
# 3. 프로젝트의 CLAUDE.md에 기록
# 4. 다음 세션에서 자동 적용

from headroom import PipelineExtension

class MyCustomCompressor(PipelineExtension):
    def on_input_received(self, event):
        # 입력 수신 시 사용자 정의 로직 실행
        print(f"Received {len(event.content)} bytes")

    def on_input_compressed(self, event):
        # 압축 완료 후 실행
        print(f"Compressed to {event.compressed_size} bytes")

# 확장 등록
pipeline.register(MyCustomCompressor())

pip install "headroom-ai[all]"
headroom wrap claude  # 또는 사용하는任何 Agent
headroom perf         # 절감 효과 확인