kvleak은 캐시 적중률이 높아도 새는 비용을 찾아낸다

kvleak은 Claude Code의 캐시 적중률이 95%를 넘더라도 입력 비용의 4분의 1가량이 캐시 재구축에 쓰일 수 있다고 설명하는 도구다. 로컬에 저장된 세션 파일을 분석해 비용이 새는 지점을 보여주고, 설정을 한 번에 조정하는 기능도 제공한다.

설치는 uvx kvleak, pipx run kvleak 또는 pip install kvleak으로 할 수 있다. API 키와 설정, 네트워크 연결, 추가 의존성은 필요하지 않다. Claude Code, Codex CLI, Gemini CLI, OpenCode가 디스크에 저장한 세션 파일을 읽으며, 분석은 몇 초 안에 끝난다고 프로젝트 측은 설명한다. 구독 사용자의 달러 금액은 정가 기준 환산액이고, 백분율은 사용량 제한 여유분을 나타낸다.

저장소의 유지관리자가 공개한 최근 30일 기록은 101개 세션과 276개 하위 에이전트, 22,100개의 단발 실행을 분석했다. 여기에는 Claude Code 81개, Codex CLI 20개 세션과 모델 호출 58,208회가 포함된다. 이 기록에서 캐시 적중률은 95.4%였지만, 입력 지출 2,602달러 중 537.72달러가 캐시 누락과 콜드 스타트로 새었다. 이는 입력 지출의 20.7%, 전체 청구액 3,054달러의 17.6%다. 캐싱으로 절약한 금액은 21,281달러였고, 출력 지출은 452.39달러였다. 전체 청구액에서 캐시 쓰기는 43.8%, 캐시 읽기는 38.8%, 출력은 14.8%를 차지했다. 읽히지 않은 토큰에 지불한 쓰기 프리미엄은 215.71달러였으며, 대부분 단발성 claude -p 실행에서 발생했다.

유지관리자의 사례에서 누수 원인은 캐시 TTL보다 긴 유휴 시간이 164회, 미스 4,130만 토큰, 371.92달러로 전체 누수의 69.2%를 차지했다. 새 세션 콜드 스타트는 1,378회, 3,630만 토큰, 81.67달러(15.2%)였고, 하위 에이전트 콜드 스타트는 145회, 410만 토큰, 29.44달러(5.5%)였다. 이 수치는 유지관리자의 기록이며 각 사용자의 결과는 다를 수 있다. 이슈에 자신의 결과를 공유할 수 있다.

두 분짜리 시연 영상은 적중률이 비용을 제대로 보여주지 못하는 이유와 누수, 수정 전후, 벤치마크를 소개한다.

설정을 점검하고 바꾸는 방법

kvleak만 실행하면 누수 보고서를 확인할 수 있다. --since 7d로 최근 7일을 지정하고, --html report.html로 공유 가능한 보고서를 만들 수 있다. kvleak session <id>는 특정 세션의 호출을 하나씩 보여준다. 점검만으로는 설정이 바뀌지 않는다.

설정을 적용하려면 다음 명령을 사용할 수 있다. tune --apply는 압축 시점, 캐시 TTL, 유휴 세션 압축, Bash 출력 한도를 settings.json에 기록한다. 백업을 만들며 --reset으로 되돌릴 수 있다. hooks --install은 긴 셸 출력을 컨텍스트 밖에 두고 압축 과정에서 빠진 내용을 보관한다. --uninstall로 제거할 수 있다. refine --apply는 비용 추정치를 함께 적은 컨텍스트 관리 규칙을 ~/.claude/CLAUDE.md에 추가하며 --remove로 지운다. statusline --install은 상태 표시줄에 캐시 카운트다운을 넣고, --uninstall로 제거한다. 네 변경 사항은 각각 되돌릴 수 있으며, 적용 이후 시작한 Claude Code 세션부터 효력이 생긴다.

pip install kvleak
kvleak tune --apply # settings.json: compaction window, cache TTLs, idle compaction, Bash cap (--reset)
kvleak hooks --install # long shell output stays out of the context; compaction keeps an archive (--uninstall)
kvleak refine --apply # context-hygiene rules, with their dollar figures, in ~/.claude/CLAUDE.md (--remove)
kvleak statusline --install # cache countdown in the status bar, ticking while you read (--uninstall)

설치 후 Claude Code에서 /hooks를 실행하면 kvleak 항목 네 개가 표시된다. 첫 응답 뒤 상태 표시줄에는 ● cache 59:47 · 86k ctx · rebuild $1.73 같은 정보가 나타난다. 긴 seq 1 20000 출력은 2만 줄 대신 앞부분과 뒷부분, 파일 경로로 돌아온다. 일주일 뒤 kvleak probe를 실행하면 실제 변화량을 확인할 수 있다.

적중률만으로 비용을 알기 어려운 이유

캐시 적중은 입력 가격의 0.1배 비용이 들고, Fable 5.1에서는 0.025배다. 캐시를 다시 만드는 비용은 1.25~2배다. 컨텍스트가 20만 토큰인 미스 한 번은 적중 80회에 해당할 수 있다. 따라서 호출 중 2%만 미스여도 캐시되지 않은 입력 비용의 절반을 차지할 수 있지만, 적중률에는 거의 드러나지 않는다. kvleak은 미스 비용 전체가 아니라, 캐시에 이미 있던 컨텍스트를 다시 쓰면서 발생한 비용, 즉 쓰기 가격과 읽기 가격의 차이만 절감 가능한 비용으로 계산한다.

컨텍스트를 줄이는 도구가 청구액을 줄이지 않을 수도 있다. 도구 출력 압축기는 컨텍스트에 실리는 내용을 줄이지만, 그 내용은 청구서에서 가장 저렴한 캐시 읽기 가격으로 계산된다. arXiv 논문은 청구된 Claude Code 실행 2,848건에서 도구 출력이 38% 줄었는데도 비용이 6.8% 증가했다고 보고했다(arXiv 2607.12161). kvleak whatif는 사용자 자신의 청구 기록을 바탕으로 각 도구가 약속하는 절감 효과를 상한선으로 다시 계산한다.

유지관리자의 30일 기록에서 총 청구액 3,053달러는 캐시되지 않은 입력 80.38달러, 캐시 쓰기 1,337달러, 캐시 읽기 1,183달러, 출력 452.12달러로 나뉜다. 이 기록에 각 방식을 적용했을 때의 추정 절감액은 kvleak tune --apply가 786.56달러(청구액의 25.8%), 셸 출력 60% 감소가 222달러(7.3%), 모든 도구 결과 40% 감소가 183.98달러(6.0%), 추론 강도를 높음에서 중간으로 바꾸는 방식이 59.22달러(1.9%), 시작 컨텍스트를 50% 줄이는 방식이 43.19달러(1.4%), 응답 길이를 절반으로 줄이는 방식이 32.74달러(1.1%)였다. 비교에 사용된 출처는 각각 rtk의 하한 약속(“60–90%”), AgentDiet(arXiv 2509.23586), claude-token-optimizer, caveman이다. 이 추정은 유지관리자의 기록에 대한 결과다.

압축 설정은 컨텍스트에 실리는 양 자체를 바꾼다. 유지관리자의 기록에서는 청구액의 44%가 캐시 쓰기였기 때문에, 설정 조정의 절감 추정치는 가장 효과적인 압축기보다 세 배 컸다.

조정값과 실제 효과 확인

kvleak tune은 최근 30일 기록을 각 설정값에 대입해 재생하고, --apply를 지정하면 결과가 가장 좋은 값을 settings.json에 기록한다. 유지관리자 기록에서 자동 압축 창은 자동 설정(약 967k)에서 200k로 바꿀 때 30일 기준 720.52달러를 절감하는 것으로 계산됐다. 압축 횟수는 32회에서 98회로 늘고 입력 지출은 57.7% 감소하는 결과였다.

claude -p 실행의 CLAUDE_CODE_PROMPT_CACHE_TTL은 1시간에서 5분으로 바꿀 때 169.11달러를 절감하는 것으로 추정됐다. 해당 실행의 캐시 쓰기 중 42%가 다시 읽히지 않았기 때문이다. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS는 200k에서 100k로 바꿀 때 19.72달러를 절감하는 결과였으며, 54분 이상 유휴 상태인 구간이 153회 있었다. bashOutputMaxChars는 30,000에서 8,000으로 낮출 때 32.54달러를 절감하는 것으로 계산됐다. Bash 결과가 컨텍스트에 들어간 내용의 29%였기 때문이다. 네 설정을 모두 적용했을 때의 추정치는 30일에 909달러, 입력 지출 45% 감소다.

$ kvleak tune   setting                                         now           best   saving / 30d  why   autoCompactWindow                               auto (~967k)  200k        $720.52  98 compactions instead of 32 · −57.7% of input spend   `claude -p` runs: CLAUDE_CODE_PROMPT_CACHE_TTL  1h            5m          $169.11  42% of their cache writes were never read back   CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS             200k          100k         $19.72  153 idle gaps ≥54 min   bashOutputMaxChars                              30,000        8,000        $32.54  Bash results are 29% of what entered the context   Total if applied: $909 per 30d (−45% of input spend)   Write these to ~/.claude/settings.json: kvleak tune --apply

일주일 뒤 kvleak probe를 실행하면 설정 적용일을 기준으로 대화형 세션을 전후로 나눠 실제 변화를 비교한다. 호출당 입력 지출, 누수 비중, 호출당 컨텍스트 크기, 압축 횟수, 셸 출력과 그 차이를 30일 기준으로 환산한 금액을 보여준다. 재생한 기록이 아니라 실제 청구된 내용을 측정한다.

kvleak statusline --install은 Claude Code 상태 표시줄에 TTL 카운트다운을 넣는다. 컨텍스트를 계속 유지하는 비용이 이를 줄이는 비용보다 커지는 시점도 알려준다. 표시 예시는 다음과 같다.

◕ cache 3:41 · 182k ctx · rebuild $0.89 ● cache 59:47 · 249k ctx · rebuild $1.99 · ⚠ /compact saves ~$9.42 ◔ cache 1:19 · 250k ctx · rebuild $2.00 · ⚑ ≤2 pings pay

함께 제공되는 기능과 지원 범위

각 기능은 제안을 내놓기 전에 사용자의 기록에서 효과를 측정한다. 아래 수치는 유지관리자의 30일 기록이며, 계산 방법과 재현 정보는 docs/benchmarks.md에 공개돼 있다.

• kvleak probe는 tune --apply, hooks --install, refine --apply를 실행한 날을 기준으로 적용 전후의 호출당 입력 지출, 누수 비중, 컨텍스트 크기, 압축 횟수, 셸 출력을 비교하고 30일 환산값을 제시한다. 기록을 재생하지 않고 사용자의 실제 전후 기록을 비교한다.
• kvleak advise는 지금 /compact를 실행할지 새 세션으로 넘길지, 몇 번 호출해야 비용을 회수하는지 추정한다. 백테스트에서 입력 지출 58% 감소를 기록했다.
• kvleak diet는 컨텍스트를 채운 항목을 분석한다. 유지관리자의 기록에서는 셸 출력 29%, 셸에 보낸 스크립트 21%, 추론 14%, 파일 읽기 4%였다. 비용이 큰 개별 항목도 표시한다. 긴 도구 반복 114회는 다시 읽는 데 351달러가 들었고, 하위 에이전트에서는 319달러가 절감 대상이었다.
• kvleak hooks --install은 긴 셸 출력을 앞부분·뒷부분·오류 줄과 경로만 컨텍스트에 남기고, 나머지는 압축 과정에서 빠지지 않도록 보관한다. kvleak recall로 보관 내용을 찾을 수 있다. 긴 출력 작업 72회 벤치마크에서 정확도는 1.00이었고, 장시간 출력 작업의 비용은 16% 감소했다.
• kvleak refine --apply는 근거에 따라 CLAUDE.md에 컨텍스트 관리 규칙을 추가하고 각 규칙에 달러 기준 추정치를 적는다. 나중에 --probe로 어떤 규칙이 행동을 바꿨는지 확인할 수 있다. 규칙 다섯 개는 30일 기준 약 640달러를 다룬다.
• kvleak keepalive는 사용자의 휴식 시간에 정당화되는 캐시 유지 핑 횟수를 전체와 시간대별로 추정해 cache-refresher에 전달한다. 유지관리자의 기록에서는 핑 다섯 번의 가치가 337달러였고, 점심시간 휴식은 25%, 오전 6~8시 휴식은 86%를 돌려줬다.
• kvleak pointer, --fail-over, --path는 여러 에이전트 간 인계 포인터, 누수 비중을 검사하는 CI 게이트, Anthropic·OpenAI·Gemini 사용량 카운터가 포함된 JSONL 파일 처리를 지원한다. 에이전트 무리 운영 방법은 플레이북에 있다.

audit, advise, keepalive, whatif는 Claude Code, Codex CLI(~/.codex/sessions), Gemini CLI(~/.gemini/tmp/*/chats), OpenCode(opencode.db) 기록을 자동으로 읽는다. diet, tune, hooks, refine처럼 컨텍스트 수준을 다루는 명령은 도구 결과 자체가 필요하므로 Claude Code만 읽는다. 전체 예시는 docs/guide.md, 계산 방법은 docs/how-it-works.md에서 확인할 수 있다.

도구는 데이터를 외부로 보내지 않으며 로컬 파일만 읽는다. 구독 사용자는 미스가 달러 대신 사용량 제한 여유분을 소모한다고 보면 된다. 컨텍스트를 줄이는 것이 모델에 미치는 영향에 관해 프로젝트가 공개한 A/B 벤치마크는 bench/의 Opus 5.5 실행 72회다. 모든 실험군이 모든 작업에서 1.0점을 받았다. tune이 기록하는 설정은 컨텍스트가 200k를 넘을 때만 압축하며, --min-window로 이 기준을 높일 수 있다.

카운트다운 아이디어는 olddonkey/cache-refresher에서 가져왔다. 훅, recall, refine은 Prime Agent와 Harness²를 참고했다. MIT 라이선스로 배포된다.