claude-usage: Claude Code 토큰 사용량과 비용을 확인하는 로컬 대시보드

9bow · 7월 9, 2026, 11:30오후

claude-usage 소개

Claude Code는 API, Pro, Max 요금제와 관계없이 세션마다 토큰 수·모델·프로젝트 정보를 담은 사용 로그를 로컬에 자동으로 남깁니다. 하지만 Anthropic 공식 UI는 이 로그를 세션별로 들여다보거나 비용으로 환산해 보여주지 않기 때문에, 자신이 오늘 얼마나 많은 토큰을 썼는지, Pro나 Max 정액제를 얼마나 소진했는지를 직관적으로 파악하기가 어렵습니다. claude-usage는 이 로컬 로그를 읽어 차트와 비용 추정치로 바꿔주는 대시보드로, 뉴스레터 The Product Compass 제작진이 만들었습니다.

접근 방식은 단순합니다. ~/.claude/projects/에 세션마다 하나씩 쌓이는 JSONL 트랜스크립트를 스캐너가 파싱해 SQLite 데이터베이스에 적재하고, 그 위에 웹 대시보드가 차트를 그립니다. Python 표준 라이브러리(sqlite3, http.server, json, pathlib)만 사용해 서드파티 패키지 없이 동작하며, pip install 이나 가상환경 구성 없이 바로 실행할 수 있습니다. 모든 처리가 로컬에서 끝나므로 사용 로그가 외부로 전송되지 않는다는 점도 특징입니다.

Claude Code CLI, VS Code 확장의 Claude Code 사이드바, Claude Code로 라우팅되는 Dispatched Code 세션의 사용량을 모두 추적합니다. 다만 Cowork 세션은 서버 사이드에서 실행되어 로컬에 JSONL 트랜스크립트를 남기지 않으므로 집계 대상에서 제외됩니다. 웹 대시보드 외에 VS Code 확장으로도 제공되어, 에디터를 벗어나지 않고 같은 화면을 사이드바에서 바로 확인할 수 있습니다.

claude-usage의 동작 원리

claude-usage의 핵심은 scanner.py와 dashboard.py 두 모듈입니다. Claude Code는 세션마다 하나의 JSONL 파일을 ~/.claude/projects/에 기록하며, assistant 타입 레코드에는 message.usage.input_tokens(입력 토큰), message.usage.output_tokens(출력 토큰), message.usage.cache_creation_input_tokens(캐시 생성 토큰), message.usage.cache_read_input_tokens(캐시 조회 토큰), message.model(사용 모델) 필드가 담겨 있습니다. scanner.py는 이 파일들을 파싱해 ~/.claude/usage.db의 SQLite 데이터베이스에 저장하는데, 파일 경로와 수정 시각을 기록해두는 증분(incremental) 방식이라 재실행 시 새로 추가되거나 변경된 파일만 처리합니다. 기본적으로 ~/.claude/projects/뿐 아니라 Xcode의 Claude 통합 디렉터리도 함께 스캔하며, --projects-dir 옵션으로 다른 위치를 지정할 수도 있습니다.

dashboard.py는 이렇게 쌓인 데이터를 localhost:8080에서 단일 페이지 대시보드로 서빙합니다. CDN에서 불러오는 Chart.js로 차트를 그리고 30초마다 자동 새로고침되며, 모델별 필터링과 북마크 가능한 날짜 범위 드롭다운을 지원합니다. 섹션 간 이동을 돕는 고정 내비게이션이 있고, 각 차트·표는 접어둘 수 있어 그 상태가 새로고침 이후에도 유지됩니다. HOST, PORT 환경변수로 바인딩 주소와 포트를 바꿀 수 있습니다.

claude-usage 설치 및 사용법

Python 3.8 이상만 있으면 되고, Claude Code를 이미 쓰고 있다면 Python도 대부분 설치되어 있습니다. macOS/Linux에서는 Homebrew로 설치할 수 있습니다.

brew tap phuryn/claude-usage https://github.com/phuryn/claude-usage
brew install phuryn/claude-usage/claude-usage
claude-usage dashboard

uv tool이나 pipx로 저장소를 클론하지 않고 바로 설치할 수도 있습니다.

uv tool install git+https://github.com/phuryn/claude-usage
claude-usage dashboard

저장소를 직접 클론해 실행하려면 다음과 같이 합니다.

git clone https://github.com/phuryn/claude-usage
cd claude-usage
python3 cli.py dashboard

Docker로 실행하는 방법도 제공됩니다. scripts/run-docker.sh가 이미지를 빌드한 뒤, ~/.claude를 읽기 전용으로 마운트하고 SQLite 데이터베이스는 별도의 명명된 볼륨(claude-usage-data)에 저장하는 컨테이너를 띄웁니다. 컨테이너가 세션 트랜스크립트를 수정할 수 없다는 점에서 로컬 클론 방식보다 격리 수준이 높습니다.

git clone https://github.com/phuryn/claude-usage
cd claude-usage
bash scripts/run-docker.sh

설치 방식과 무관하게 CLI는 다음 하위 명령을 지원합니다.

python cli.py scan        # JSONL을 스캔해 usage.db에 반영
python cli.py today       # 오늘 사용량을 모델별로 터미널에 표시
python cli.py week        # 최근 7일 요약
python cli.py stats       # 전체 기간 통계
python cli.py dashboard   # 스캔 후 브라우저 대시보드 오픈

claude-usage의 비용 계산 방식

비용 추정치는 2026년 6월 기준 Anthropic API 공식 가격을 기준으로 계산됩니다. 이름에 fable, mythos, opus, sonnet, haiku가 포함된 모델만 비용 계산 대상이며, 로컬 모델이나 그 외 이름의 모델은 n/a로 표시되어 제외됩니다.

모델	입력	출력	캐시 생성	캐시 조회
claude-fable-5	$10.00/MTok	$50.00/MTok	$12.50/MTok	$1.00/MTok
claude-mythos-5	$10.00/MTok	$50.00/MTok	$12.50/MTok	$1.00/MTok
claude-opus-4-8	$5.00/MTok	$25.00/MTok	$6.25/MTok	$0.50/MTok
claude-sonnet-4-6	$3.00/MTok	$15.00/MTok	$3.75/MTok	$0.30/MTok
claude-haiku-4-5	$1.00/MTok	$5.00/MTok	$1.25/MTok	$0.10/MTok

이 표는 API 종량제 기준 가격이라는 점에 유의해야 합니다. Pro나 Max 정액제로 Claude Code를 쓰고 있다면 실제 과금 구조가 토큰당 과금이 아니므로, 대시보드가 보여주는 금액은 "API로 환산했을 때의 참고값"에 가깝습니다. 대신 Pro·Max 구독자에게는 정액 한도 대비 소진율을 보여주는 진행 막대(progress bar)가 별도로 제공됩니다.

claude-usage의 라이선스

claude-usage는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

claude-usage 프로젝트 GitHub 저장소

claude-usage 설치하기

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~