ccusage - Analysewerkzeug für die Claude Code-Nutzung

Projektübersicht

ccusage ist ein CLI-Werkzeug zur Analyse von Nutzungsdaten aus lokalen Claude Code JSONL-Dateien. Das Projekt wurde von @ryoppippi entwickelt und ist von einem Artikel über die Verfolgung der Claude Code-Nutzungskosten inspiriert.

Hauptmerkmale

📊 Verschiedene Berichtstypen

• Tagesbericht: Fasst die Token-Nutzung und Kosten nach Datum zusammen
• Monatsbericht: Fasst die Token-Nutzung und Kosten nach Monat zusammen
• Sitzungsbericht: Zeigt die Nutzung gruppiert nach Dialogsitzungen an
• 5-Stunden-Block-Bericht: Berichte basierend auf 5-Stunden-Abrechnungsfenstern
• Statuszeile: Eine kompakte Statuszeile für Hooks (Beta)

🎯 Leistungsstarke Filter- und Analysefunktionen

• Datumsfilterung: Filtert Berichte nach Datumsbereich mit --since und --until
• Projektanalyse: Gruppierung nach Projekt/Instanz, unterstützt Filterung nach spezifischen Projekten
• Kostenaufschlüsselung nach Modell: Aufschlüsselung der Kosten pro Modell
• Zeitzone und Lokalisierung: Unterstützt UTC-Zeitzone und japanisches Lokalisierungsformat

🎨 Ästhetische Ausgabe und Anzeige

• Farbige Tabellenformatierung mit automatischem responsivem Layout
• Intelligente Tabellen: Schmale Terminals (<100 Zeichen) wechseln automatisch in den Kompaktmodus und zeigen grundlegende Spalten an
• Kompaktmodus: Erzwingt ein kompaktes Tabellenlayout mit dem --compact-Flag, ideal für Screenshots und zum Teilen
• Verbesserte Modellanzeige: Modellnamen werden als Aufzählungspunkte angezeigt, um die Lesbarkeit zu verbessern

💰 Kostenverfolgungsfunktionen

• Anzeige der täglichen/monatlichen/sitzungsbezogenen Kosten in US-Dollar
• Cache-Token-Unterstützung: Verfolgt und zeigt Cache-Erstellungs- und Cache-Lese-Token separat an
• Offline-Modus: Verwendet --offline, um bei fehlender Netzwerkverbindung vorab zwischengespeicherte Preisdaten zu nutzen (nur für Claude-Modelle)

⚡ Echtzeitüberwachung

• Echtzeit-Nutzungs-Dashboard
• Echtzeitüberwachung: ccusage blocks --live

Installation und Nutzung

Schnellstart (ohne Installation)

Da ccusage eine extrem geringe Paketgröße hat, kann es direkt ohne Installation ausgeführt werden:

# Mit bunx (empfohlen, schneller)
bunx ccusage

# Mit npx
npx ccusage@latest

# Mit deno (mit Sicherheits-Flags)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

Globale Installation

# Global mit npm installieren
npm install -g ccusage

# Global mit bun installieren
bun install -g ccusage

# Dann ausführen
ccusage

Entwicklungsumgebung

# Repository klonen
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Abhängigkeiten installieren
bun install

# Werkzeug ausführen
bun run report [subcommand] [options]

Grundlegende Nutzung

Tagesbericht

# Alle täglichen Nutzungsdaten anzeigen
ccusage daily

# Nach Datumsbereich filtern
ccusage daily --since 20250525 --until 20250530

# Benutzerdefiniertes Claude-Datenverzeichnis verwenden
ccusage daily --path /custom/path/to/.claude

# Ausgabe im JSON-Format
ccusage daily --json

# Kostenaufschlüsselung pro Modell
ccusage daily --breakdown

# UTC-Zeitzone verwenden
ccusage daily --timezone UTC

# Japanische Lokalisierung verwenden
ccusage daily --locale ja-JP

Projektanalyse

# Nach Projekt/Instanz gruppieren
ccusage daily --instances

# Auf ein bestimmtes Projekt filtern
ccusage daily --project myproject

# Kombinierte Nutzung
ccusage daily --instances --project myproject --json

Sitzungsbericht

# Alle Sitzungen anzeigen
ccusage session

# Sitzungen nach letztem Aktivitätsdatum filtern
ccusage session --since 20250525

# Filter kombinieren
ccusage session --since 20250525 --until 20250530 --path /custom/path

# Ausgabe im JSON-Format
ccusage session --json

Echtzeitüberwachung

# Echtzeit-Nutzungs-Dashboard
ccusage blocks --live

# 5-Stunden-Abrechnungsfenster
ccusage blocks

# Statuszeile (Beta)
ccusage statusline

Kompaktmodus

# Kompakten Tabellenmodus erzwingen
ccusage --compact

# Kompakter Monatsbericht
ccusage monthly --compact

Befehlsoptionen

Alle Befehle unterstützen die folgenden Optionen:

• -s, --since <date>: Filtert ab Datum (Format YYYYMMDD)
• -u, --until <date>: Filtert bis Datum (Format YYYYMMDD)
• -p, --path <path>: Benutzerdefinierter Pfad zum Claude-Datenverzeichnis (Standard: ~/.claude)
• -j, --json: Gibt die Ergebnisse im JSON-Format anstelle einer Tabelle aus
• -h, --help: Zeigt Hilfeinformationen an
• -v, --version: Zeigt die Version an

Ausgabebeispiele

Tagesbericht-Ausgabe

╭──────────────────────────────────────────╮
│                                          │
│ Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ Date             │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total            │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

Sitzungsbericht-Ausgabe

╭───────────────────────────────────────────────╮
│                                               │
│ Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Project / Session            │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │ Last Activity │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total                        │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

Technische Architektur

Abhängigkeitsanforderungen

• Bun Laufzeitumgebung
• Claude Code Nutzungsverlaufsdateien (~/.claude/projects/**/*.jsonl)

Projektstruktur

ccusage/
├── commands/
│   ├── daily.ts        # Befehl für Tagesbericht
│   └── session.ts      # Befehl für Sitzungsbericht
├── data-loader.ts      # Logik zum Laden von JSONL-Daten
├── index.ts           # CLI-Einstiegspunkt
├── logger.ts          # Logger-Konfiguration
├── utils.ts           # Gemeinsame Hilfsfunktionen
└── package.json

Entwicklung und Tests

# Tests ausführen
bun test

# Typüberprüfung
bun run typecheck

# Code-Linting
bun run lint

# Code formatieren
bun run format

Integrationsfunktionen

🔌 MCP-Integration

Eingebauter Model Context Protocol Server zur Integration mit anderen Tools

Zusammenfassung

ccusage ist ein leistungsstarkes und benutzerfreundliches CLI-Werkzeug, das speziell für Claude Code-Benutzer entwickelt wurde, um die Token-Nutzung und die damit verbundenen Kosten zu analysieren und zu verfolgen. Sein leichtgewichtiges Design, der umfangreiche Funktionsumfang und die ästhetische Ausgabe machen es zur idealen Wahl für Entwickler, die ihre Claude Code-Nutzung optimieren und Kosten verwalten möchten.