Claude Code 사용량을 모니터링하기 위한 최고의 오픈 소스 도구 (2026)

Claude Code 사용량을 모니터링하기 위한 최고의 오픈 소스 도구 (2026)

Claude Code는 강력한 AI 코딩 어시스턴트이지만, 토큰 기반 요금 체계로 인해 사용량을 세심하게 추적하지 않으면 예상치 못한 비용이 발생할 수 있습니다. 단일 복합 에이전트 작업만으로도 수십만 개의 토큰이 소비될 수 있으며, 모니터링 없이는 비용이 빠르게 불어날 수 있습니다.

이 가이드에서는 Claude Code 사용량을 모니터링하고, 토큰 소비 추적, 예산 알림 설정 및 지출 최적화에 도움을 주는 최고의 오픈 소스 도구들을 소개합니다.

왜 Claude Code 사용량을 모니터링해야 할까요?

도구를 살펴보기 전에, 모니터링이 중요한 이유는 다음과 같습니다.

Claude 모델	입력 비용 (1M 토큰당)	출력 비용 (1M 토큰당)	일반적인 일일 사용량	일일 비용
Claude Opus 4	$15.00	$75.00	100K 입력 / 50K 출력	$5.25
Claude Sonnet 4	$3.00	$15.00	200K 입력 / 100K 출력	$2.10
Claude Haiku 3.5	$0.80	$4.00	300K 입력 / 150K 출력	$0.84

Opus 4를 사용하는 하비 유저라면 월 $100-200를 쉽게 지출할 수 있습니다. 토큰이 어디에 사용되는지 가시성이 확보되지 않으면 최적화는 불가능합니다.

도구 1: ccusage (Claude Code Usage Tracker)

ccusage는 Claude Code 사용량 추적을 위해 특별히 제작된 가장 인기 있는 오픈 소스 도구입니다.

주요 기능

• Claude Code의 로컬 세션 로그를 읽음
• 세션별 토큰 사용량 및 예상 비용 계산
• 일간, 주간, 월간 사용량 보고서 생성
• 프로젝트 및 작업 유형별 사용량 세부 정보 표시
• 추가 분석을 위해 데이터를 CSV로 내보내기

설치 방법

# npm을 통해 설치
npm install -g ccusage

# 또는 설치 없이 npx 사용
npx ccusage

사용법

# 오늘의 사용량 요약 표시
ccusage

# 지난 7일간의 사용량 표시
ccusage --days 7

# 특정 날짜 범위의 사용량 표시
ccusage --from 2026-01-01 --to 2026-01-31

# CSV로 내보내기
ccusage --days 30 --format csv > claude-usage-january.csv

# 세션별 상세 내역 표시
ccusage --detailed

# 프로젝트 디렉토리별 사용량 표시
ccusage --by-project

출력 예시

Claude Code Usage Report (Last 7 Days)
=======================================

Total Tokens:     1,245,670
  Input:            892,340
  Output:           353,330

Estimated Cost:   $19.83
  Input:            $2.68 (892K @ $3.00/1M)
  Output:           $5.30 (353K @ $15.00/1M)

Daily Breakdown:
  Mon Feb 02:  180,200 tokens  ($2.87)
  Tue Feb 03:  210,450 tokens  ($3.35)
  Wed Feb 04:  156,780 tokens  ($2.49)
  Thu Feb 05:  298,120 tokens  ($4.74)
  Fri Feb 06:  400,120 tokens  ($6.38)

Top Projects:
  ~/projects/web-app     520,300 tokens  ($8.28)
  ~/projects/api-server  380,200 tokens  ($6.05)
  ~/projects/cli-tool    345,170 tokens  ($5.50)

설정

// ~/.ccusage/config.json
{
  "defaultDays": 7,
  "currency": "USD",
  "models": {
    "claude-opus-4-20250514": {
      "inputCost": 15.0,
      "outputCost": 75.0
    },
    "claude-sonnet-4-20250514": {
      "inputCost": 3.0,
      "outputCost": 15.0
    }
  },
  "budgetAlert": {
    "daily": 10.0,
    "weekly": 50.0,
    "monthly": 150.0
  }
}

도구 2: claude-token-counter

claude-token-counter는 실시간 토큰 추적을 제공하기 위해 Anthropic API에 연결되는 경량 Python 도구입니다.

설치 방법

pip install claude-token-counter

프록시로 사용하기

claude-token-counter는 Claude Code와 Anthropic API 사이의 프록시로 실행되어 모든 요청을 로깅할 수 있습니다.

# 로깅 프록시 시작
claude-token-counter proxy --port 8080

# 다른 터미널에서 Claude Code가 프록시를 사용하도록 설정
export ANTHROPIC_BASE_URL="http://localhost:8080"
claude  # 평소처럼 Claude Code 시작

대시보드

# 웹 대시보드 실행
claude-token-counter dashboard --port 3000

# 브라우저에서 http://localhost:3000 접속

대시보드 표시 항목:

• 실시간 토큰 소비 그래프
• 세션별 비용 상세 내역
• 모델별 사용 분포 (Opus vs Sonnet vs Haiku)
• 누적 지출 추세
• 예산 알림 및 예측

프로그래밍 방식 접근

from claude_token_counter import UsageTracker

tracker = UsageTracker()

# 오늘의 사용량 가져오기
today = tracker.get_usage(period="today")
print(f"Tokens used today: {today.total_tokens}")
print(f"Estimated cost: ${today.estimated_cost:.2f}")

# 프로젝트별 사용량 가져오기
projects = tracker.get_usage_by_project(days=30)
for project in projects:
    print(f"{project.name}: {project.total_tokens} tokens (${project.cost:.2f})")

도구 3: Anthropic Usage Dashboard (API 기반)

엄격히 말해 오픈 소스는 아니지만, Anthropic API는 오픈 소스 도구로 쿼리할 수 있는 사용량 엔드포인트를 제공합니다.

API를 통한 사용량 쿼리

import httpx
from datetime import datetime, timedelta

ANTHROPIC_ADMIN_KEY = "sk-ant-admin-your-key"

async def get_usage(days: int = 7):
    """Anthropic API에서 사용량 데이터를 가져옵니다."""
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days)

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.anthropic.com/v1/organizations/usage",
            headers={
                "x-api-key": ANTHROPIC_ADMIN_KEY,
                "anthropic-version": "2024-01-01"
            },
            params={
                "start_date": start_date.strftime("%Y-%m-%d"),
                "end_date": end_date.strftime("%Y-%m-%d")
            }
        )
        return response.json()

Grafana로 커스텀 대시보드 구축

Anthropic 사용량 데이터를 Prometheus로 내보내고 Grafana로 시각화합니다.

# prometheus_exporter.py
from prometheus_client import start_http_server, Gauge
import time

token_usage = Gauge('claude_tokens_total', 'Total tokens used', ['model', 'direction'])
cost_gauge = Gauge('claude_cost_usd', 'Estimated cost in USD', ['model'])

def update_metrics():
    """Anthropic에서 사용량을 가져와 Prometheus 메트릭을 업데이트합니다."""
    usage = get_usage(days=1)  # 위의 함수 사용

    for model_usage in usage.get("models", []):
        model = model_usage["model"]
        token_usage.labels(model=model, direction="input").set(model_usage["input_tokens"])
        token_usage.labels(model=model, direction="output").set(model_usage["output_tokens"])
        cost_gauge.labels(model=model).set(model_usage["estimated_cost"])

if __name__ == "__main__":
    start_http_server(9090)
    while True:
        update_metrics()
        time.sleep(60)

그 후 Prometheus scrape target을 추가하고 시각화를 위한 Grafana 대시보드를 생성합니다.

도구 4: LLM Cost Calculator CLI

llm-cost는 Claude뿐만 아니라 여러 LLM 제공업체의 비용을 추적하는 범용 CLI 도구입니다.

설치 방법

# pip를 통해 설치
pip install llm-cost-calculator

# 또는 Homebrew를 통해 설치
brew install llm-cost

사용법

# Claude Code 로그를 스캔하고 비용 계산
llm-cost scan --provider anthropic --days 30

# 실시간으로 Claude Code 사용량 감시
llm-cost watch --provider anthropic

# 예산 알림 설정
llm-cost budget --daily 10 --weekly 50 --monthly 200

# 제공업체별 비용 비교
llm-cost compare --task "code review" --providers anthropic,openai,google

예산 알림 설정 샘플

# ~/.llm-cost/config.yaml
providers:
  anthropic:
    api_key_env: ANTHROPIC_API_KEY
    models:
      claude-opus-4-5:
        input_cost_per_million: 15.0
        output_cost_per_million: 75.0
      claude-sonnet-4:
        input_cost_per_million: 3.0
        output_cost_per_million: 15.0

alerts:
  daily_limit: 10.0
  weekly_limit: 50.0
  monthly_limit: 200.0
  notification:
    type: "slack"
    webhook_url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

도구 5: Claude Code 내장 사용량 추적

Claude Code 자체에도 많은 사용자가 간과하는 내장 사용량 추적 기능이 있습니다.

Claude Code 내에서 사용량 확인

# Claude Code 세션 내에서 입력:
/usage

# 현재 세션의 토큰 소비량을 보여줍니다.
# 입력 토큰, 출력 토큰, 캐시 적중(cache hits) 포함

세션 로그 직접 읽기

Claude Code는 상세 세션 로그를 로컬에 저장합니다.

# macOS
ls ~/.claude/projects/

# 각 세션은 JSON 로그 파일을 가짐
# jq를 사용하여 커스텀 분석 수행
cat ~/.claude/projects/*/sessions/*.json | \
  jq '[.[] | select(.type == "usage") | .tokens] | add'

Claude Code 로그 파싱을 위한 커스텀 스크립트

#!/usr/bin/env python3
"""사용량 분석을 위해 Claude Code 세션 로그를 파싱합니다."""

import json
from pathlib import Path
from datetime import datetime

CLAUDE_DIR = Path.home() / ".claude" / "projects"

def analyze_usage(days: int = 7):
    total_input = 0
    total_output = 0
    sessions = 0

    cutoff = datetime.now().timestamp() - (days * 86400)

    for session_file in CLAUDE_DIR.rglob("*.json"):
        if session_file.stat().st_mtime < cutoff:
            continue

        try:
            data = json.loads(session_file.read_text())
            for entry in data:
                if entry.get("type") == "usage":
                    total_input += entry.get("input_tokens", 0)
                    total_output += entry.get("output_tokens", 0)
                    sessions += 1
        except (json.JSONDecodeError, KeyError):
            continue

    # 비용 계산 (Sonnet 4 요율 기준)
    input_cost = (total_input / 1_000_000) * 3.0
    output_cost = (total_output / 1_000_000) * 15.0

    print(f"Usage Summary (Last {days} days)")
    print(f"{'='*40}")
    print(f"Sessions:      {sessions}")
    print(f"Input tokens:  {total_input:,}")
    print(f"Output tokens: {total_output:,}")
    print(f"Input cost:    ${input_cost:.2f}")
    print(f"Output cost:   ${output_cost:.2f}")
    print(f"Total cost:    ${input_cost + output_cost:.2f}")

if __name__ == "__main__":
    analyze_usage(days=30)

비용 최적화 팁

모니터링을 통해 사용 패턴을 파악한 후, 다음 최적화 전략을 적용해 보세요.

1. 작업에 적합한 모델 사용

작업	권장 모델	Opus 대비 비용 절감
코드 완성	Haiku 3.5	95% 저렴
버그 수정 (단순)	Sonnet 4	80% 저렴
코드 리뷰	Sonnet 4	80% 저렴
아키텍처 설계	Opus 4	기준점
복잡한 리팩토링	Opus 4	기준점

2. 모델에 전송되는 컨텍스트 축소

# .claudeignore를 사용하여 불필요한 파일 제외
# 프로젝트 루트에 .claudeignore 생성
echo "node_modules/
dist/
.git/
*.lock
*.log
coverage/
.env" > .claudeignore

3. Anthropic 대시보드에서 지출 한도 설정

console.anthropic.com/settings/limits에서 다음을 설정하세요.

• 월간 지출 상한선
• 요청당 토큰 한도
• 모델 액세스 제한

4. 프롬프트 접두사 캐싱 (Prompt Caching)

Claude Code는 프롬프트 캐싱을 지원하여 반복되는 컨텍스트에 대해 입력 토큰 비용을 최대 90%까지 줄일 수 있습니다.

# 시스템 프롬프트 및 반복되는 파일 내용에 대해 프롬프트 캐싱이 자동으로 적용됩니다.
# CLAUDE.md 파일을 잘 구조화하여 효율적으로 캐싱되도록 하세요.

모니터링 도구 비교표

도구	유형	실시간	비용 추적	알림	멀티 제공업체	설정 난이도
ccusage	CLI	아니오	예	예	아니오 (Claude 전용)	쉬움
claude-token-counter	프록시 + 대시보드	예	예	예	아니오 (Claude 전용)	보통
Anthropic API + Grafana	대시보드	거의 실시간	예	예 (커스텀)	아니오	높음
llm-cost	CLI + 설정	예 (watch 모드)	예	예	예	보통
내장 /usage	CLI 명령	예	기본	아니오	아니오	없음

마치며

비용을 예측 가능한 수준으로 유지하려면 Claude Code 사용량 모니터링은 필수입니다. 빠른 확인을 위해 내장 /usage 명령어로 시작한 다음, 일일 보고서와 비용 추적을 위해 ccusage를 설정해 보세요. 팀 단위나 헤비 유저라면 Anthropic API를 연동한 Grafana 대시보드가 기업 수준의 가시성을 제공할 것입니다.

가장 효과적인 최적화 방법은 일상적인 작업에 Opus 4 대신 Sonnet 4를 사용하는 것입니다. 대부분의 코딩 작업에서 품질 저하를 최소화하면서 비용을 80% 절감할 수 있습니다.

코드와 함께 AI 생성 미디어가 필요한 애플리케이션을 구축 중이라면, Hypereal AI는 이미지, 비디오, 오디오 생성에 대해 투명한 크레딧당 요금제를 제공합니다. 숨겨진 비용이나 예상치 못한 요금 없이, 35개의 무료 크레딧으로 예측 가능한 가격 정책을 경험해 보세요.