gglucass/headroom-desktop

해결하는 문제

Headroom는 Claude Code 및 OpenAI Codex와 같은 AI 코딩 보조 도구 사용 시 발생하는 토큰 비용을 줄이기 위해 설계되었습니다. 특히 프롬프트 내의 '과잉' — 구체적으로 도구 출력, 로그, 반복 코드 — 가 AI의 추론 과정에 필요한 가치를 추가하지 않으면서도 비용을 증가시키는 문제에 초점을 맞춥니다.

작동 방식

Headroom는 코드 클라이언트와 LLM API 사이에 로컬 우선 프록시로 작동합니다. Rust로 작성된 인터셉트 프록시와 Python 최적화 백엔드를 사용하는 두 단계 로컬 프록시 시스템을 통해 API로 전송되기 전에 콘텐츠를 압축합니다.

주요 메커니즘:

• 관리되는 Python 런타임: 시스템 Python에 영향을 주지 않고 최적화 도구를 실행할 수 있도록 격리된 Python 환경을 설치합니다.
• 토큰 절약 도구: headroom를 통한 프롬프트 최적화 및 CLI 출력을 압축하는 rtk 등을 포함합니다.
• 역전 가능 압축: 압축된 데이터는 필요 시 모델이 원본 콘텐츠를 다시 추출할 수 있도록 설계되어 있습니다.
• 클라이언트 통합: Claude Code는 settings.json, Codex는 config.toml을 통해 자동으로 로컬 프록시를 통해 트래픽을 라우팅하도록 설정됩니다.

대상 사용자

코딩 워크플로우를 변경하지 않고 API 비용을 낮추고 토큰 한도를 늘리고 싶은 Claude Code 또는 OpenAI Codex 사용자.

주요 특징

• 매우 큰 비용 절감: 벤치마크 결과 HTML 추출 시 최대 94.9% 압축, JSON 로그 시 최대 87.6% 압축 가능.
• 호스트 오염 없음: 앱은 자체 의존성을 관리하며, 종료 또는 제거 시 모든 시스템 및 설정 변경 사항을 완전히 되돌립니다.
• 로컬 우선 개인정보 보호: 최종 API 호출 전까지 모든 처리가 127.0.0.1에서 이루어집니다.
• 분석 대시보드: 일일 및 월간 절감 금액 차트와 각 클라이언트별 토큰 통계 제공.
• 보수적인 코드 보호: 디버깅 및 분석 작업의 정확성을 보장하기 위해 의도적으로 활성 소스 코드는 압축하지 않습니다.