Headroom

요약

Headroom은 에이전트와 모델 사이의 프록시에서 입력 컨텍스트와 도구 출력을 압축해, 긴 코딩 세션에서도 필요한 정보는 남기고 토큰 사용량과 지연을 줄이는 오픈소스 도구입니다.

도구 소개

공식 README 기준으로 Headroom은 로컬 프록시, MCP, Python·TypeScript SDK, 이미지·코드·메모리·관련성 기반 압축 모듈을 제공합니다. 코딩 에이전트를 headroom wrap으로 감싸거나 headroom proxy로 연결해 기존 OpenAI 호환 클라이언트와 함께 사용할 수 있습니다.

압축 결과를 그대로 신뢰하는 대신, 처음에는 같은 작업을 압축 전·후로 실행해 파일 목록·오류 메시지·도구 결과가 보존되는지 비교하는 방식이 안전합니다.

사용 포인트

• 긴 저장소 작업에서 반복되는 도구 출력으로 컨텍스트가 빠르게 찰 때
• MCP와 코딩 에이전트를 함께 사용하면서 입력 크기를 관리할 때
• 프록시 적용 전·후 토큰 절감과 작업 성공률을 비교하는 실습을 만들 때
• Python 기반 에이전트 서비스에 컨텍스트 압축 계층을 붙일 때

설치와 시작

공식 README가 안내하는 격리된 CLI 설치 경로입니다.

uv tool install --python 3.13 "headroom-ai[all]"

Python 패키지로 설치하거나 TypeScript SDK만 사용할 수도 있습니다.

pip install "headroom-ai[all]"
npm install headroom-ai

설치 후에는 공식 문서의 래퍼·프록시 모드 중 하나를 선택해 테스트 프로젝트에서 먼저 실행합니다. 프레임워크 어댑터가 필요하면 [langchain], [agno] 같은 추가 기능을 별도로 설치합니다.

선정 사유

GitHub API에서 64,063 stars와 2026-08-02 최신 push를 확인했고, 공식 README와 실제 동작 화면을 직접 확인했습니다. 단순 모델 교체가 아니라 에이전트가 길게 실행될수록 커지는 컨텍스트·도구 출력 문제를 프록시 계층에서 다루므로, 업무 자동화와 에이전트 운영 교육에 재사용할 수 있는 실용성이 있습니다.

참고

• GitHub 저장소
• 공식 문서
• 이미지는 공식 README의 Headroom 동작 화면에서 대표 프레임을 사용했습니다.
• Reddit과 국내 사용자·개발자 커뮤니티를 각각 실제 검색했으나 양쪽 모두 HTTP 202 챌린지와 0 링크로 후보별 공개 반응을 검증하지 못했습니다. 익명 반응 요약은 생략했습니다. 정확한 쿼리와 응답은 internal/run-notes/2026-08-03-picks-curation-batch.md에 기록했습니다.