Token Weather: Claude Code 컨텍스트 창 예보

Token Weather는 Hamza Zafar(hamzafer)가 만든 커뮤니티 모드로, 그의 claude-code-mods 모음에 포함되어 있습니다. 프롬프트 위의 한 줄에 Claude Code 컨텍스트 창 예보를 보여 줍니다. 창이 얼마나 찼는지를 날씨 단어와 아이콘으로 나타내고, 사용률, 창 크기 대비 토큰 수, 최근 턴의 스파크라인, 그리고 프롬프트 캐시가 얼마나 더 따뜻하게 유지되는지 알려 주는 카운트다운이 이어집니다.

예보는 ☀ Clear(25% 미만)에서 ☁ Cloudy, ☂ Showers, ☇ Storm을 거쳐 90% 이상의 ↯ Compact soon까지 바뀝니다. 옆의 last turns는 최대 12개의 측정값을 ▁▂▃▄▅▆▇█로 그리며, 그중 가장 큰 값에 맞춰 크기가 조정됩니다. 이어서 직전 턴에서 늘거나 줄어든 양이 ▲ +39.4k last turn처럼 표시됩니다. 줄이 충분히 넓으면 ❄ cache 4:12가 캐시 만료 시점까지 카운트다운하고, 마지막 1분에는 노란색이 되며, 만료 후에는 ❄ cache cold로 바뀝니다.

Token Weather는 우리 사이트의 Context Bar, Context Meter, Cache Clock과 일부 겹칩니다. Context Bar는 창을 카테고리별로 나누고, Context Meter는 상태 표시줄에 사용률과 요금제 사용량을 보여 주며, Cache Clock은 상태 표시줄 아래에 캐시 세부 정보를 보여 줍니다. Token Weather는 한 줄짜리 판정과 추이를 보여 줍니다. 작성자의 마켓플레이스에 등록된 버전은 0.2.2입니다.

녹화에서는 작은 데모 프로젝트에서 이 모드를 불러온 Claude Code를 시작합니다. 프롬프트를 보내기 전에는 입력창 위의 줄이 ☀ Clear 0% of context 0 / 1M입니다. 그다음 Claude에게 README.md를 읽고 이 프로젝트가 무엇인지 한 문장으로 말해 달라고 요청합니다. 첫 요청이 실행되는 동안 ❄ cache 5:00 카운트다운이 나타납니다. 턴이 끝나면 줄은 ☀ Clear 4% of context 39.4k / 1M, 스파크라인, ▲ +39.4k last turn, ❄ cache 60:00을 보여 줍니다. 응답이 1시간짜리 캐시를 기록했기 때문입니다.

설치 블록에 있는 방법 중 아무것이나 사용하세요. 모두 작성자의 마켓플레이스에서 직접 설치합니다. 이 줄은 다음 세션을 시작할 때 나타납니다. 플러그인 옵션은 프롬프트 캐시 유효 시간 하나뿐입니다.

측정값은 호스트가 보관하는 $.state 아톰에 저장되므로 핫 리로드 후에도 남아 있습니다. 측정은 세션 시작 시와 메인 에이전트의 각 턴이 끝난 뒤에, $.session.usage의 컨텍스트 정보로 이루어집니다. 캐시 시계는 턴 안의 도구 루프 요청을 포함해, 메인 스레드의 모델 요청이 끝날 때마다 다시 시작됩니다. 다음은 hooks/register.tsx의 turn.step 핸들러입니다.

on('turn.step', async function* ($, e, next) {
  const result = yield* next(e)
  if (!e.agentId && result.stopReason !== null) {
    const now = await $.clock.now()
    await update($, lastRequestAt, () => now)
    restart($, now, now, await ttlMsFor($, override))
  }
  return result
})

auto 모드에서는 각 턴이 끝난 뒤 세션 기록(<config dir>/projects/<project>/<session id>.jsonl)의 마지막 1MB를 읽고, 가장 최근 메인 스레드 응답의 cache_creation에 1시간 또는 5분짜리 토큰이 있는지 확인합니다. 결과는 플러그인 저장소에 기억되어 다음 세션에서도 쓰입니다. 카운트다운 문구가 바뀔 때마다 타이머가 줄을 다시 그립니다. 남은 시간이 10분을 넘으면 30초마다, 그 아래에서는 15초마다, 마지막 2분에는 매초 갱신됩니다.

옵션은 플러그인 설정의 cacheTtl 하나이며 auto(기본값), 5m, 1h 중에서 고릅니다. 고정값은 자동 감지보다 우선합니다. 예보 구간, 12개 측정값 기록, 60초 경고는 register.tsx 맨 위의 상수입니다. 또한 선택 사항인 순서 파일 <config dir>/claude-code-mods/bands.json을 읽어, 같은 작성자의 여러 밴드 모드가 프롬프트 위에 그려질 때의 순서를 정합니다.

실행하기 전에 플러그인이 실행할 수 있는 모든 파일을 읽었습니다. .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/bands.ts, 타입 선언, 그리고 테스트 파일 세 개입니다. package.json, 설치 스크립트, 바이너리, 번들된 코드는 없으며, 그려지는 문구는 숫자로 만들어지고 모델의 프롬프트에는 아무것도 주입하지 않습니다. 저장소에는 MIT LICENSE가 있습니다.

동작의 전부는 다음과 같습니다.

• 네트워크: 없음.
• 프로세스: 하나, tail -c 1048576 <세션 기록 경로>이며 기록이 1MB보다 클 때만 사용합니다. 그렇지 않으면 파일을 직접 읽습니다.
• 읽는 파일: 내 세션 기록(캐시 유효 시간 감지용), Claude 설정 디렉터리의 선택적 bands.json, 그리고 $.settings.read로 읽는 Claude Code 설정(Cache Clock 상태 표시줄이 설정되었는지 확인용). 위치를 찾기 위해 환경 변수 HOME과 CLAUDE_CONFIG_DIR을 읽습니다.
• 쓰는 파일: 직접 쓰는 것은 없습니다. 감지한 캐시 유효 시간(5m 또는 1h)을 플러그인 자체 저장소인 $.store에 저장합니다.
• 백그라운드 작업: Claude Code 안의 다시 그리기 타이머뿐이며 세션이 끝나면 멈춥니다. 데몬은 없습니다.
• 차단: 없음. 도구 호출이나 프롬프트를 막거나 바꾸지 않습니다.

claude plugin validate는 플러그인 자체에 대해 오류도 경고도 보고하지 않았습니다(디렉터리 검사기는 아이콘이 없다고 알려 줍니다). 작성자의 테스트 24개는 Claude Code 2.1.307에서 모두 통과했습니다.

macOS의 Claude Code 2.1.307에서 확인했습니다(validate, 테스트, 녹화). 줄이 나타나지 않는다면 다음을 확인하세요.

• 설치 후 새 세션을 시작했는지 확인하세요. 모드는 세션 시작 시 로드됩니다.
• 입력창 위에 설문이 열려 있지 않은지 확인하세요. 설문이 열려 있으면 이 줄이 비켜 주고, 닫히면 돌아옵니다.
• 창 너비가 60열 이상인지 확인하세요. 더 좁으면 예보 단어, 사용률, 토큰 수만 표시됩니다.
• 카운트다운이 맞지 않으면 cacheTtl을 auto 대신 5m 또는 1h로 설정하세요. 프로젝트 경로가 매우 길거나 세션 중에 프로젝트를 옮기면 세션 기록을 찾지 못할 수 있으며, 이 경우 마지막으로 감지한 값이 유지됩니다.
• /clear 또는 세션 재개 후에는 다음 요청이 올 때까지 카운트다운이 숨겨집니다.