클로드 코드(Claude Code)를 사용하다 보면 가장 궁금한 것 중 하나가 바로 얼마나 사용했는지입니다. 특히 저처럼 바이브코딩을 하면서 커서 프로(Cursor Pro)에서 클로드 코드 20달러 플랜을 쓰다가 100달러 맥스 플랜으로 올린 경우라면 더욱 그렇죠1.
토큰 사용량을 정확하게 파악하고 관리하는 것은 비용 최적화뿐만 아니라 효율적인 개발을 위해서도 중요합니다. 오늘은 클로드 코드 사용량을 확인할 수 있는 두 가지 훌륭한 도구를 소개하겠습니다. 물론, 클로드는 세션이 지멋대로 조금씩 바뀌기 때문에 대충 사용하시면서 감을 잡아야 합니다.
클로드 코드 사용량 모니터링의 필요성
클로드 코드는 5시간 롤링 세션 윈도우 시스템으로 작동합니다2. 첫 메시지를 보낸 시점부터 5시간 동안 세션이 유지되며, 여러 세션이 동시에 활성화될 수 있어 수동으로 추적하기가 거의 불가능합니다2.
개발 중간에 갑자기 “세션이 종료되었습니다”라는 메시지를 보게 되면 정말 답답하죠. 이런 상황을 미리 예방하고 사용량을 체계적으로 관리하기 위해 두 가지 도구를 활용할 수 있습니다.
1. bunx ccusage : 전체 사용량 분석의 강자
https://github.com/ryoppippi/ccusage
ccusage는 클로드 코드가 로컬에 생성하는 JSONL 파일을 분석하여 사용량과 비용을 추적하는 CLI 도구입니다. 가장 큰 장점은 설치 없이 바로 사용할 수 있다는 점입니다. 제 사용량을 보시면 처음엔 10달러대 많이 사용한 날은 20달러대입니다. 하지만 맥스 결제 이후 사용량은 몇 배로 늘어났습니다. (오푸스가 비싸긴 합니다.)
설치 방법 (윈도우 환경)
윈도우에서 ccusage를 사용하는 가장 간단한 방법은 bunx를 활용하는 것입니다. 먼저 Bun을 설치해야 합니다.
1단계: Bun 설치
bash# PowerShell에서 실행
powershell -c "irm bun.sh/install.ps1|iex"
Bun은 Windows 10 이상에서 지원되며4, 설치가 완료되면 bun --version으로 확인할 수 있습니다.
2단계: ccusage 실행
bash# 가장 빠른 방법 (권장)
bunx ccusage
# npm 사용 (느림)
npx ccusage@latest
주요 명령어와 기능
기본 리포트 명령어
bash# 일일 사용량 리포트 (기본값)
bunx ccusage
bunx ccusage daily
# 월별 집계 리포트
bunx ccusage monthly
# 세션별 사용량
bunx ccusage session
# 5시간 청구 블록별 집계
bunx ccusage blocks
실시간 모니터링
bash# 실시간 대시보드 (새로운 기능!)
bunx ccusage blocks --live
고급 옵션
bash# 특정 기간 필터링
bunx ccusage daily --since 20241201 --until 20241231
# JSON 출력
bunx ccusage daily --json
# 모델별 비용 상세 분석
bunx ccusage daily --breakdown
ccusage의 장점
- 전체적인 사용량 파악: 클로드 코드를 얼마나 사용했는지 종합적으로 확인 가능
- 정확한 데이터: 로컬 JSONL 파일을 직접 분석하여 정확한 사용량 제공
- 다양한 리포트: 일별, 월별, 세션별 등 다양한 관점에서 분석 가능
- 비용 추정: 실제 비용이 얼마나 될지 추정 가능
2. claude-monitor : 실시간 세션 모니터링의 혁신
https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor
claude-monitor는 현재 진행 중인 세션의 토큰 사용량을 실시간으로 추적하는 도구입니다8. 코딩 세션 중에 실시간으로 토큰 소모 상황을 파악할 수 있어 매우 유용합니다.
설치 방법 (윈도우 환경)
Python 환경 준비
bash# Python 가상환경 생성 (권장)
python -m venv venv
venv\Scripts\activate
# 또는 WSL 사용 시
python3 -m venv venv
source venv/bin/activate
claude-monitor 설치
bash# uv 사용 (권장)
pip install uv
uv tool install claude-monitor
# 또는 pip 직접 설치
pip install claude-monitor
# GitHub에서 직접 클론
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor
cd Claude-Code-Usage-Monitor
pip install -r requirements.txt
주요 명령어와 옵션
기본 실행
bashclaude-monitor
플랜별 설정
bash# Pro 플랜 (약 44,000 토큰)
claude-monitor --plan pro
# Max5 플랜 (약 88,000 토큰)
claude-monitor --plan max5
# Max20 플랜 (약 220,000 토큰)
claude-monitor --plan max20
# 커스텀 플랜 (자동 감지)
claude-monitor --plan custom
고급 설정
bash# 리셋 시간 설정 (오전 9시)
claude-monitor --reset-hour 9
# 타임존 설정
claude-monitor --timezone Asia/Seoul
# 새로고침 속도 조절
claude-monitor --refresh-rate 5
# 실시간 모드
claude-monitor --view realtime
# 일별 사용량 보기
claude-monitor --view daily
claude-monitor의 특징
- 실시간 추적: 3초마다 갱신되는 컬러풀한 프로그레스 바
- 번 레이트 계산: 토큰 소모 속도를 분석하여 세션 종료 시점 예측
- 세션 리셋 알림: 5시간 롤링 윈도우 기반 리셋 시간 안내
- 다중 세션 지원: 여러 활성 세션 동시 모니터링
두 도구의 실제 사용 경험
ccusage의 장점
제가 실제로 사용해본 결과, ccusage는 전체적인 사용량 분석에 탁월합니다. 특히 bunx ccusage blocks --live 명령어는 실시간으로 현재 블록의 사용량을 보여주어 매우 유용했습니다.
claude-monitor의 한계
개인적으로 claude-monitor는 사용량에 약간의 변동이 있고 정확하다고 보기는 어려웠습니다. 이전 세션에서 많이 사용했다고 해도 현재 세션에서는 더 많이 사용할 수 있다는 점을 염두에 두어야 합니다.
실무 활용 팁
1. 개발 시작 시 세팅
bash# 터미널 1: 실시간 모니터링
bunx ccusage blocks --live
# 터미널 2: 개발 작업
claude
2. 주기적 사용량 체크
bash# 주간 사용량 확인
bunx ccusage daily --since 20241201 --until 20241207
# 월별 트렌드 분석
bunx ccusage monthly --breakdown
3. 비용 최적화
bash# 모델별 비용 분석
bunx ccusage daily --breakdown
# 세션별 효율성 체크
bunx ccusage session
마무리
클로드 코드를 효율적으로 사용하기 위해서는 사용량 모니터링이 필수입니다. bunx ccusage는 전체적인 사용량 분석과 비용 추정에 탁월하며, claude-monitor는 실시간 세션 모니터링에 유용합니다.
특히 윈도우 사용자라면 Bun을 설치하고 bunx ccusage를 활용하는 것을 강력히 추천합니다. 설치 없이 바로 사용할 수 있고, 다양한 리포트 기능으로 사용량을 체계적으로 관리할 수 있습니다.
두 도구를 적절히 조합하여 사용하면 클로드 코드의 토큰 한도에 도달하는 상황을 미리 예방하고, 더욱 효율적인 AI 코딩 경험을 만들어갈 수 있을 것입니다.