Claude-thermos: Claude Code에서 프롬프트 캐시 만료 방지
Claude-thermos: Claude Code에서 프롬프트 캐시 만료 방지
Claude-thermos는 프롬프트 캐시 따뜻함을 유지하여 API 비용을 줄입니다
claude-thermos는 Claude Code 세션에서 '캐시 세금'을 제거하도록 설계된 유틸리티입니다. 메인 에이전트가 서브에이전트에 의해 5분 이상 차단될 때 프롬프트 캐시의 silenz한 만료를 방지하며, 이는 그렇지 않을 경우 사용자의 총 API 청구액의 약 20%를 차지할 수 있습니다.
문제: 서브에이전트 실행 중 캐시 만료
Claude Code의 프롬프트 캐시는 5분의 Time-to-Live (TTL)를 가집니다. 캐시된 기록은 입력 가격의 0.1x로 제공되지만, 캐시 미스는 대화 기록의 전체 재인코딩을 1.25x 쓰기 속도로 강제합니다. 이는 개별 붕괴가 200K에서 500K 토큰을 다시 쓸 수 있는 긴 세션에서는 지나치게 비싸질 수 있습니다.
캐시 만료의 주요 트리거는 사용자 비활성이 아니라 서브에이전트의 행동입니다. 서브에이전트는 서로 다른 시스템 프롬프트와 도구 세트를 사용하기 때문에 서로 다른 캐시 접두사를 생성합니다. 서브에이전트가 실행되는 동안 메인 에이전트의 캐시 접두사는 건드리지 않은 상태로 유지됩니다. 서브에이전트의 작업이 5분보다 오래 걸리면 메인 에이전트의 캐시가 만료됩니다. 서브에이전트가 메인 에이전트에 제어를 반환할 때, 메인 에이전트는 전체 기록을 다시 인코딩해야 하며 이로 인해 상당한 비용이 발생합니다.
claude-thermos가 캐시를 유지하는 방법
claude-thermos는 ANTHROPIC_BASE_URL을 루프백 포트로 가리켜 로컬 역방향 프록시로 작동합니다. 다음과 같은 4단계 과정을 통해 캐시를 관리합니다:
- Observation: 프록시는
/v1/messages트래픽을 모니터링하여 세션과 "라인리지"(모델, 도구 세트, 시스템 텍스트로 정의됨)로 요청을 그룹화합니다. 첫 번째 도구를 포함하는 라인리지를 메인 에이전트로 식별합니다. - Detection: 메인 라인리지가 유휴 상태이고 서브에이전트가 활발히 실행 중인 "위험 창"을 식별합니다.
- Warming: 5분 TTL이 만료되기 전에, 프록시는 Anthropic API에 직접 "워밍 요청"을 보냅니다. 이 요청은 동일한 캐시 가능한 접두사를 사용하지만
max_tokens: 1로 설정하고 스트리밍을 비활성화합니다. - Refresh: 단일 토큰은 버려지며, 목적은 프리필로, 이는 저렴한 읽기 속도(0.1x)에서 전체 캐시 접두사를 새로 고쳐서 비용이 많이 드는 재작성(1.25x)을 피합니다.
설치 및 사용법
claude-thermos는 시스템 PATH에 Python 3.11+와 claude CLI가 설치되어 있어야 합니다. uvx를 사용하여 실행할 수 있습니다:
- Standard run:
uvx claude-thermos(claude명령을 대체) - With arguments:
uvx claude-thermos -p "fix the bug"(인수는 Claude CLI에 직접 전달됨)
구성 튜닝
사용자는 다음 선택적 플래그를 조정하여 워밍 동작을 튜닝할 수 있습니다:
| Flag | Default | Meaning |
|---|---|---|
--idle |
270 |
의미: 메인 에이전트가 워밍이 시작되기 전에 유휴 상태여야 하는 초 |
--interval |
270 |
의미: 워밍 사이클 사이의 초 |
--max-cycles |
4 |
의미: 유휴 에피소드당 최대 워밍 횟수 (auto이면 무제한) |
--subagent-window |
540 |
의미: 서브에이전트가 '여전히 활성'으로 간주되는 초 |
명령을 변경하지 않고 특정 실행에서 워밍을 비활성화하려면 환경 변수 CLAUDE_WARMER_DISABLE=1를 설정하세요.
절감 추적
각 세션은 ~/.claude-thermos/logs/<session_id>/에 events.jsonl 스트림과 summary.json 롤업을 포함하는 로그를 생성합니다. summary.json 파일은 다음과 같은 메트릭을 제공합니다:
warms_fired: 전송된 총 워밍 요청 수.cache_read_total: 워밍 중에 읽은 토큰 수.rewrite_avoided_tokens: 캐시가 만료되었더라면 다시 쓰여졌을 토큰 수.net_savings: 방지된 재작성 비용(1.25x)과 워밍 비용(0.1x)의 차이, 기본 입력 토큰 단위로 측정.
실제 달러 절감액을 계산하려면 net_savings 값에 모델의 입력 토큰당 가격을 곱하세요.
커뮤니티 토론 및 반론
캐시 TTL 차이
몇몇 사용자는 Pro 및 Max 플랜의 경우 캐시 만료가 5분이 아니라 1시간일 수 있다고 지적했습니다.
"저는 pro/Max 플랜에 대한 호출을 직접 검사했으며, 오늘 기준으로 그들은 1시간 캐시 만료를 가지고 있습니다... API 요금을 지불하고 있다면, 5m 또는 1hr 중에서 직접 선택할 수 있습니다."
리소스 사용 및 윤리
몇몇 사용자는 자동화된 워밍 요청이 공유 자원의 비극을 초래할 수 있다고 우려했습니다. 이는 기능적인 출력 없이 Anthropic 인프라에 부하를 증가시킬 수 있습니다.
"이는 단지 모두에게 더 비싸게 만들고 있을 뿐이죠? ...저도 항상 큐의 앞에 서기를 요구하지는 않을 거예요."
반대로, 다른 사용자들은 이 도구가 제공업체에게 결함이 있는 캐시 메커니즘을 해결하도록 강요한다고 주장했습니다. 이 메커니즘은 서브에이전트가 필요한 에이전트 워크플로우를 사용하는 사용자에게 벌칙을 부과합니다.}
SUMMARY: Claude-thermos는 메인 에이전트가 서브에이전트에 의해 차단될 때 자동으로 '워밍' 요청을 Anthropic API에 보내어 Claude Code에서 비용이 많이 드는 프롬프트 캐시 재구성을 방지하는 로컬 역방향 프록시입니다.
TITLE: Claude-thermos: Claude Code에서 프롬프트 캐시 만료 방지