개요
claude-usage는 Claude Code가 ~/.claude/projects/ 등에 남기는 세션별 JSONL 로그를 읽어 토큰 사용량, 모델, 프로젝트, 세션 이력과 비용 추정치를 보여주는 로컬 대시보드다. 스캐너가 로그를 SQLite 데이터베이스에 증분 적재하고, 웹 대시보드가 localhost:8080에서 차트와 표를 제공한다. Python 표준 라이브러리만 사용해 별도 서드파티 패키지 없이 실행할 수 있으며, 처리 결과와 사용 로그가 외부로 전송되지 않는 것이 특징이다. Claude Code CLI·VS Code 확장·Dispatched Code 세션을 추적하지만, 서버에서 실행되어 로컬 JSONL을 남기지 않는 Cowork 세션은 제외한다.
핵심 포인트
scanner.py가 assistant 레코드의 입력·출력·캐시 생성·캐시 조회 토큰과 모델 정보를 파싱해~/.claude/usage.db에 저장한다.- 파일 경로와 수정 시각을 기록하는 증분 스캔 방식이라 재실행 시 새로 추가되거나 변경된 파일만 처리한다.
--projects-dir로 스캔 위치를 바꿀 수 있다. dashboard.py는 모델 필터, 날짜 범위 선택, 30초 자동 새로고침, 접을 수 있는 차트·표와 고정 내비게이션을 제공한다.HOST,PORT환경변수로 바인딩을 조정할 수 있다.- Homebrew,
uv tool, 소스 클론, Docker 방식으로 설치할 수 있으며scan,today,week,stats,dashboardCLI 명령을 제공한다. - 비용은 원문에 제시된 2026년 6월 Anthropic API 가격을 기준으로 계산되는 참고값이다. Pro·Max 정액제의 실제 과금액을 의미하지 않으며, 별도로 정액 한도 대비 소진율 진행 막대를 제공한다.
- MIT 라이선스이며 VS Code 확장과 Open VSX 배포판도 제공된다.
왜 중요한가
Claude Code 사용량은 로컬 세션 로그에 기록되지만 공식 UI만으로는 세션별 토큰 사용량과 API 기준 비용 환산값을 한눈에 보기 어렵다. claude-usage는 이 데이터를 로컬에서 집계해 사용 패턴과 모델별 소비량을 확인하게 하므로, 사용량 점검과 비용 감각을 얻는 보조 도구로 의미가 있다. 다만 구독제의 실제 청구 금액과 API 종량제 환산 비용은 다르므로 비용 수치를 청구서처럼 해석해서는 안 된다.
후속으로 볼 링크와 키워드
- 원문: https://discuss.pytorch.kr/t/claude-usage-claude-code/11174
- 프로젝트 GitHub: https://github.com/phuryn/claude-usage
- VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=PawelHuryn.claude-usage-phuryn
- Open VSX: https://open-vsx.org/extension/PawelHuryn/claude-usage-phuryn
- 관련 위키: moc-claude-code, 2026-06-19-artifacts-in-claude-code
- 키워드: Claude Code, JSONL 트랜스크립트, SQLite, 증분 스캔, 로컬 대시보드, 토큰 사용량, API 비용 추정, Pro/Max 사용량