Cache Clock: Claude Code 프롬프트 캐시가 언제 만료되는지 확인하세요

Cache Clock은 Claude Code 프롬프트 캐시의 상태를 보여 주는 커뮤니티 모드입니다. 만든 사람은 Hamza Zafar(hamzafer)이며 claude-code-mods 모음의 일부입니다. 상태 표시줄 아래에 한 줄을 추가합니다. 캐시가 따뜻한 동안에는 초록색으로 cache ● 1h ██████████ 59m left · hit 48% · misses 0처럼 표시됩니다. 캐시 수명(5m 또는 1h), 남은 정도를 나타내는 10칸 막대, 남은 시간, 적중률, 미스 횟수입니다.

남은 시간이 수명의 20% 아래로 내려가면 줄이 노란색이 됩니다. 캐시가 만료되면 빨간색으로 바뀌어 cache ○ cold · next message re-caches 82k tokens처럼 표시되고, Claude Code가 직전 미스의 원인을 알려 주면 함께 붙습니다. 메시지를 보내기 전에, 캐시에서 응답이 나올지 아니면 앞부분 전체를 다시 만드는 비용을 치를지 알 수 있습니다.

수치는 모드가 계산하지 않습니다. Claude Code는 2.1.251부터 상태 표시줄 명령에 prompt_cache 객체를 보내 주고, 모드는 그것을 서식만 맞춥니다. 플러그인은 상태 표시줄을 등록할 수 없으므로 모드가 /cache-clock 명령을 추가합니다. setup은 statusLine이 모드의 스크립트를 가리키게 하고, remove는 원래대로 돌려 놓습니다. 이미 상태 표시줄이 있다면 그대로 유지되고 캐시 줄이 그 아래에 붙습니다.

녹화에서는 작은 데모 프로젝트에서 모드를 불러온 Claude Code를 시작합니다. 상태 표시줄은 미리 모드의 스크립트를 가리키도록 해 두었고, 녹화하는 사람 자신의 ~/.claude를 건드리지 않도록 /cache-clock setup 단계는 일부러 생략했습니다. Claude에게 README.md를 읽고 프로젝트를 한 문장으로 설명해 달라고 요청합니다. 턴이 실행되는 동안 프롬프트 아래에는 막대가 가득 찬 초록색 cache ● 1h가 59m left, hit 0% · misses 0과 함께 보입니다. 턴이 끝나면 같은 줄이 hit 48% · misses 0으로 바뀝니다.

설치 블록에 있는 방법 중 아무거나 쓰세요. 모두 만든 사람 자신의 마켓플레이스에서 바로 설치됩니다. 그런 다음 세션에서 /cache-clock setup을 실행합니다. 줄은 Claude의 다음 답변 뒤에 나타나며, /cache-clock만 실행하면 켜져 있는지 알려 줍니다.

hooks/register.ts가 명령을 등록하고 설정을 처리합니다. 함께 배포되는 statusline/cache-clock.mjs는 Claude Code가 상태 표시줄을 갱신할 때마다 실행하는 스크립트입니다. stdin에서 JSON을 읽고, 저장된 원래 명령이 있으면 먼저 실행한 다음 캐시 줄을 출력합니다. 순수 포매터는 statusline/render.mjs에 있습니다.

export function render(input, nowSeconds) {
  const cache = input?.prompt_cache
  if (!cache || typeof cache !== 'object') return ''
  if (cache.caching_observed === false) return ''

  const left = typeof cache.expires_at === 'number' ? cache.expires_at - nowSeconds : null
  const isWarm = cache.warm !== false && left !== null && left > 0
  return isWarm ? warmLine(cache, left) : coldLine(cache)
}

expires_at이 지나면, 입력이 만들어질 때 warm이었더라도 곧바로 콜드로 취급합니다. setup은 스크립트 두 개를 플러그인 폴더가 아니라 <config dir>/cache-clock/에 씁니다. 플러그인 폴더는 버전마다 바뀌기 때문입니다. 다음 세션이 시작될 때 상태 표시줄이 이 모드의 것이면 refreshScripts가 복사본을 새 버전으로 덮어씁니다. setup은 refreshInterval을 30초로 설정하며(이미 더 짧으면 그대로 둡니다), 그래서 답변 사이에도 카운트다운이 움직입니다.

옵션은 없습니다. /cache-clock setup과 /cache-clock remove가 유일한 스위치입니다. 모양을 바꾸려면 render.mjs를 편집하세요. BAR_CELLS는 막대 너비, WARN_SHARE는 노란색으로 바뀌는 기준(기본 20%)이고, 파일 맨 위에 색상 이스케이프 코드가 있습니다. <config dir>/cache-clock/의 복사본을 편집하세요. 설정된 동안에는 다음 세션 시작 때 모드가 배포 버전으로 덮어씁니다.

실행하기 전에 플러그인이 실행하는 모든 파일을 읽었습니다. .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.ts, 상태 표시줄 스크립트 두 개, 테스트입니다. package.json, 설치 스크립트, 번들되거나 minify된 코드, 바이너리는 없습니다. 저장소에는 MIT LICENSE가 있습니다.

• 요청할 때만 설정을 바꿉니다. 설치나 세션 시작 때는 자체 스크립트 갱신 외에는 아무것도 쓰지 않습니다. /cache-clock setup은 Claude 설정 폴더(또는 CLAUDE_CONFIG_DIR)의 settings.json에 씁니다. 상태 표시줄이 프로젝트 설정에서 온 경우에는 <project>/.claude/settings.local.json에 씁니다. 또한 <config dir>/cache-clock/ 아래에 스크립트와 setup-<hash>.json 백업을 씁니다. /cache-clock remove는 이전 statusLine을 복원하며, 설정 이후 직접 바꾼 경우는 건드리지 않습니다. 관리형(policy) 설정이나 --settings의 상태 표시줄은 바꾸지 않고, 잘못된 설정 JSON도 그대로 둡니다.
• 갱신할 때마다 명령을 실행합니다. setup 이후 Claude Code는 node "<config dir>/cache-clock/cache-clock.mjs"를 실행합니다. 이 스크립트는 이전 상태 표시줄 명령을 같은 입력으로 셸을 통해(spawnSync(..., { shell: true }), 5초 제한) 실행합니다. setup 자체는 Node가 있는지 확인하려고 node --version을 실행합니다.
• 네트워크, 텔레메트리, 모델 호출, 데몬이 없습니다. HOME과 CLAUDE_CONFIG_DIR은 설정 폴더를 찾는 데만 읽습니다. 토큰이나 자격 증명은 읽지 않습니다.
• 프롬프트 인젝션도, 차단하는 훅도 없습니다. 등록하는 것은 session.start와 자체 명령뿐이며 프롬프트나 도구 결과에는 아무것도 추가하지 않습니다.
• 요구 사항: PATH의 Node, Claude Code 2.1.251 이상.

claude plugin validate는 오류나 경고를 보고하지 않았고, 만든 사람의 테스트 25개는 Claude Code 2.1.296에서 모두 통과했습니다.

macOS의 Claude Code 2.1.296에서 확인했습니다(validate, 테스트, 데모). 줄이 보이지 않는다면:

• /cache-clock을 실행하세요. “cache-clock is on”이라고 나와야 합니다.
• 먼저 메시지를 한 번 보내세요. prompt_cache가 도착하기 전, 그리고 공급자가 캐시가 없다고 알리는 동안에는 줄이 비어 있습니다.
• claude --version이 2.1.251 이상이고, 같은 터미널에서 node --version이 동작하는지 확인하세요.
• 상태 표시줄이 관리형 설정이나 --settings로 지정되어 있지 않은지 확인하세요. setup은 그런 설정은 바꾸지 않습니다.
• 이미 실행 중인 세션에서 setup했다면 다음 답변이나 30초 갱신을 기다리세요.