Claude Code Usage Monitor: 실시간 토큰 사용량 모니터링 완전 가이드

Claude Code를 사용하다 보면 갑작스럽게 "세션이 종료되었습니다"라는 메시지와 함께 작업이 중단되는 경험을 해보셨을 것입니다. 특히 중요한 코딩 작업 중이라면 더욱 당황스럽죠. 이런 문제를 해결해주는 강력한 도구가 바로 Claude Code Usage Monitor입니다.

📋 Claude Code Usage Monitor란?

Claude Code Usage Monitor는 Claude AI 토큰 사용량을 실시간으로 모니터링하는 아름다운 터미널 도구입니다. 토큰 소비량, 소모율을 추적하고 토큰이 언제 소진될지 예측해줍니다.

✨ 주요 기능

🔄 실시간 모니터링

• 3초마다 업데이트되는 부드러운 새로고침
• 화면 깜빡임 없는 매끄러운 업데이트

📊 시각적 진행률 표시바

• 아름다운 컬러 코딩된 토큰 및 시간 진행률 바
• 직관적인 사용량 시각화

🔮 스마트 예측 기능

• 현재 소모율을 기반으로 토큰 소진 시점 계산
• 세션 리셋 전 토큰 고갈 경고

🤖 자동 감지

• Pro 한계 초과 시 자동으로 커스텀 최대값으로 전환
• 다양한 플랜 지원 (Pro, Max5, Max20, 자동 감지)

🚀 설치 방법

사전 요구사항

설치하기 전에 다음 항목들이 설치되어 있는지 확인하세요:

# Python 3.6+ 확인
python --version

# Node.js 확인 (ccusage 설치용)
node --version
npm --version

1단계: 의존성 설치

# Python pytz 패키지 설치
pip install pytz

# ccusage CLI 도구 전역 설치
npm install -g ccusage

2단계: 저장소 클론 및 설정

# 저장소 클론
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git

# 디렉토리 이동
cd Claude-Code-Usage-Monitor

# 실행 권한 부여 (Linux/Mac)
chmod +x ccusage_monitor.py

3단계: 실행

# 기본 실행
./ccusage_monitor.py

# 또는 Python으로 직접 실행
python ccusage_monitor.py

📖 사용법

기본 사용법

기본 실행 (Pro 플랜, 7,000 토큰)

 

./ccusage_monitor.py

플랜별 사용법

Claude Code Usage Monitor는 다양한 구독 플랜을 지원합니다:

플랜 토큰 한계 적합한 용도

Pro	~7,000	가벼운 사용, 테스트 (기본값)
Max5	~35,000	일반적인 개발 작업
Max20	~140,000	대규모 프로젝트, 집중 사용
Custom Max	자동 감지	이전 세션에서 최고값 자동 사용

# Pro 플랜 (~7,000 토큰) - 기본값
./ccusage_monitor.py --plan pro

# Max5 플랜 (~35,000 토큰)
./ccusage_monitor.py --plan max5

# Max20 플랜 (~140,000 토큰)
./ccusage_monitor.py --plan max20

# 자동 감지 (이전 세션에서 최고값 사용)
./ccusage_monitor.py --plan custom_max

고급 설정

커스텀 리셋 시간 설정

# 오전 3시에 리셋
./ccusage_monitor.py --reset-hour 3

# 오후 10시에 리셋
./ccusage_monitor.py --reset-hour 22

시간대 설정

# 한국 시간대 사용
./ccusage_monitor.py --timezone Asia/Seoul

# 미국 동부 시간 사용
./ccusage_monitor.py --timezone US/Eastern

# 일본 시간 사용
./ccusage_monitor.py --timezone Asia/Tokyo

# UTC 사용
./ccusage_monitor.py --timezone UTC

종합 설정 예시

# Max20 플랜, 한국 시간대, 오전 9시 리셋
./ccusage_monitor.py --plan max20 --timezone Asia/Seoul --reset-hour 9

📊 Claude 세션 시스템 이해하기

Claude Code는 5시간 롤링 세션 윈도우 시스템을 사용합니다:

• 세션 시작: Claude에게 첫 번째 메시지를 보낸 시점
• 세션 지속: 첫 메시지로부터 정확히 5시간
• 토큰 한계: 각 5시간 세션 윈도우 내에서 적용
• 다중 세션: 여러 세션이 동시에 활성화될 수 있음

기본 리셋 시간 (Europe/Warsaw 기준)

• 04:00, 09:00, 14:00, 18:00, 23:00

⚠️ 중요: 이것은 참고 시간입니다. 실제 토큰 새로고침은 각 세션의 첫 번째 메시지로부터 5시간 후에 발생합니다.

🎯 활용 시나리오

1. 일일 개발 작업자

# 매일 오전 9시 작업 시작
./ccusage_monitor.py --reset-hour 9 --timezone Asia/Seoul

2. 심야 작업자

# 자주 자정을 넘겨 작업하는 경우
./ccusage_monitor.py --reset-hour 0

3. 유연한 사용자

# 모니터가 자동으로 한계를 파악하게 함
./ccusage_monitor.py --plan custom_max

4. 글로벌 팀워크

# 뉴욕 시간대 사용
./ccusage_monitor.py --timezone America/New_York

# 싱가포르 시간대 사용
./ccusage_monitor.py --timezone Asia/Singapore

💡 모니터 화면 읽는 법

실행하면 다음과 같은 정보들을 실시간으로 확인할 수 있습니다:

📊 진행률 바

• 초록색: 안전 범위 (0-70%)
• 노란색: 주의 범위 (70-90%)
• 빨간색: 위험 범위 (90-100%)

📈 주요 지표

• Cost Usage: 비용 사용률 및 달러 금액
• Token Usage: 토큰 사용률 및 개수
• Messages Usage: 메시지 사용률
• Time to Reset: 세션 리셋까지 남은 시간
• Model Distribution: 사용 중인 모델 (Opus/Sonnet) 분포
• Burn Rate: 분당 토큰 소모율
• Predictions: 토큰 고갈 예상 시간

⚡ 베스트 프랙티스

1. 조기 모니터링 시작

새 세션을 시작할 때 모니터를 함께 실행하세요.

2. 소모율 주시

Burn Rate 지표를 통해 사용량을 관리하세요.

3. 미리 계획하기

토큰이 리셋 전에 고갈될 것으로 예상되면 사용량을 조절하세요.

4. 커스텀 스케줄 활용

본인의 작업 일정에 맞게 --reset-hour를 설정하세요.

5. 자동 감지 활용

--plan custom_max로 모니터가 자동으로 한계를 파악하게 하세요.

🐛 문제 해결

ccusage 관련 문제

# ccusage 설치 확인
npm install -g ccusage

# ccusage 작동 확인
ccusage blocks --json

세션 인식 문제

• Claude Code에서 활성 세션이 있는지 확인
• 새로운 Claude Code 세션 시작 후 재시도

화면 깜빡임 문제

# 커서 복원
printf '\033[?25h'

화면 표시 문제

• 터미널 창이 최소 80자 이상인지 확인
• 터미널 크기 조정 후 모니터 재실행

🔧 고급 기능

스마트 자동 감지

Pro 플랜 기본 설정에서 사용하다가 7,000 토큰을 초과하면:

• 🔍 자동으로 초과 감지
• 🔄 custom_max 모드로 자동 전환
• 📢 전환 알림 표시
• ▶️ 새로운 한계로 모니터링 계속

다중 세션 분석

모니터는 지난 1시간의 모든 세션을 분석하여:

• 겹치는 세션 간 토큰 소비 분석
• 정확한 최근 사용 패턴 제공
• 실시간 예측 업데이트

🎯 실제 사용 예시

아침 루틴

# 오전 9시 작업 시작, 한국 시간대, Max5 플랜
./ccusage_monitor.py --plan max5 --timezone Asia/Seoul --reset-hour 9

집중 개발 세션

# 자동 감지로 최대한 활용
./ccusage_monitor.py --plan custom_max

팀 프로젝트

# UTC 시간대로 글로벌 팀과 협업
./ccusage_monitor.py --plan max20 --timezone UTC

🚪 모니터 종료

모니터를 종료하려면 Ctrl+C를 누르면 됩니다. 그러면 깔끔하게 종료됩니다.

🌟 마무리

Claude Code Usage Monitor는 Claude Code를 더 효율적으로 사용할 수 있게 도와주는 필수 도구입니다. 실시간 모니터링을 통해 갑작스러운 세션 종료를 방지하고, 토큰 사용량을 체계적으로 관리할 수 있습니다.

더 나은 AI 개발 경험을 위해 오늘부터 Claude Code Usage Monitor를 사용해보세요!

---

🔗 유용한 링크

• GitHub 저장소
• ccusage 도구
• Claude Code 공식 문서

💬 문의 및 기여 버그 신고, 기능 제안, 풀 리퀘스트 등은 GitHub 저장소에서 환영합니다!

💡 팁: 이 글이 도움이 되었다면 GitHub 저장소에 ⭐를 눌러주세요!