토큰 소모량을 60~95%까지 줄여주는 Headroom 사용 방법
5
설명
헤드룸(Headroom)은 넷플릭스의 시니어 엔지니어(Chopra)가 개발하여 오픈소스로 공개한 AI 에이전트 전용 토큰 압축 및 최적화 레이어입니다.
Cursor나 Claude Code 같은 AI 코딩 툴을 쓰다 보면 방대한 로그, RAG 청크, 툴 호출 결과(grep, 파일 읽기 등)가 누적되면서 엄청난 양의 컨텍스트(토큰)를 소모하게 되는데, Headroom은 이를 LLM으로 보내기 전에 미리 압축하여 토큰 소모량을 60~95%까지 줄여주는 역할을 합니다.
Headroom의 핵심 특징과 Cursor 및 Claude(Claude Code 등)에서 사용하는 방법을 정리해 드립니다.
1. Headroom의 주요 특징
* 혁신적인 토큰 및 비용 절감: 실제 워크로드에서 답변의 정확도를 유지하면서도 60~95%의 토큰을 압축해 줍니다. (실제 사용 데이터 기준 수억 개의 토큰을 아끼고 막대한 API 비용을 절감함)
* 스마트 라우팅 (ContentRouter): 전송하려는 데이터가 코드 로그인지, 파일 본문인지, 검색 결과(RAG)인지 자동으로 감지하여 컨텐츠 유형에 맞는 최적의 알고리즘으로 압축합니다.
* 가역성 (Reversible / Lossless): 원본 데이터를 완전히 지우는 것이 아니라 필요할 때 LLM이 다시 복원(Retrieve)하여 읽을 수 있도록 설계되어 정확도 손실이 거의 없습니다.
* 크로스 에이전트 메모리 (Cross-Agent Memory): 여러 에이전트나 툴(예: Claude와 Codex)을 동시에 띄워놓고 쓸 때, 중복된 컨텍스트를 제거하고 에이전트 간 압축된 메모리를 공유할 수 있습니다.
* 자가 학습 기능 (headroom learn): AI 에이전트가 실패한 세션 로그를 분석하여 오류 패턴을 파악한 뒤, 이를 프로젝트의 CLAUDE.md, GEMINI.md 같은 가이드 파일에 자동으로 반영해 다음 번에 같은 실수를 하지 않도록 돕습니다.
2. Cursor 및 Claude에서 사용하는 방법
Headroom은 기존 코드를 거의 수정하지 않거나, 로컬 프록시 레이어를 통해 AI 코딩 툴의 트래픽을 가로채는 방식으로 동작합니다. (Python 3.10+ 환경이 필요합니다.)
방법 ①: 가장 간단한 방법 (터미널 래핑)
기존에 사용하는 AI CLI 에이전트(Claude Code, Aider, Copilot CLI 등)를 실행할 때 Headroom으로 감싸서 실행하는 제로 코드(Zero-code) 방식입니다.
1. 터미널에서 Headroom을 설치합니다.
Bash
pip install "headroom-ai[all]"
2. Claude Code나 다른 CLI 에이전트를 실행할 때 앞에 headroom wrap을 붙여 실행합니다.
Bash
headroom wrap claude
# 또는 다른 AI 코딩 CLI 도구 이름
이렇게 하면 Headroom이 자동으로 백그라운드에서 발생하는 툴 호출 및 컨텍스트 트래픽을 가로채 압축한 뒤 Anthropic/OpenAI 서버로 전달합니다.
방법 ②: 로컬 프록시 (Drop-in Proxy) 방식으로 Cursor 연결하기
Cursor와 같이 GUI 기반의 IDE UI에서 사용하려면 Headroom을 로컬 프록시 서버로 띄우고, Cursor가 이 프록시를 바라보게 설정해야 합니다.
1. 로컬 PC 터미널에서 Headroom 프록시 서버를 실행합니다.
Bash
headroom proxy --port 8787
2. Cursor 설정 변경:
* Cursor의 Settings(설정) -> Models -> OpenAI/Anthropic API 키 설정 부분으로 이동합니다.
* Base URL(기본 URL) 입력란을 공식 서버 주소가 아닌, Headroom 프록시 주소인 http://localhost:8787로 변경합니다.
* 이렇게 설정하면 Cursor 내부에서 나누는 대화, 대량의 코드 컨텍스트 파일들이 로컬 Headroom을 거쳐 압축된 후 AI 모델로 전송됩니다.
방법 ③: MCP(Model Context Protocol) 서버로 등록하기
만약 MCP를 지원하는 에이전트 환경(예: Claude Desktop 등)을 사용 중이라면 Headroom을 MCP 서버로 직접 등록하여 쓸 수 있습니다.
1. 터미널에 아래 명령어를 입력하여 MCP 서버로 등록합니다.
Bash
headroom mcp install
2. 이 작업이 완료되면 에이전트가 headroom_compress, headroom_retrieve, headroom_stats 등의 도구를 인식하여 스스로 컨텍스트를 압축하고 관리하게 됩니다.
💡 팁: 내 절약 스탯 확인하기
Headroom을 적용해 한참 코딩을 진행한 후, 아래 명령어를 터미널에 입력하면 내가 토큰을 얼마나 압축했고 비용을 얼마나 아꼈는지 누적 통계(stats)를 한눈에 볼 수 있습니다.
Bash
headroom stats
댓글 0
아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.