headroomlabs-ai/headroom

어떤 프로젝트인가요?

핵심 기능

• 01JSON, 코드, 산문에 맞는 압축기를 선택하는 콘텐츠 유형 라우팅.
• 02원본을 로컬에 캐시해 필요할 때 가져올 수 있는 가역 압축.
• 03인기 코딩 에이전트에서 코드 변경 없이 사용할 수 있는 프록시와 한 번의 명령으로 설정하는 래퍼.
• 04인라인 사용을 위한 compress()를 제공하는 Python 및 TypeScript 라이브러리.
• 05compress, retrieve, stats 도구를 제공하는 MCP 서버.
• 06로컬 처리로, 프롬프트와 파일 콘텐츠를 압축 서비스에 전송하지 않습니다.

활용 사례

• 도구 출력을 많이 사용하는 긴 세션에서 Claude Code나 Cursor 같은 코딩 에이전트의 토큰 비용 절감.
• 디버깅을 위해 모델에 전달하기 전에 로그 덤프나 대용량 JSON 검색 결과 압축.
• 기존 LangChain 또는 LiteLLM 파이프라인에서 검색된 RAG 청크의 크기 축소.
• 여러 에이전트를 하나의 공유 프록시와 메모리 계층으로 라우팅.

빠른 시작

1. 1

   uv로 CLI를 설치하세요

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

   또는 pip로 Python 패키지를 설치하세요

   pip install "headroom-ai[all]"
3. 3

   포트 8787에서 드롭인 프록시를 시작하세요

   headroom proxy --port 8787
4. 4

   헬스 체크로 설치를 확인하세요

   headroom doctor

사용 전 알아둘 점

• !절감 효과는 크게 달라집니다. 산문이나 이미 밀도가 높은 출력은 거의 압축되지 않습니다.
• !README의 압축 벤치마크는 자체 보고된 결과이며, 특정 시드가 설정된 시나리오에서 실행되었습니다.

토픽

자주 묻는 질문

headroom은(는) 무엇인가요?

LLM에 전달하기 전에 도구 출력, 로그, 파일, RAG 청크를 라이브러리·프록시·MCP 서버 형태로 압축합니다. Headroom은 AI 에이전트와 LLM 애플리케이션을 위한 컨텍스트 압축 계층입니다. 도구 출력, 로그, RAG 청크, 파일, 대화 기록을 모델에 전달하기 전에 압축하며, 압축 작업은 사용자 컴퓨터에서 로컬로 실행됩니다. 콘텐츠 라우터가 각 페이로드의 유형을 판별해 JSON은 SmartCrusher로, 소스 코드는 AST를 인식하는 CodeCompressor로, 산문은 Kompress-v2-base 모델로 전달합니다.

headroom은(는) 무료로 사용할 수 있나요? 라이선스는 무엇인가요?

headroom은(는) Apache-2.0 라이선스의 오픈소스입니다. 상업용 제품에 사용하기 전에 라이선스 조건을 확인하세요.

headroom은(는) 아직 유지보수되고 있나요?

활발히 유지보수 중. headroom의 마지막 커밋은 2026년 10월 17일입니다.

headroom은(는) 어디에 사용할 수 있나요?

도구 출력을 많이 사용하는 긴 세션에서 Claude Code나 Cursor 같은 코딩 에이전트의 토큰 비용 절감. 디버깅을 위해 모델에 전달하기 전에 로그 덤프나 대용량 JSON 검색 결과 압축. 기존 LangChain 또는 LiteLLM 파이프라인에서 검색된 RAG 청크의 크기 축소. 여러 에이전트를 하나의 공유 프록시와 메모리 계층으로 라우팅.

headroom는 어떻게 설치하나요?

uv로 CLI를 설치하세요: uv tool install --python 3.13 "headroom-ai[all]" 또는 pip로 Python 패키지를 설치하세요: pip install "headroom-ai[all]" 포트 8787에서 드롭인 프록시를 시작하세요: headroom proxy --port 8787 헬스 체크로 설치를 확인하세요: headroom doctor

headroom은(는) 어디서 받을 수 있나요?

소스 코드와 설치 방법은 GitHub에 있습니다: https://github.com/headroomlabs-ai/headroom