claudetop

Claude Code에 하루 20달러를 쓰고 있지만, 그 사실을 인지하지 못하고 있습니다.

claudetop은 당신의 토큰(token)과 비용이 어디로 가고 있는지 실시간으로 정확하게 보여줍니다.

14:32 my-project/src/app Opus 20m 0s +256/-43 #auth-refactor
152.3K in / 45.2K out ████░░░░░░ 38% $3.47 $5.10/hr ~$174/mo
cache: 66% efficiency: $0.012/line opus:~$3.20 sonnet:~$0.88 haiku:~$0.23
...

Claude Code는 당신이 얼마를 쓰고 있는지 보여주지 않습니다. 세션을 마치고 결제 대시보드를 확인하면, 고작 30분 정도 작업한 것 같은데 65달러가 청구된 것을 발견하게 됩니다. 어떤 세션이 원인이었는지, 어떤 모델이 낭비적이었는지, 혹은 캐시(cache)가 제대로 작동하고 있었는지조차 알 길이 없습니다.

저는 모델 추정치는 10달러인데 실제 청구액은 65달러인 것을 발견한 후 claudetop을 만들었습니다. 알고 보니 압축(compaction) 과정이 토큰(token) 사용량의 80%를 숨기고 있었습니다. 비용은 실제였지만, 가시성(visibility)은 없었습니다.

git clone https://github.com/liorwn/claudetop.git
cd claudetop && ./install.sh

curl -fsSL https://raw.githubusercontent.com/liorwn/claudetop/main/install.sh | bash

claude plugin marketplace add liorwn/claudetop
claude plugin install claudetop

이를 통해 SessionEnd 훅(hook)과 모든 슬래시 명령어(/claudetop:stats, /claudetop:dashboard, /claudetop:branch, /claudetop:export, /claudetop:pricing)를 자동으로 사용할 수 있습니다.

그런 다음 Claude Code를 재시작하세요.

>

빈 프롬프트. 컨텍스트(context) 없음. 비용 정보 없음. 아무것도 알 수 없음.

14:32 my-project/src/app Opus 20m 0s +256/-43 #auth-refactor
152.3K in / 45.2K out ████░░░░░░ 38% $3.47 $5.10/hr ~$174/mo
cache: 66% efficiency: $0.012/line opus:~$3.20 sonnet:~$0.88 haiku:~$0.23
...

모든 응답에서 다음을 확인할 수 있습니다:

어떤 프로젝트에 있는지, 그리고 얼마나 깊게 들어갔는지
어떤 모델이 실행 중이며 얼마나 오래 실행되었는지
현재 비용, 시간당 비용, 그리고 예상 월간 비용
캐시(cache)가 얼마나 효율적인지 (토큰을 낭비하고 있지는 않은지?)
다른 모델을 사용한다면 비용이 얼마일지 (모델을 전환해야 할까요?)
문제가 발생했을 때의 스마트 알림

실제 세션 비용(녹색), 시간당 소모율 (burn rate), 그리고 사용 기록을 바탕으로 추정한 월간 예측치를 보여줍니다. 더 이상 예상치 못한 청구서에 놀랄 일이 없습니다.

Opus, Sonnet 또는 Haiku를 사용할 때의 세션 비용을 확인하세요. 실제 캐시 적중률 (cache hit ratio)을 반영한 **캐시 인지형 가격 책정 (cache-aware pricing)**이 적용됩니다. 현재 모델은 굵게 표시되어 즉시 비교할 수 있습니다.

가격 정보는 이 리포지토리의 pricing.json에서 자동으로 업데이트됩니다. Anthropic이 가격을 변경하면 claudetop도 최신 상태를 유지합니다.

캐시 적중률 (cache hit ratio)은 사용자가 효율적으로 작업하고 있는지 알려줍니다. 녹색(≥60%)은 입력 토큰의 대부분이 재사용되고 있음을 의미합니다. 빨간색(<30%)은 압축 (compaction)이나 모델 전환 등으로 인해 전체를 다시 읽어야 하는 상황임을 의미합니다.

주의가 필요한 경우에만 나타납니다:

알림 (Alert)	발생한 상황	조치 사항
$5 MARK / $10 / $25	비용 마일스톤 돌파	점검: 가치를 제대로 얻고 있는가?
OVER BUDGET	일일 예산 초과	작업을 마무리하거나 모델을 전환하세요
CONSIDER FRESH SESSION	>2시간 경과 + >60% 컨텍스트	새로 시작하세요 — 수익 체감률 저하 (diminishing returns)
LOW CACHE	5분 후 캐시 <20%	컨텍스트가 초기화되어 토큰을 다시 읽고 있음
BURN RATE	>$15/시간 속도	폭주하는 서브에이전트 (subagents) 또는 무한 루프
SPINNING?	$1 이상 지출, 코드 출력 없음	연구 루프 (research loop)에 갇힘
TRY /fast	Opus에서 라인당 >$0.05 지출	이 작업에는 가장 큰 모델이 필요하지 않음
COMPACT SOON	컨텍스트 창 >80% 가득 참	자동 압축 (auto-compaction) 임박

모든 세션은 자동으로 기록됩니다. 돈이 어디에 쓰이는지 확인하세요:

claudetop-stats # 오늘의 요약
claudetop-stats week # 이번 주
claudetop-stats month # 이번 달
...

claudetop-stats This Week
──────────────────────────────────────────────────────
Summary
...

분석 엔진은 hook으로 기록된 파일뿐만 아니라 모든 Claude Code JSONL 세션 파일을 스캔합니다. claudetop이 설치되기 전의 세션, 서브에이전트 (subagent) 비용, 턴당 토큰 상세 내역을 포함한 전체 기록을 캡처합니다.

claudetop-engine scan # 모든 JSONL 파일 스캔 → SQLite
claudetop-engine today # 오늘 (턴당 도구 상세 내역 포함)
claudetop-engine stats # 전체 기간 (서브에이전트 (subagents), 주요 도구, 프로젝트)
...

라이브 대시보드는 활동 히트맵 (activity heatmap), 모델별 비용 차트, 프로젝트 및 도구별 상세 내역, 서브에이전트 (subagent) 비용 귀속, 그리고 정렬 가능한 세션 테이블을 제공하며 — 이 모든 기능은 모델 필터링 및 시간 범위 선택이 가능합니다. 30초마다 자동으로 새로고침됩니다.

의존성 제로 — Python 3 표준 라이브러리 (sqlite3, http.server, json)만 사용합니다.

기능, 버그 또는 이니셔티브(initiative)별로 비용을 추적하세요:

export CLAUDETOP_TAG=auth-refactor
# ... 인증 관련 작업 수행 ...
claudetop-stats tag auth-refactor
...

export CLAUDETOP_DAILY_BUDGET=50

예산의 80% 사용 시 budget: $12 left라고 표시되며 → 예산을 초과하면 OVER BUDGET ($52/$50)라고 표시됩니다.

export CLAUDETOP_THEME=full # 기본값: 3-5줄
export CLAUDETOP_THEME=minimal # 2줄
export CLAUDETOP_THEME=compact # 1줄

claudetop 데이터를 iTerm2의 크롬 (chrome) 요소 — 탭 제목, 상태 표시줄, 배지 워터마크(badge watermark)에 반영하세요:

export CLAUDETOP_ITERM=all # 모든 기능 활성화
export CLAUDETOP_ITERM=title # 탭/윈도우 제목만
export CLAUDETOP_ITERM=badge # 워터마크 오버레이만
...

탭 제목 (Tab title) — iTerm2 탭에 project | $4.21 | Opus 4.6 | ctx:38%를 표시합니다. 별도의 설정이 필요 없습니다.

배지 (Badge) — 터미널 배경에 비용, 모델, 컨텍스트 (context)를 한눈에 볼 수 있도록 희미한 워터마크를 표시합니다. 출력 내용을 스크롤하는 동안 비용을 계속 확인할 수 있어 유용합니다.

배경색 (Background color) — 세션 상태에 따라 터미널 배경색을 미세하게 변경합니다:

색조 (Tint)	의미
Green (녹색)	정상적인 세션 (낮은 컨텍스트, $5 미만) 또는 세션 종료 (유휴/대기 중)
...

세션이 종료되면 배경색이 녹색으로 유지되어, 어떤 터미널이 유휴 상태인지 활성 상태인지 한눈에 확인할 수 있습니다. 다음 세션이 깨끗하게 시작되면 기본값으로 재설정됩니다.

상태 표시줄 (Status bar) — iTerm2 상태 표시줄(터미널 상단 또는 하단)에 표시할 수 있는 사용자 정의 변수를 설정합니다. iTerm2에서 다음과 같이 설정하세요: Preferences > Profiles > Session > Status Bar > "Interpolated String" 컴포넌트 추가:

변수 (Variable)	내용 (Content)	예시 (Example)
\(user.claudetop_cost)	세션 비용 (Session cost)	$4.21
\(user.claudetop_model)	현재 모델 (Current model)	Opus 4.6
\(user.claudetop_ctx)	컨텍스트 사용량 (Context usage)	38%
\(user.claudetop_project)	프로젝트 이름 (Project name)	my-project
\(user.claudetop_duration)	세션 시간 (Session time)	20m 0s
\(user.claudetop_cache)	캐시 히트율 (Cache hit ratio)	66%
\(user.claudetop_velocity)	소모율 (Burn rate)	$5.10/hr
\(user.claudetop_tokens_in)	입력 토큰 (Input tokens)	152.3K
\(user.claudetop_tokens_out)	출력 토큰 (Output tokens)	45.2K
\(user.claudetop_lines)	변경된 라인 수 (Lines changed)	+256/-43
\(user.claudetop_tag)	세션 태그 (Session tag)	#auth-refactor

non-iTerm2 터미널에서는 동작하지 않음 (No-op) — 이스케이프 시퀀스 (escape sequences)가 조용히 무시됩니다.

컨텍스트 윈도우 (context window)를 무엇이 점유하고 있는지 확인하세요:

in:80% out:20% (fresh:15% cwrite:7% cread:76%)

높은 cread

= 캐시가 잘 작동하고 있음. 높은 fresh

= 매 턴마다 파일을 다시 읽고 있음.

실행 가능한 스크립트를 ~/.claude/claudetop.d/ 디렉토리에 넣으세요

— 그러면 상태 표시줄의 일부가 됩니다.

포함됨 (기본적으로 활성화됨):

플러그인 (Plugin)	표시 내용 (What it shows)
git-branch.sh	main* (브랜치 + 변경 사항 표시기)

예시 플러그인 (복사하여 활성화):

cp ~/.claude/claudetop.d/_examples/spotify.sh ~/.claude/claudetop.d/

플러그인 (Plugin)	표시 내용 (What it shows)
spotify.sh	♫ Artist - Song (macOS)
gh-ci-status.sh	CI ✓ 또는 CI ✗ (GitHub Actions)
meeting-countdown.sh	Mtg in 12m: Standup (macOS Calendar)
ticket-from-branch.sh	PROJ-123 (브랜치 이름에서 추출)
weather.sh	현재 날씨 (wttr.in)
news-ticker.sh	주요 HN 스토리
pomodoro.sh	포모도로 타이머 (Focus timer)
system-load.sh	CPU 부하 평균 (CPU load average)

단 4줄로 직접 작성하기:

#!/bin/bash
JSON=$(cat)
COST=$(echo "$JSON" | jq -r '.cost.total_cost_usd')
...

실행 권한을 부여하고 ~/.claude/claudetop.d/ 디렉토리에 넣으세요.

, 완료.

가격 정보는 이 리포지토리(repo)로부터 매일 업데이트됩니다. Anthropic이 가격을 변경하면, 저희가 pricing.json을 업데이트하며 모든 사용자는 다음 날 아침 새로운 요율을 적용받게 됩니다.

현재 가격 (Claude 4.6, 2026년 3월 기준):

모델 (Model)	입력 (Input)	캐시 쓰기 (Cache Write)	캐시 읽기 (Cache Read)	출력 (Output)	비고 (Notes)
Opus 4.6	$5/MTok	$6.25/MTok	$0.50/MTok	$25/MTok
...

확장 사고 (Extended thinking) 토큰은 표준 출력 요율로 청구됩니다. 추가 비용은 없습니다.

수동으로 업데이트하려면: ~/.claude/update-claudetop-pricing.sh를 실행하세요.

모든 지표는 신호등 색상을 사용합니다 — 초록색은 정상, 빨간색은 조치가 필요함을 의미합니다:

지표 (Metric)	초록색 (Green)	노란색 (Yellow)	빨간색 (Red)
비용 속도 (Cost velocity)	<$3/hr	<$8/hr	≥$8/hr
...

• 상태 표시줄 (status line)을 지원하는 Claude Code
  jq

— brew install jq

또는 apt install jq

bc

— macOS 및 대부분의 Linux에 사전 설치되어 있음

가격이 변경되었나요? 새로운 모델이 추가되었나요? pricing.json을 업데이트하는 PR (Pull Request)을 보내주세요.

. 모든 사용자는 다음 날 아침 업데이트를 받게 됩니다.

유용한 플러그인을 만드셨나요? plugins/examples/로 PR을 환영합니다.

.

MIT