Claude Code 사용량 모니터 – 사용량 제한 회피를 위한 실시간 트래커

(github.com/Maciek-roboblog)

5P by GN⁺ 11시간전 | ★ favorite | 댓글 2개

Claude AI 토큰 사용량, 소진 속도, 소모 예측등 다양한 정보를 실시간으로 터미널에 보여주는 모니터링 툴
3초마다 갱신되는 컬러풀한 프로그레스 바, 스마트한 토큰 소진 예측
기본 플랜 한도 초과 시 세션 기록을 분석해 실제 한도로 즉시 전환
자동으로 Pro/Max5/Max20/custom_max 등 사용량 플랜을 감지 및 지원
세션별 토큰 한도 임박·초과, 세션 리셋 전 소진 위험시 실시간 알림
실제 Claude 사용 흐름에 최적화된 인터페이스 구현
npm, pip 설치, 가상환경(venv/virtualenv) 사용 권장,Mac/Linux/Windows 전부 지원

Claude 세션 이해하기

5시간 롤링 윈도우 방식
- 최초 메시지를 보낸 시점부터 세션 5시간 유지
- 세션별 한도 적용, 복수 동시 활성화 가능
- 실제 리셋은 내 메시지 기준 매 5시간마다 발생
세션/토큰 리셋 시간 기준을 내 스케줄에 맞게 지정 가능

활용 시나리오

출근/오전 개발자: 일과 시작 시간(예: 9시)에 맞춰 토큰 리셋 스케줄 조정해 효율적 플래닝 가능
야간 작업자: 자정 등 본인 스케줄에 맞춘 토큰 리셋 이용
가변 한도 사용자: custom_max 모드로 실제 환경에 맞는 한도 자동 감지
글로벌/원격 개발자: 여러 타임존 이동, 팀 단위 리셋 시간 지정 → 협업 최적화
빠른 상태 확인: 단순 실행(설정 무관)

환경 구축 베스트 프랙티스

세션 시작과 동시에 모니터링 시작
- Claude 작업을 시작할 때 즉시 모니터 실행 (./ccusage_monitor.py)
- 지원 플랜
  - pro: 약 7,000 토큰(테스트 및 경량 사용)
  - max5: 약 35,000 토큰(일상적 개발)
  - max20: 약 140,000 토큰(대형 프로젝트 및 중/고강도 사용)
  - custom_max: 자동 감지 모드(실제 사용 이력 기준 최대값 사용)
- 세션 전체 토큰 추적 정확도 향상
- 토큰 소모 속도 계산과 한도 임박 조기 경고 가능
Python 가상환경(venv) 사용
- 의존성 충돌 방지, 환경 분리, 프로젝트별 재현성 보장
- 설치 및 실행:
```
python3 -m venv venv  
source venv/bin/activate  
pip install pytz  
```
- 삭제 시 가상환경 폴더만 지우면 깨끗한 제거 가능
쉘 Alias 커스텀 등록
- 반복적인 명령을 한 줄로 단축 실행
```
alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./ccusage_monitor.py'  
```
- .bashrc 또는 .zshrc 등에 추가, 한 번 입력으로 곧바로 모니터 실행 가능

사용 방법 베스트 프랙티스

Burn Rate(소모 속도) 상시 모니터링
- 토큰 사용량이 갑자기 치솟는 경우 주의
- 남은 시간·토큰량에 따라 작업 강도 조절
- 세션 리셋(토큰 초기화) 전후로 대규모 리팩터링 등 큰 작업 일정 조정
전략적 세션 스케줄링
- 대규모 작업은 토큰 리셋 직후 시작, 한도 임박 시에는 가벼운 작업 수행
```
./ccusage_monitor.py --reset-hour 9  
```
- 세션별 5시간 규칙을 활용해 여러 세션 중첩 운영 가능
타임존 명확히 지정
- 실제 근무/협업 시간대 반영하여 정확한 토큰 리셋 예측 및 일정 관리
```
./ccusage_monitor.py --timezone Asia/Seoul  
```
- 여러 국가·팀과 협업 시 시간 오차 방지, 세션 만료 시점 혼동 최소화

최적화 팁

터미널 환경 세팅
- 최소 80자 너비 터미널 권장
- 컬러 지원으로 시각적 피드백 극대화
- 별도 전용 창에서 상시 모니터링 추천
워크플로우 통합
- tmux 등 터미널 멀티플렉서 활용해 개발과 동시에 모니터링 가능
```
tmux new-session -d -s claude-monitor './ccusage_monitor.py'  
tmux attach -t claude-monitor  
```
멀티 세션 전략
- 세션별로 5시간 고정, 중첩 세션 동시 관리 가능
- 긴 작업은 여러 세션에 분산, 각 세션 한도/만료 주의

실제 워크플로우 예시

대형 프로젝트 개발
```
./ccusage_monitor.py --plan max20 --reset-hour 8 --timezone America/New_York  
```
- 오전 8시 토큰 리셋 → 주요 기능 개발 시작
- 10시 Burn Rate 점검 후 작업 속도 조절
- 12시 오후 일정 점검 및 조율
- 14시 새 세션 오픈, 복잡한 이슈 처리
- 16시 가벼운 작업/저녁 세션 준비
러닝/실험 중심 사용
```
./ccusage_monitor.py --plan pro  
```
- 가벼운 학습, 실험적 코드 작성에 적합
스프린트 집중 개발
```
./ccusage_monitor.py --plan max20 --reset-hour 6  
```
- 집중적인 대량 토큰 소모가 예상되는 개발에 맞춤 설정

▲

GN⁺ 11시간전 [-]

Hacker News 의견

나는 Claude의 투명성 부족이 답답하고, 이 아이디어가 참 마음에 든다는 의견 공유 Claude Code의 핵심 기능은 데스크톱 앱에 비해 컨텍스트와 제한 관리를 더 잘할 수 있다는 것(예: compact 모드, 남은 용량 % 표시)인데, 아직 충분하지 않다는 느낌 추가 조언으로, 프로젝트 README에 이모지가 너무 많이 사용되는 건 개인적으로 굉장히 비전문적으로 느껴지며, 마치 AI가 적절히 관리되지 않은 채로 '분위기'만으로 코딩된 프로젝트 같다는 걱정이 든다는 생각 공유
- 내가 소프트웨어 쪽에 들어왔던 시절엔 코드베이스에 이모지 쓰다 걸리면 정신병원에 보낼 정도 분위기였음 지금은 시대가 확 바뀌어서, 이모지를 시각적으로 맥락 정리에 쓴다는 점에서 자주 사용함 이제 내 코드는 나를 행복하게 해줄 만큼 이모지가 많이 들어가 있음
- 요즘 스타트업이나 젊은 회사들에서 이런 이모지 스타일이 많이 보임 아마 Notion의 영향이 큰 듯 우리 회사에서는 리스트, 페이지, 캘린더 인바이트 하나 만들 때도 늘 이모지를 고른다는 특징 있음
- AI 코딩을 위해 만들어진 소프트웨어에 대해 이런 코멘트가 달리는 게 참 아이러니하다는 생각 공유
- 실제로 코드를 보면, 400줄짜리 파이썬 파일 하나가 그냥 ccusage를 감싸고 있을 뿐임 그래서 그렇게 느끼는 것도 가능하다고 생각
- AI가 만든 PR 설명이나 README는 프롬프트에 ‘간결하게, 화려한 수식이나 이모지 없이’라는 조건을 꼭 추가함 이렇게 하면 산만했던 이모지 파티가 적절한 문서로 변함 상황에 따라 달라질 수는 있음
나는 ccusage 제작자라는 소개와 함께, 사람들이 우리 오픈소스를 다양하게 써줘서 기쁘다는 소감 Happy vibe coding!이라는 긍정 메시지 남김
- 신기하게도 ccusage의 Show HN에는 댓글이 하나도 없는데, 이 쓰레드는 무척 활발하다는 점이 재미로움 관련 쓰레드 링크
참고로, 내 과거 세션 최대 토큰 제한은 약 337,492개였고, Max20 플랜과 Opus를 99% 정도 사용한다는 경험 공유 Claude Code를 5월 27일부터 써서 총 사용한 토큰이 1,374,439,311개, 금액으로는 약 3,397달러임
- 나는 Max20 플랜으로 약 2,100달러어치 정도 사용 API에서 엄청난 마진이 남는 건지, 아니면 손해를 보고 있는 건지 궁금 매일 쓰지만 과하게 쓴다고 생각하진 않음
- Opus에서 속도 제한에 자주 걸리지 않는지, Sonnet에 비해 느리다고 느끼지 않는지 궁금
나는 지금까지 쓴 토큰이 리미트에 얼마나 가까운지 직감적으로 파악할 수 있음 대화 자체가 최대치에 도달할 것 같은 순간도 감지하는데, 그때 마지막 남은 리소스로 요약본 생성 후 새로운 대화로 이어가면서 작업을 계속함 이런 AI 도구들이 이제 내 생체 시계 일부가 된 느낌 매주 수요일마다 ChatGPT의 주간 리미트가 리셋돼서, 수요일이 새로운 일요일처럼 느껴지는 경험 공유
토큰 사용량이 시간창이 지나도 100%에 도달하지 않으면 리셋되지 않는 걸 관찰함 예를 들어 90% 썼다가 다음 윈도우로 넘어가고, 남은 10%를 금방 소진하면 긴 시간 대기해야 하는 문제가 있음
나는 여러 Claude Code 세션을 동시에 사용할 수 있게 만드는 UI 툴(crystal)을 만들었음 여러 기능을 한 번에 작업하다보니 내 계정 한계에 자주 다다르게 됨 보통 리셋 시간 근처에서 한계에 도달하지만, 언제쯤 쉬어야 할지 미리 알 수 있으면 더 좋겠다는 느낌
- Claude Code를 엄청나게 많이 사용하지만, worktree랑 여러 세션 작업을 위한 툴링을 따로 짤 자신은 git 이해도가 부족해서 망설이게 됨 솔직히 이 도구를 쓰는 것도 조금 두려운데, 이상적으로는 각 worktree를 컨테이너에서 돌리고 싶지만 Crystal만큼 부드럽게 돌아가게끔 만들기는 어려울 것 같은 느낌
- 이 툴 좋아하지만, Crystal은 이미 예전에 써봤던 프로그래밍 언어 이름이라 혼동됨
- GitHub에 이슈를 남겨주면(여기), 내 usage monitor와 연동도 시도해볼 수 있음
- 멋지다는 감탄 나도 프로젝트별이 아니라 동시 5개 프로젝트에도 이런 툴이 있었으면 좋겠다고 Laude에게 시켰을 뻔했다는 경험 공유 많은 활용 기회에 공감
정말 흥미로운데, Pro 플랜의 토큰 제한이 정말 7,000개밖에 안 되는지 궁금 즉, 7,000단어도 안 되는 셈인데, 실제로는 훨씬 더 많이 쓸 수 있는 느낌임 이 정도면 대화가 조금만 길어져도 금방 한계가 올 것 같은데, 나는 아직 한 번도 부딪혀본 적 없음 혹시 Claude Code에만 적용되는 제한인지, 아직 Claude Code를 많이 써보지 않아 잘 모르겠다고 의견 남김
- 프로 플랜은 한 달에 $20. 최근에 claude code 접근이 가능해짐 그런데 몇 번 쿼리만으로도 일부 사용자들은 리미트에 걸린다는 얘기를 들었음 그래서 그 정도 수치가 맞는 것 같다는 생각 채팅 인터페이스의 제한과 Claude Code의 제한이 별개임
대단히 훌륭함에 감탄, 제작해준 것에 감사함 uv로 설치 가능 여부 궁금 uv 링크 공유와 함께, 설치 과정을 한 줄씩 정리해 셸 명령 예시 공유
- 만약 해당 레포가 project.toml 등 패키지 구조로 되어 있었다면 pipx(pipx)로 다음과 같이 더 빠르게 설치할 수 있었을 것이라는 설명

pipx install git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor ccusage_monitor uv에서도 이와 유사한 명령(uvx)이 있을 것 같은데, pipx와 같은 기능/목적인지는 잘 모르겠다는 의견

참고로 pip으로 설치 가능한 거의 모든 것은 uv로도 설치할 수 있으니, uv로도 더 쉽다는 사실 공유
혹시 이 도구가 ccusage로 쉘 호출해서 실행되는 것 말고 다른 유용한 점이 있는지 궁금 솔직히 이런 류의 프로젝트는 조금 실망스럽고, AI 툴로 한 번에 끝낸 느낌도 있음 Show HN에선 모든 실제 작업이 타툴에 의해 처리된다고 언급조차 없어 아쉬움
어제 Claude Code에서 특이한 경험이 있었음 오래된 PHP로 작성한 phtml 테이블 페이지를 새 div 레이아웃으로 변환하려다 실패하고 $4 정도를 소진한 경험 WSL 문제일 수도 있지만, 이런 일이 자주 일어나지 않길 바라는 마음
- Claude Code는 러닝커브가 꽤 있음 요구사항을 충분히 논의하고 모델에게 명확한 질문을 유도하는 식으로 긴 대화 세션을 진행해야 함 그래도 가끔은 이런 실패가 발생할 수 있으니, 매우 값비싼 도구라는 점을 꼭 기억해야 함 유튜버나 블로거들이 말하는 것처럼 마법은 아니라는 점 상기

답변달기

▲

fanotify 8시간전 [-]

같은 거네요: https://news.hada.io/topic?id=21560

답변달기