Quickstart · Headroom for Teams · Install · Proof · Agents · Docs · Discord · llms.txt

AI agents / LLMs: /llms.txt를 읽으세요.

여기서, 또는 라이브 인덱스(live index) · 전체 문서 블롭(full docs blob)을 가져오세요.

Headroom은 AI 에이전트가 읽는 모든 것 — 도구 출력(tool outputs), 로그(logs), RAG 청크(RAG chunks), 파일 및 대화 기록(conversation history) — 을 LLM에 전달하기 전에 압축합니다. 동일한 답변을 훨씬 적은 토큰으로 얻을 수 있습니다. 압축은 사용자의 기기에서 실행되며, 프롬프트나 파일 내용은 어딘가로 전송되어 압축되지 않습니다.

라이브러리(Library)—Python 또는 TypeScript에서 compress(messages)를 사용하여 모든 앱에 인라인으로 사용할 수 있습니다.프록시(Proxy)—headroom proxy --port 8787을 사용하여, 코드 변경 없이 어떤 언어에서도 사용 가능합니다.에이전트 래핑(Agent wrap)—한 명령어(headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode)로 여러 에이전트를 처리할 수 있으며, headroom unwrap <tool>로 되돌릴 수 있습니다.MCP 서버(MCP server)—모든 MCP 클라이언트용으로 headroom_compress, headroom_retrieve, headroom_stats를 제공합니다.크로스-에이전트 메모리(Cross-agent memory)—Claude, Codex, Gemini 및 Grok 전반에 걸쳐 공유되는 저장소이며, 자동 중복 제거 기능을 갖추고 있습니다. 실패한 세션을 기록하고 수정 사항을 headroom learn에 작성합니다.

CLAUDE.local.md (기본값, gitignore), CLAUDE.md, AGENTS.md, GEMINI.md 또는 GROK.md를 사용합니다.

출력 토큰 감소(Output token reduction)—사용자가 전송하는 내용뿐만 아니라 모델이* 다시 작성하는 내용도 간소화합니다. 아래를 참조하세요.가역적(Reversible) (CCR)—원본은 로컬에 캐시되며 필요할 때 검색됩니다.

당신의 에이전트 / 앱
(Claude Code, Cursor, Codex, LangChain, Agno, Strands, 당신의 자체 코드…)
│ 프롬프트 · 도구 출력 · 로그 · RAG 결과 · 파일
...

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

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

1 — 설치

uv tool install --python 3.13 "headroom-ai[all]" # CLI를 독립적인 환경에서 설치
pip install "headroom-ai[all]" # Python — headroom CLI가 포함됨
...

인라인, Python에서:

from headroom import compress
from openai import OpenAI
messages = [{"role": "user", "content": "이 결과를 분석해 주세요"}]
...

세션마다 래핑된 에이전트 세션을 실행하여 설정이 작동하도록 합니다. headroom wrap은
로컬 프록시를 시작하고, 시맨틱 코드 탐색을 위해 Serena를 설치하며, Headroom을 통해 라우팅되도록 구성된 에이전트를 실행합니다. Claude Code의 경우, Serena는 래핑된 프로젝트에 대해서만 등록됩니다 ( ~/.claude.json 파일 내에서 local-스코프 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()로 측정했습니다. 시드(Seed)를 설정하고 오프라인으로 실행했기 때문에 우리가 얻은 것과 동일한 숫자를 얻을 수 있습니다:

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

절감률은 페이로드의 반복 정도에 따라 달라집니다. 중복된 JSON 배열과 로그 라인은 benchmarks/bench_latency.py에서 90%를 제거합니다.

; 산문 및 이미 밀도가 높은 출력물
compress는 거의 적게 비용을 차지합니다. 10K 토큰 JSON 검색 결과의 p50 기준 0.21ms, 100K 토큰에서는 1.4ms로, headroom savings를 사용해 자체 트래픽에 대해 실행하여 자신에게 적용되는 숫자를 확인하세요.

압축 비용은 밀리초보다 훨씬 적습니다 — 에이전트 지연 시간(latency)에 표시되지 않습니다.

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

N=100에서 ±0.03의 델타(delta)는 신뢰 구간(confidence interval) 내에 속하므로, TruthfulQA는 개선이라기보다는 감지 가능한 차이가 없음을 보여줍니다. 방법론 →

위 모든 기능은 사용자가 전송하는 프롬프트를 축소합니다. 또한 모델이 출력하는 모든 토큰에 대해 비용을 지불하며, Opus급 모델의 경우 출력 비용이 입력 비용보다 5배 높습니다. 이 출력 중 상당 부분은 형식적인 절차(ceremony)입니다: "좋아요, 제가…", 재인쇄되는 코드, 파일 읽기와 같은 일상적인 단계에 소모되는 심층 추론 과정 등이 그것입니다.

Headroom은 사용자의 코드를 변경하지 않으면서 프록시를 통해 이 부분을 간소화합니다:

**서술성 제어(Verbosity steering)**는 시스템 프롬프트의 끝에 "간결하게 작성하고, 컨텍스트를 반복하지 마세요"라는 짧은 메모를 추가하여, 사용자의 프롬프트 캐시는 여전히 작동하도록 합니다. **노력 라우팅(Effort routing)**은 턴이 도구 결과(tool result) 이후 모델이 재개하는 경우—파일 읽기나 테스트 통과 등—추론 노력을 낮춥니다. 새로운 질문이나 오류가 발생하면 전체 노력 수준을 유지합니다.

두 기능 모두 Anthropic의 /v1/messages와 OpenAI 호환 /v1/chat/completions, 그리고 /v1/responses에 적용됩니다. 노력 라우팅은 OpenAI에서는 reasoning_effort를, Anthropic에서는 thinking.budget_tokens / output_config.effort를 사용하며, 두 경로 모두 동일한 클램프 전용 불변성(clamp-only invariant)과 동일한 output_shaper:* 레이블을 사용합니다.

export HEADROOM_OUTPUT_SHAPER=1 # 기본값은 비활성화됨
headroom proxy --port 8787

이미 프록시를 실행 중인가요? 이 스위치들은 모든 요청마다 실시간으로 읽히기 때문에, headroom wrap을 사용하여 재사용된 프록시는 나중에 사용자가 내보내는 값(export)을 볼 수 없습니다. 해당 환경은 시작 시점에 스냅샷되었기 때문입니다. headroom wrap은 현재 설정을 루프백(POST /admin/runtime-env)을 통해 실행 중인 프록시에 핫 동기화(hot-syncs)하여, 재시작이나 요청 손실 없이 적용되게 합니다. 공유 프록시의 경우 이러한 오버라이드는 전역적이며, 마지막 명시적 설정이 우선합니다.

설정할 필요가 없도록 간결하게. 사람들은 자신이 얼마나 간결한 답변을 원하는지 거의 말하지 않습니다. 그들은 긴 답변을 중단하거나 읽기도 전에 넘어가는 방식으로 보여줍니다. headroom learn --verbosity

이 명령어는 이전 세션을 읽어 들여 적절한 수준을 파악합니다:

headroom learn --verbosity # dry run — 찾은 것을 미리보기
headroom learn --verbosity --apply # 저장합니다; 프록시가 이를 적용합니다

측정하기. 출력 절감량은 반사실적(counterfactual)입니다. 즉, 모델이 어떤 내용을 작성했을지 우리는 결코 볼 수 없으므로, Headroom은 신뢰 범위와 함께 추정치로 보고하며 다음과 같이 표시합니다:

headroom output-savings
# 감소율: 31.7% (95% CI 27.7% … 35.7%) [추정]

측정된 수치를 원한다면, 대화의 10%를 비형태적(unshaped) 제어군으로 제외합니다: export HEADROOM_OUTPUT_HOLDOUT=0.1

이렇게 하면 대시보드의 출력 토큰 절감량 카드에 '추정' 대신 '측정됨'이 표시되며, 범위도 함께 나타납니다.

어떤 OpenAI 호환 클라이언트든 headroom proxy를 통해 작동합니다.

. MCP 네이티브 클라이언트:
headroom mcp install

. 내구성 있는 래핑을 되돌리려면 headroom unwrap <도구>를 사용합니다 (claude, copilot, codex, grok, kimi, omp, opencode, openclaw, zcode). 레지스트리 작성자는 산문에서 headroom mcp serve 계약을 재구성하기보다는 표준적인 server.json을 사용해야 합니다.

Anthropic의 /v1/messages의 경우, --mode cache를 사용하면 자동 --memory 컨텍스트 주입이 건너뛰어져 제공자 접두사(provider prefix)가 안정적으로 유지됩니다. OpenAI 채팅/응답과 Gemini는 메모리를 라이브 영역 끝에 추가합니다. Anthropic 경로에서 자동 메모리 컨텍스트가 필요할 때는 --mode token을 사용하십시오.

GitHub Copilot CLI 구독 모드

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

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

이 래퍼(wrapper)는 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 엔드포인트를 사용합니다.

플랫폼 지원. macOS 인증 재사용을 위해 Copilot CLI Keychain 저장소를 이용하고 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 프록시 엔드포인트를 오버라이드(override)하므로, 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와 동일한 사용자 설정을 읽습니다. 프록시 추가(proxy extra)를 설치한 다음, VS Code에서 열 프로젝트의 디렉토리에서 래퍼(wrapper)를 실행합니다:

pip install "headroom-ai[proxy]"
headroom wrap vscode-claude
# 선택 사항: Claude Code가 소유한 클라이언트 전용 1M 모델 셀렉터 유지하기
...

첫 실행 시 VS Code 창을 새로고침하세요. Claude Code 패널을 사용하는 동안 래퍼 터미널은 계속 실행 상태로 두세요. 시작 시 표시되는 대시보드나 프록시 로그에는 요청 및 절약량이 표시됩니다. Anthropic 인증 정보와 선택된 모델이 유지됩니다. Ctrl+C는 프록시를 중지시키고, headroom unwrap vscode-claude는 설정 구성 전의 설정을 복원합니다.

--1m을 사용하면 Headroom은 해결된 [1m] 모델 셀렉터를 Claude Code의 최상위 사용자 설정에 기록하고, headroom unwrap vscode-claude를 실행하거나 --1m 없이 설정이 다시 실행될 때 정확한 이전 모델을 복원합니다. 파일에 쓰지 않고 설정을 출력하려면 headroom wrap vscode-claude --no-configure --1m을 사용하세요.

Claude Code와 Anthropic의 자체 1M 모델 지원 및 계정 적격성은 해당됩니다. 로컬 테스트는 지속된 설정과 복원을 증명하는 것이며, 라이브로 권한이 부여된 VS Code 세션이나 결과 컨텍스트 창은 아닙니다. 전체 가이드 →

다음 경우에 적합합니다: 매일 코딩 에이전트를 사용하며 코드 수정 없이 절약을 원할 때, 여러 에이전트에서 작업하며 공유 메모리를 원할 때, 또는 압축이 되돌릴 수 있는(reversible) 것이 필요할 때 — 원래 데이터는 구성된 TTL을 통해 CCR로 검색 가능하게 유지됩니다.

다음 경우 건너뛰세요: 단일 제공업체의 네이티브 압축만 사용하고 크로스-에이전트 메모리가 필요하지 않을 때, 또는 로컬 프로세스가 실행될 수 없는 샌드박스 환경에서 작업할 때.

Headroom은 무거운 도구 출력이 있는 긴 에이전트 세션에서 효과를 발휘합니다. 짧은 대화 교환, 산문, 이미 밀도가 높은 페이로드에서는 적거나 전혀 감소가 없으며, min_input_words 미만의 블록은 바이트 단위로 동일하게 복원됩니다.

제한 사항에는 전체 목록이 있습니다.

통합(Integrations) — Headroom을 모든 스택에 적용하세요