Show HN: Claude-thermos keeps your Claude session warm for you

개요

Claude Code의 프롬프트 캐시 만료로 인한 비용 증가 문제를 해결하기 위해 개발된 claude-thermos는 Claude 세션을 지속적으로 따뜻하게 유지하여 불필요한 재인코딩 비용을 절감하는 도구입니다.

주요 내용

* Claude Code 캐시 만료 및 비용 문제: Claude Code에서 메인 에이전트가 서브 에이전트의 응답을 5분 이상 기다리면 프롬프트 캐시가 만료됩니다. 이후 대화 기록이 재인코딩되면서 원가 대비 약 20%의 추가 비용이 발생할 수 있습니다.
* claude-thermos의 작동 방식: claude-thermos는 로컬 리버스 프록시를 사용하여 Claude Code 트래픽을 감시합니다. 메인 에이전트가 유휴 상태이고 서브 에이전트가 실행 중일 때, 5분 TTL 전에 메인 에이전트의 마지막 요청을 캐시 갱신을 위한 "웜(warm)" 요청으로 다시 보냅니다. 이 웜 요청은 실제 트래픽에 영향을 주지 않으며, 캐시를 살아있게 유지하여 재인코딩 비용을 방지합니다.
* 사용법: Python 3.11 이상 및 Claude CLI가 설치되어 있으면 uvx claude-thermos 명령어로 claude-thermos를 실행할 수 있으며, 기존 Claude CLI 인수는 그대로 전달됩니다. CLAUDE_WARMER_DISABLE=1 환경 변수를 설정하여 일시적으로 비활성화할 수 있습니다.
* 튜닝 옵션: --idle(메인 에이전트 유휴 시간), --interval(웜 주기), --max-cycles(최대 웜 횟수), --subagent-window(서브 에이전트 활성 시간) 등의 옵션을 통해 웜 동작을 미세 조정할 수 있습니다.
* 비용 절감 효과: 웜 요청은 저렴한 캐시 읽기(0.1x)로 처리되는 반면, 방지된 재인코딩은 훨씬 큰 데이터에 대한 쓰기(1.25x) 비용이 발생하므로 비용 절감 효과가 큽니다.
* 로깅 및 요약: 각 세션은 ~/.claude-thermos/logs/<session_id>/events.jsonl 및 summary.json 파일에 이벤트 기록과 요약 정보를 저장합니다. summary.json에는 웜 횟수, 캐시 읽기 토큰, 회피된 재인코딩 토큰, 발생한 비용 및 순수 절감액 등이 포함됩니다.

시사점

claude-thermos는 Claude Code 사용 시 발생하는 숨겨진 캐시 관련 비용을 효과적으로 관리하고 절감할 수 있는 실용적인 솔루션을 제공하여, 장시간 세션이나 복잡한 에이전트 워크플로우에서 경제성을 향상시킬 수 있습니다.