토큰 소모량을 60~95%까지 줄여주는 Headroom 사용 방법
2,581
설명
헤드룸(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
신고 · 불법·유해·아동 안전(CSAE) 관련 콘텐츠
댓글 1
Windows 환경에서 파이썬을 사용할 때 아주 흔하게 발생하는 인코딩(Encoding) 오류가 발생하는데, 아래 내용참고 바랍니다. 1. 원인 분석 Headroom이 headroom wrap cursor 명령어를 수행하면서, Cursor 관련 설정 파일이나 프로젝트 내의 특정 가이드 파일(예: .cursorrules, README.md 등)을 읽어와 RTK(Rust Token Killer) 관련 지침을 주입(_inject_rtk_instructions)하려 시도했습니다. 이때 파이썬의 pathlib 모듈이 파일을 읽으려고 했는데, Windows 한국어 기본 인코딩인 cp949(MS949)로 파일을 읽으려다 보니 파일 내에 포함된 한글이나 특수문자(UTF-8)를 해석하지 못해 UnicodeDecodeError를 뱉으며 프로그램이 뻗어버린 것입니다. (Headroom 내부 코드에서 파일을 열 때 encoding='utf-8' 명시를 누락한 일종의 Windows 호환성 버그입니다.) 2. 해결 방법 이 문제를 우회하고 정상적으로 실행할 수 있는 방법은 크게 두 가지가 있습니다. 방법 ①: Windows 시스템의 기본 파이썬 인코딩을 UTF-8로 강제하기 (가장 추천) Windows 10/11 환경에서 파이썬이 cp949 대신 전 세계 표준인 utf-8을 기본으로 사용하도록 환경 변수를 지정해주면 해결됩니다. 현재 열려 있는 PowerShell 창을 닫습니다. 새 PowerShell 창을 관리자 권한으로 엽니다. 아래 명령어를 입력하여 시스템 환경 변수에 PYTHONUTF8=1을 등록합니다. PowerShell [Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User") PowerShell을 완전히 종료한 후 다시 실행합니다. (환경 변수 적용을 위해 필수) 다시 프로젝트 폴더로 이동하여 명령어를 실행합니다. PowerShell headroom wrap cursor 방법 ②: 문제가 되는 설정 파일 임시 조치하기 만약 방법 ①로도 해결되지 않는다면, Headroom이 읽으려고 시도한 프로젝트 내 파일 중 한글이 포함된 설정 파일이 원인일 가능성이 높습니다. 현재 C:\dev\AIsle> 폴더 내에 .cursorrules 파일이나 README.md 파일이 있고, 그 안에 한글 주석이나 설명이 들어있는지 확인해 보세요. 해당 파일들을 잠시 다른 곳으로 백업해두거나 한글 내용을 지운 뒤 headroom wrap cursor를 실행하고, 세팅이 끝난 후에 다시 한글을 복구하는 방식으로 우회할 수 있습니다. 💡 추가 안내 (중요) 사실 headroom wrap 명령어는 claude, aider 같은 CLI(터미널 기반) 에이전트 도구를 실행할 때 그 프로세스를 감싸기(Wrap) 위해 설계된 명령어입니다. Cursor는 터미널 도구가 아니라 독립된 GUI 프로그램(IDE)이기 때문에, headroom wrap cursor가 정상적으로 실행되더라도 내부적으로 완벽히 동작하지 않을 수 있습니다. 만약 위의 인코딩 오류를 해결한 후에도 Cursor와 연동이 매끄럽지 않다면, 앞서 소개해 드린 [방법 ②: 로컬 프록시 방식]으로 우회하여 사용하는 것을 강력히 권장합니다. 터미널에 프록시 서버 실행: headroom proxy --port 8787 Cursor 설정(Models)에서 Base URL을 http://localhost:8787로 변경