Claude Code 사용량 약 4배: Headroom MCP 예산 최적화 (2026-06-04)
실제 repo에서 Claude Code를 쓰는 인디 개발자는 매번 grep, 테스트 로그, MCP 덤프가 컨텍스트로 돌아오고 Anthropic은 입·출력 토큰 과금한다는 걸 압니다. Headroom(Apache 2.0, 2026년 중 GitHub 1만+ 스타)은 모델 전에 도구 출력·로그·파일·RAG 청크를 로컬 압축하며, 공개 workload에서 60–95% 토큰 절감, README 데모의 FATAL 검색 10,144 → 1,260 토큰 동일 답변 주장.
이 글은 headroom wrap claude와 MCP 서버의 실제 청구 수학 + 설정—Claude 대체 허세가 아니라, 이미 본 stderr 메가바이트에 정가를 내지 않는 방법입니다.
엔지니어링 repo에서 Claude Code 예산이 타는 이유
Claude Code의 강점—엔지니어처럼 repo 읽기—가 미터기이기도 합니다:
- 도구 출력 팽창 — 대형 모노레포에서
bash, 검색, MCP가 턴당 1만–8만 토큰. - 재전송 컨텍스트 — 압축 없으면 이전 도구 덩어리가 스레드에 남아 45분 리팩터에서 비용 복리.
- MCP 확산 — 서버마다 JSON; 시끄러운 도구 3개면 입력 토큰 2배.
하네스를 고르는 중이면 Codex CLI vs Claude Code 벤치와 2026 에이전트 비교—이 글은 Claude Code를 이미 쓰고 마진을 회복하려는 경우입니다.
아키텍처 — Headroom 위치
Claude Code (or Cursor / Codex via wrap)
│ tool calls · logs · file reads
▼
┌──────────────────────────────────────┐
│ Headroom (local — Python 3.10+) │
│ CacheAligner → ContentRouter → CCR │
│ SmartCrusher (JSON) │
│ CodeCompressor (AST) │
│ Kompress-base (text) │
│ MCP: compress · retrieve · stats │
└──────────────────────────────────────┘
│ compressed context + retrieve tool
▼
Anthropic API (Claude)
- CCR(가역) — 원문 로컬 저장; 모델은
headroom_retrieve로 원문 가능. - MCP 모드 —
headroom_compress,headroom_retrieve,headroom_stats를 MCP 클라이언트에. - 프록시 모드 —
headroom proxy --port 8787, OpenAI 호환 클라이언트 코드 변경 없음.
문서: headroom-docs.vercel.app · 소스: github.com/chopratejas/headroom.
청구 비교 매트릭스 — 공개 workload vs "순수 Claude Code"
Headroom 공개 전후 표는 계획용—repo 보장 아님. 본인 $/MTok으로 달러화.
| Workload(Headroom) | 압축 전 | 압축 후 | 절감 | 인디 의미 |
|---|---|---|---|---|
| 코드 검색(100건) | 17,765 | 1,408 | 92% | 무거운 rg 날은 세션 $20→커피값 |
| SRE 인시던트 | 65,694 | 5,118 | 92% | --verbose 생략 없이 로그 분류 |
| GitHub 이슈 트리아지 | 54,174 | 14,761 | 73% | Max 플랜에서도 봇 가능 |
| 코드베이스 탐색 | 78,502 | 41,254 | 47% | 여전히 가치; 넓은 읽기는 압축 적음 |
가정 월간 계산(예시)
Sonnet급 ~$3/MTok 입력 가정(Anthropic 현행 요금 확인):
| 시나리오 | 원시/월 | ~75% 후 | $ 입력(원시) | $ (Headroom) |
|---|---|---|---|---|
| Solo indie (50M in) | 50M | 12.5M | $150 | ~$38 |
| Small team (200M in) | 200M | 50M | $600 | ~$150 |
| "Log hell" week (+30M logs) | 30M | 3M (90% on logs) | $90 | ~$9 |
제목의 4배 사용량은 달러 예산 고정 시 평균 ~75% 절감 ≈ 같은 지출로 약 4배 턴—무제한 아님.
시나리오 A — headroom wrap claude (가장 빠른 경로)
적합: Mac/Linux 터미널 일상 Claude Code; MCP.json 수정 불필요.
# Python 3.10+ required
pip install "headroom-ai[all]"
# One-command wrap (starts compression + optional memory)
headroom wrap claude
# After a session, inspect savings
headroom perf
변화: API 전 도구 출력·컨텍스트 가로챔.
만약 X면 Y: 임대 Mac의 obra Superpowers → 같은 호스트에 Headroom. obra 설치.
시나리오 B — Claude Code + MCP
MCP 큐레이션 팀; compress/retrieve 일급 도구.
pip install "headroom-ai[mcp]"
# Install MCP config for supported clients
headroom mcp install
Claude Code MCP 설정(최신 문서 확인):
{
"mcpServers": {
"headroom": {
"command": "headroom",
"args": ["mcp", "serve"]
}
}
}
MCP 도구:
| 도구 | 역할 |
|---|---|
headroom_compress | 채팅 전 블롭 축소 |
headroom_retrieve | CCR에서 원문 |
headroom_stats | 토큰 절감 텔레메트리 |
거대 JSON → Claude 요약 전 Headroom.
시나리오 C — 혼합 스택 프록시
headroom proxy --port 8787
# Point OpenAI-compatible clients at http://127.0.0.1:8787
Codex, Aider, 스크립트와 단일 압축 계층.
단계별 런북 — 첫 유효한 1시간
- 설치 —
pip install "headroom-ai[all]". - 베이스라인 — Headroom 없이 1작업; 입력 토큰 기록.
- wrap —
headroom wrap claude; 동일 작업. - 비교 —
headroom perf; 검색/로그 작업. - MCP —
headroom mcp install. - 기대 — ~47%.
- CCR —
headroom_retrieve. - 스킵 — 임대 Mac proxy.
문제 해결
wrap이 Claude Code를 시작하지 않음
which claude 먼저.
절감 ~0%
큰 JSON/로그에서 테스트.
세부 누락
headroom_retrieve.
MCP 빨강
headroom mcp serve.
권장 경로
| 상황 | 할 일 |
|---|---|
| 솔로, 터미널만 Claude Code | headroom wrap claude + 주간 headroom perf |
| MCP 5+ | MCP install + 최대 페이로드 서버부터 |
| 혼합 에이전트 팀 | 공유 Mac mini headroom proxy |
| Max 예산 빡빡 | 로그/검색 우선(최대 92%) |
| 중국 본토 | pip 미러; HK/SG 임대 Mac |