cnighswonger/claude-code-cache-fix

해결하는 문제

이 프로젝트는 과도한 토큰 사용(쿼터 소모) 및 불안정한 캐시 읽기 비율을 초래하는 Claude Code의 프롬프트 캐시 버그를 해결합니다. 특히 재개된 세션 또는 장시간 실행되는 세션에서 캐시 생성 토큰이 반복적으로 급증하는 문제를 수정하여 불필요한 비용을 방지하고 요청 접두사(prefix)를 안정화합니다.

작동 방식

Claude Code와 Anthropic API 사이에서 로컬 HTTP 프록시로 작동합니다. 프록시는 POST /v1/messages 요청을 가로채고 재작성하여 요청 구조(블록 순서, fingerprint, TTL 등)를 정규화함으로써 프롬프트 캐싱이 효율적으로 작동하도록 보장합니다.

두 가지 주요 동작 모드를 제공합니다:

• Reverse-Proxy 모드: 사용자가 Claude Code의 ANTHROPIC_BASE_URL을 프록시로 지정합니다.
• Forward-Proxy 모드: 프록시가 HTTPS_PROXY 역할을 수행하며, 로컬에서 생성된 CA를 사용하여 api.anthropic.com의 TLS를 종료함으로써 Claude Code의 내부 기능(Remote Control 등)을 활성화된 상태로 유지하면서 요청 변환을 허용합니다.

대상 사용자

Claude Code를 사용하면서 높은 토큰 비용, 긴 세션에서의 낮은 캐시 히트율, 또는 엄격한 API 쿼터 압박을 겪고 있는 개발자.

주요 특징

• 캐시 최적화: 캐시 히트율을 높입니다 (예: 일부 테스트에서 82.3%에서 95.5%로 증가).
• 투명한 통합: Bun 바이너리를 포함한 모든 Claude Code 버전과 호환됩니다.
• Remote Control 지원: 포워드 프록시 모드를 통해 커스텀 base URL 사용 시 비활성화될 수 있는 Claude Code의 고급 기능을 사용할 수 있습니다.
• 관측 가능성(Observability): 설치 전 세션 트랜스크립트를 통해 캐시 상태를 측정할 수 있는 도구를 포함합니다.
• ListNode: 실제 대화 내용을 수정하지 않는 멱등적(Idempotent) 변환을 수행합니다.