Claude Code는 터미널 환경에서 소스 코드를 탐색하고, 컴파일 오류를 분석하며, 테스트와 명령을 직접 수행하는 자율형 코딩 에이전트 CLI 도구입니다. 그러나 프로젝트 내 여러 파일을 열람하거나 긴 빌드 및 테스트 로그를 실행할 때마다 대량의 텍스트가 컨텍스트로 누적됩니다. 이러한 누적 데이터는 언어 모델로 전달되는 프롬프트의 입력 토큰을 급증시켜 처리 속도를 떨어뜨리고 비용 부담을 가중시킵니다.
Headroom은 터미널 코딩 에이전트와 상위 언어 모델 API 사이에서 동작하는 로컬 프록시 CLI 도구입니다. Claude Code가 전송하는 네트워크 요청을 중간에서 가로채 대규모 파일 내용이나 도구 실행 출력을 모델에 전달하기 직전에 최적화된 형태로 압축합니다. Anthropic 로그인 인증 정보나 프로젝트 소스 코드를 직접 수정하지 않고도 네트워크 계층에서 투명하게 작동하는 것이 핵심 구조입니다.
이 글에서는 호스트 운영체제의 파이썬 환경을 오염시키지 않고 uv tool을 사용해 Headroom CLI를 격리 설치한 뒤, 터미널에서 headroom wrap claude 명령어로 Claude Code를 연결하고, 로컬 웹 대시보드와 HTTP 응답 헤더를 통해 토큰 압축이 정상적으로 이루어지는지 판정하는 표준 절차를 정리합니다.
Claude Code의 컨텍스트 급증 원인과 Headroom 프록시의 중계 방식
Claude Code를 터미널에서 작업 도구로 활용할 때 발생하는 주요 병목은 도구 출력 결과와 소스 코드 열람 데이터의 누적입니다. 에이전트가 복잡한 디버깅이나 기능 구현을 처리하려면 파일 전체를 순차적으로 조회하고 린터 출력이나 테스트 실행 결과를 수집해야 합니다. 이 모든 텍스트가 대화 이력과 결합되면서 다음 요청의 입력 프롬프트 크기가 기하급수적으로 팽창합니다.
Headroom은 이러한 도구 출력을 실제 모델에 도달하기 전에 압축하기 위해 고안되었습니다. 프록시 계층이 Claude Code의 요청을 받아 긴 로그와 파일 읽기 결과를 처리 가능한 형태로 축소한 뒤 Anthropic 엔드포인트로 중계합니다. 사용자가 기존에 구성해 둔 Anthropic 로그인 세션과 선택된 기본 모델을 그대로 유지하면서 컨텍스트 크기만 줄이는 중계 방식으로 작동합니다.
별도의 설정 파일을 작성하거나 소스 코드 내부에 서드파티 SDK를 임베딩할 필요 없이, 단일 터미널 래퍼 명령어를 통해 프록시와 에이전트 세션을 결합할 수 있어 작업 흐름이 단순하게 유지됩니다.
사전 요구 조건 및 uv tool 기반 CLI 격리 설치
Headroom CLI를 실행하려면 시스템에 Python 3.10 이상 버전이 설치되어 있어야 합니다. 이 도구는 PyPI에 headroom-ai 패키지로 배포되며, CPython 3.10부터 3.13 버전을 대상으로 사전 빌드된 릴리스 휠을 제공합니다. 지원 플랫폼은 Linux(manylinux_2_28 x86_64 및 aarch64), macOS(Apple Silicon 및 Intel), Windows x86_64 환경을 포함합니다.
macOS 및 Linux 호스트 터미널에서 시스템 전역 headroom 명령어를 구성할 때는 현재 셸이나 특정 프로젝트의 파이썬 종속성과 격리된 앱 환경을 만들어 주는 uv tool install 방식을 권장합니다. 특히 전체 부가 종속성을 포괄하기 위해 Python 3.13 버전을 명시하여 설치하는 것이 공식 가이드의 표준 경로입니다.
# 1. uv tool을 사용하여 Python 3.13 기반 격리 앱 환경에 Headroom CLI 설치
uv tool install --python 3.13 "headroom-ai[all]"
# 2. 설치 버전 및 CLI 실행 가능 여부 점검
headroom --version
# 3. 설치 완료 후 PATH 미인식 시 셸 설정 동기화
uv tool update-shell- 터미널을 열고
uv tool install --python 3.13 "headroom-ai[all]"명령을 실행해 전용 가상 환경에 바이너리를 구성합니다. - 설치가 완료되면
headroom --version명령을 입력하여 설치된 도구의 버전 정보가 올바르게 출력되는지 확인합니다. - 만약 설치가 성공했다는 안내가 나왔음에도 터미널에서
headroom명령어를 찾지 못한다면uv tool update-shell명령을 실행해 셸의 실행 경로 환경 변수를 갱신합니다.
설치 과정에서 유의해야 할 런타임 제약 사항이 있습니다. Python 3.14 이상 환경에서는 호환 가능한 빌드 휠 부재로 인해 proxy, voice, relevance, image 부가 패키지에서 선택적 ONNX 백엔드가 제외됩니다. 코어 압축과 기본 프록시는 작동하지만 머신러닝 기반 콘텐츠 감지, 로컬 ONNX Kompress, 임베딩 관련성 분석, ONNX OCR 등의 기능은 비활성화되므로 해당 기능이 필요하다면 반드시 Python 3.13을 사용해야 합니다. 또한 npm 저장소에 등록된 동명의 패키지는 코드 내부 임포트용 라이브러리일 뿐이며, headroom wrap이나 headroom proxy 같은 CLI 명령어를 제공하지 않으므로 반드시 파이썬 패키지로 설치해야 합니다.
headroom wrap claude 명령을 통한 터미널 Claude Code 래핑 실행
CLI 설치와 셸 경로 설정이 완료되면 터미널 환경에서 Claude Code를 래핑하여 실행할 수 있습니다. VS Code 내부 확장 프로그램 환경이 아니라 터미널 콘솔에서 Claude Code CLI를 직접 다루는 사용자의 경우 headroom wrap claude 명령어가 공식 표준 연동 경로입니다.
이 명령어는 로컬 머신에서 Headroom 압축 프록시 서버를 백그라운드로 초기화하는 동시에 Claude Code 세션을 감싸서 실행합니다. Claude Code가 소스 코드 분석, 파일 내용 확인, 빌드 명령 실행 등을 처리하면서 생성하는 모든 도구 읽기 결과가 Anthropic API 서버로 발송되기 직전에 로컬 프록시를 통과하며 압축됩니다.
# 작업할 프로젝트 디렉터리로 이동한 뒤 래핑 명령어 실행
cd "/path/to/your-project"
headroom wrap claude- Claude Code를 사용하려는 프로젝트의 루트 디렉터리로 이동합니다. 위 예시의 경로 문자열은 작업 환경의 실제 프로젝트 디렉터리 경로로 대체해야 합니다.
- 터미널에
headroom wrap claude명령어를 입력합니다. - 로컬 프록시가 자동으로 가동되며 기존 터미널과 동일한 Claude Code 대화형 인터페이스가 화면에 표시됩니다.
래핑 실행 방식을 적용하면 Claude Code의 기존 계정 로그인 정보나 모델 설정 변경 없이 그대로 작동합니다. 에이전트가 실행하는 도구 명령과 소스 코드 열람 요청은 로컬 루프백 인터페이스를 통해 Headroom 프록시를 먼저 거친 뒤 외부 API로 전달되므로 추가적인 수동 네트워크 프록시 환경 변수 설정 없이도 투명하게 압축 파이프라인이 유지됩니다.
로컬 대시보드와 HTTP 응답 헤더를 통한 정상 압축 판정 기준
프록시 래핑을 적용한 뒤에는 도구 출력 압축이 누락 없이 실제로 수행되고 있는지 정량적으로 검증해야 합니다. Headroom은 프록시가 백그라운드에서 동작하는 동안 실시간 처리 지표를 확인할 수 있는 내장 웹 대시보드를 제공합니다.
# 새로운 터미널 세션에서 실시간 절감 대시보드 열기
headroom dashboard
# 브라우저를 자동으로 띄우지 않고 로컬 URL 주소만 출력할 경우
headroom dashboard --no-open- Claude Code 세션이 실행 중인 상태에서 별도의 새 터미널 창을 엽니다.
headroom dashboard명령을 실행하여 브라우저에서 기본 관리 주소인http://localhost:8787/dashboard를 호출합니다.- 브라우저 자동 팝업을 원하지 않는 환경이라면
headroom dashboard --no-open옵션을 사용하여 접속 URL만 확인할 수 있습니다. - Claude Code 창으로 돌아가 파일 읽기나 도구 실행을 수반하는 프롬프트 명령을 내립니다.
- 대시보드 화면의 지표 중 Tokens saved 수치가 요청 완료와 함께 지속적으로 증가하는지 확인합니다.
웹 대시보드 지표 확인 외에도 프록시가 반환하는 개별 네트워크 응답의 HTTP 헤더를 검사하여 압축 동작을 정밀하게 판정할 수 있습니다. 정상적으로 압축이 적용된 요청에는 다음 세 가지 헤더 값이 기록됩니다.
x-headroom-tokens-before: Headroom 로컬 프록시 계층이 요청을 수신했을 때의 원본 입력 토큰 수입니다.x-headroom-tokens-after: 도구 실행 출력과 컨텍스트를 압축하여 실제 모델로 전송한 최종 입력 토큰 수입니다.x-headroom-tokens-saved: 원본 토큰 수와 최종 전송 토큰 수의 차이로 계산된 순수 절감 토큰 수치입니다.
작업 도중 대시보드의 Tokens saved 수치가 0에 머물러 있거나 해당 응답 헤더가 확인되지 않는다면 프록시 프로세스가 비정상 종료되었거나 네트워크 루프백 연결이 차단되었는지 점검해야 합니다. 정상적인 환경에서는 Claude Code가 긴 파일과 터미널 출력을 참조할 때마다 x-headroom-tokens-saved 값이 0보다 큰 양수로 기록되며 대시보드의 누적 절감 그래프가 함께 갱신됩니다.
