내 Claude Code Context Window가 얼마나 가득 찼는지 전혀 몰랐어요. 그래서 도구를 만들었습니다.

Source: Dev.to

개요

Claude가 이상하게 잘린 답변을 내놓을 때, 혹은 긴 세션에서 이전 컨텍스트를 “잊어버린” 것처럼 보일 때가 있나요?
그것은 바로 컨텍스트 창이 가득 차는 순간입니다.

Claude Sonnet은 200 k‑토큰 컨텍스트 창을 가지고 있습니다. 창이 가득 차면 오래된 메시지가 삭제됩니다. 여러분이 신중하게 설정한 컨텍스트—로드한 파일들, 설정한 제약 조건, 설명한 코드베이스—가 조용히 사라집니다.

저는 Claude Code를 60일 넘게 자동 루프에서 실행해 왔습니다. 지난 주에 현재 컨텍스트가 얼마나 차 있는지 전혀 알지 못한다는 것을 깨닫고 cc-context-check 를 만들었습니다.

기능

npx cc-context-check

샘플 출력

cc-context-check — Context window usage across sessions

Context limit: 200.0k tokens (Claude Sonnet/Opus)

🟢 ~/projects/my-app    [a3f9c12] just now · 12.4 MB
   ████████████░░░░░░░░░░░░░░░░░░ 40.1% used
   80.2k input · 1.2k output · 119.8k remaining

🟡 ~/                   [b7d44e1] 2h ago · 5.9 MB
   █████████████████████░░░░░░░░░ 71.5% used
   143.0k input · 89 output · 57.0k remaining
   △ Warning: Context is getting full — consider /compact

색상 코드

• 🟢 70 % 미만 → 계속 사용
• 🟡 70‑85 % → 압축 고려
• 🔴 85 % 이상 → 바로 압축

작동 원리

Claude Code는 세션 전사를 ~/.claude/projects/ 폴더에 .jsonl 파일로 저장합니다. 각 라인은 하나의 메시지이며, 각 어시스턴트 메시지는 usage 객체를 포함합니다. 예시:

{
  "usage": {
    "input_tokens": 1,
    "cache_read_input_tokens": 79927,
    "cache_creation_input_tokens": 917,
    "output_tokens": 158
  }
}

실제 컨텍스트 사용량은 다음과 같습니다.

input_tokens + cache_read_input_tokens + cache_creation_input_tokens

input_tokens: 1 항목은 오해의 소지가 있습니다—실제 컨텍스트는 캐시 토큰에 저장됩니다.

cc-context-check는 각 세션 파일의 마지막 64 KB를 읽어 가장 최신의 사용량 데이터를 찾아 실제 채워진 비율을 계산합니다.

/compact를 사용해야 할 때

이 도구는 프로젝트별 활성 Claude Code 세션을 모두 보여주어 한눈에 확인할 수 있게 해줍니다.

• ≈ 40 % – 문제 없음. 계속 진행.
• ≈ 71 % – 거의 가득 찼음. 새로운 작업을 시작한다면 /compact를 사용하세요.
• ≈ 87 % – 곧 압축 필요. 컨텍스트가 사라지고 있습니다.

옵션

npx cc-context-check --all    # 상위 5개 대신 상위 20개 세션 표시
npx cc-context-check --json   # 스크립팅을 위한 JSON 출력

cc‑toolkit의 일부

이 도구는 cc-toolkit 에 포함된 #43번째 도구입니다 — Claude Code 사용자를 위한 43개의 무료 도구. 의존성이 없으며 브라우저 또는 npx로 실행됩니다.

Source: github.com/yurukusa/cc-context-check

추가 도구: Dev Toolkit — 개발자를 위한 56개의 무료 브라우저 기반 도구(JSON, 정규식, 색상, CSS, SQL 등). 모두 단일 HTML 파일이며 회원가입이 필요 없습니다.