ccusage - Outil d'analyse de l'utilisation de Claude Code

Aperçu du projet

ccusage est un outil CLI conçu pour analyser les données d'utilisation de Claude Code à partir de fichiers JSONL locaux. Ce projet a été développé par @ryoppippi, inspiré par un article sur le suivi des coûts d'utilisation de Claude Code.

Caractéristiques principales

📊 Plusieurs types de rapports

• Rapport quotidien: Résumé de l'utilisation des jetons et des coûts par date
• Rapport mensuel: Résumé de l'utilisation des jetons et des coûts par mois
• Rapport de session: Affiche l'utilisation regroupée par session de conversation
• Rapport par bloc de 5 heures: Rapports basés sur des fenêtres de facturation de 5 heures
• Ligne d'état: Ligne d'état compacte pour les hooks (version Bêta)

🎯 Fonctions de filtrage et d'analyse puissantes

• Filtrage par date: Filtrez les rapports par plage de dates à l'aide de --since et --until
• Analyse de projet: Regroupement par projet/instance, avec prise en charge du filtrage par projet spécifique
• Répartition des coûts par modèle: Répartition détaillée des coûts pour chaque modèle
• Fuseau horaire et localisation: Prise en charge du fuseau horaire UTC et du format de localisation japonais

🎨 Sortie et affichage esthétiques

• Affichage en format tableau coloré avec une mise en page réactive automatique
• Tableaux intelligents: mode compact automatique pour les terminaux étroits (<100 caractères), affichant les colonnes essentielles
• Mode compact: utilisez l'indicateur --compact pour forcer une mise en page de tableau compacte, idéale pour les captures d'écran et le partage
• Affichage amélioré des modèles: les noms de modèles sont affichés sous forme de liste à puces pour une meilleure lisibilité

💰 Fonctions de suivi des coûts

• Affichage des coûts quotidiens/mensuels/par session en USD
• Prise en charge des jetons mis en cache: suivi et affichage séparés des jetons de création de cache et de lecture de cache
• Mode hors ligne: utilisez --offline pour utiliser les données de tarification pré-mises en cache sans connexion réseau (modèles Claude uniquement)

⚡ Surveillance en temps réel

• Tableau de bord d'utilisation en temps réel
• Surveillance en temps réel: ccusage blocks --live

Installation et utilisation

Démarrage rapide (sans installation)

Étant donné la taille très réduite du paquet ccusage, il peut être exécuté directement sans installation:

# Avec bunx (recommandé, plus rapide)
bunx ccusage

# Avec npx
npx ccusage@latest

# Avec deno (avec indicateurs de sécurité)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

Installation globale

# Installation globale avec npm
npm install -g ccusage

# Installation globale avec bun
bun install -g ccusage

# Puis exécutez
ccusage

Environnement de développement

# Cloner le dépôt
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Installer les dépendances
bun install

# Exécuter l'outil
bun run report [subcommand] [options]

Utilisation de base

Rapport quotidien

# Afficher toute l'utilisation quotidienne
ccusage daily

# Filtrer par plage de dates
ccusage daily --since 20250525 --until 20250530

# Utiliser un répertoire de données Claude personnalisé
ccusage daily --path /custom/path/to/.claude

# Sortie au format JSON
ccusage daily --json

# Répartition des coûts par modèle
ccusage daily --breakdown

# Utiliser le fuseau horaire UTC
ccusage daily --timezone UTC

# Utiliser la localisation japonaise
ccusage daily --locale ja-JP

Analyse de projet

# Regrouper par projet/instance
ccusage daily --instances

# Filtrer sur un projet spécifique
ccusage daily --project myproject

# Utilisation combinée
ccusage daily --instances --project myproject --json

Rapport de session

# Afficher toutes les sessions
ccusage session

# Filtrer les sessions par date de dernière activité
ccusage session --since 20250525

# Filtres combinés
ccusage session --since 20250525 --until 20250530 --path /custom/path

# Sortie au format JSON
ccusage session --json

Surveillance en temps réel

# Tableau de bord d'utilisation en temps réel
ccusage blocks --live

# Fenêtre de facturation de 5 heures
ccusage blocks

# Ligne d'état (Bêta)
ccusage statusline

Mode compact

# Forcer le mode tableau compact
ccusage --compact

# Rapport mensuel compact
ccusage monthly --compact

Options de commande

Toutes les commandes prennent en charge les options suivantes:

• -s, --since <date>: Filtrer à partir de la date (format AAAA MM JJ)
• -u, --until <date>: Filtrer jusqu'à la date (format AAAA MM JJ)
• -p, --path <path>: Chemin personnalisé pour le répertoire de données Claude (par défaut: ~/.claude)
• -j, --json: Afficher les résultats au format JSON plutôt qu'en tableau
• -h, --help: Afficher l'aide
• -v, --version: Afficher la version

Exemples de sortie

Sortie du rapport quotidien

╭──────────────────────────────────────────╮
│                                          │
│ 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    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

Sortie du rapport de session

╭───────────────────────────────────────────────╮
│                                               │
│ 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    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

Architecture technique

Exigences de dépendance

• Environnement d'exécution Bun
• Fichiers d'historique d'utilisation de Claude Code (~/.claude/projects/**/*.jsonl)

Structure du projet

ccusage/
├── commands/
│   ├── daily.ts        # Commande de rapport quotidien
│   └── session.ts      # Commande de rapport de session
├── data-loader.ts      # Logique de chargement des données JSONL
├── index.ts           # Point d'entrée CLI
├── logger.ts          # Configuration du journal
├── utils.ts           # Utilitaires partagés
└── package.json

Développement et tests

# Exécuter les tests
bun test

# Vérification des types
bun run typecheck

# Linting du code
bun run lint

# Formater le code
bun run format

Fonctionnalités d'intégration

🔌 Intégration MCP

Serveur de protocole de contexte de modèle intégré pour l'intégration avec d'autres outils

Résumé

ccusage est un outil CLI puissant et facile à utiliser, spécialement conçu pour les utilisateurs de Claude Code, afin d'analyser et de suivre l'utilisation des jetons et les coûts associés. Sa conception légère, son riche ensemble de fonctionnalités et sa sortie esthétique en font un choix idéal pour les développeurs souhaitant optimiser leur utilisation de Claude Code et gérer leurs coûts.