claude-monitor-usage 2.2.0

Real-time Claude Pro/Max usage monitor — tray icon, overlay widget, notifications, mini mode, sparklines

Claude Usage Monitor

Moniteur temps réel des limites d'utilisation Claude (Pro/Max) — tray icon dynamique, widget overlay always-on-top, notifications système.

Projet publié à titre de présentation et de consultation. Tous droits réservés. Aucune utilisation, reproduction, modification, redistribution ou exploitation commerciale n'est autorisée sans accord écrit préalable de l'auteur. Voir LICENSE.md.

Aperçu

Widget compact	Vue au survol	Mode mini

Popup (double-clic)	Tooltip systray	Menu tray

Pourquoi ?

• Libérez votre console : si vous affichiez vos quotas dans le terminal, cette appli remplace ça par un widget discret toujours visible — vous récupérez de l'espace dans votre fenêtre de travail.
• Gain de temps : plus besoin de chercher dans les menus Claude, d'ouvrir une page web ou de taper une commande pour connaître vos quotas restants. Un coup d'œil suffit.
• Anticipez les limites : notifications automatiques à 80% et 95%, estimation du temps restant avant d'atteindre la limite.

Fonctionnalités

• Tray icon dynamique : icône avec arc de progression coloré (style Claude, orange #D97744)
• Widget overlay : compact (160×76px), always-on-top, ne vole jamais le focus
• Tooltip au survol : countdown avant reset en temps réel
• Popup détaillé : barres de progression, sparklines 24h, infos abonnement
• Notifications système : alertes aux seuils configurables (80%, 95%)
• Historique : tendances d'utilisation sur 7 jours avec mini-graphiques
• Raccourci clavier : Ctrl+Shift+U pour toggle le widget overlay
• Multi-écran : détection automatique, positionnement libre avec drag & drop
• Multilingue : français, anglais, allemand, espagnol, portugais, italien (détection auto)
• Thèmes : sombre, clair, auto (suit le système)
• Exécutable Windows : .exe standalone, aucune installation requise

Plateformes supportées

Plateforme	Statut	Notes
Windows 10/11	✅ Testé	Exécutable .exe disponible
Linux (X11)	✅ Compatible	Nécessite libappindicator3
macOS	⚠️ Partiel	tkinter + pystray fonctionnels, non testé en production

Prérequis

• Claude Code installé et connecté (claude login)

Depuis les sources (développeurs)

• Python 3.12+
• uv (gestionnaire de paquets)

Linux uniquement

sudo apt install libappindicator3-1 gir1.2-appindicator3-0.1

Installation

Option 1 : Exécutable Windows (recommandé)

Télécharger claude-usage-monitor.exe depuis la page Releases et le lancer directement.

Option 2 : Depuis les sources

git clone https://github.com/audi63/claude-usage-monitor.git
cd claude-usage-monitor
uv sync

Utilisation

Exécutable

Double-cliquer sur claude-usage-monitor.exe. L'icône apparaît dans la barre système.

Depuis les sources

uv run claude-usage-monitor

Interactions

• Clic droit sur le tray icon → menu contextuel (rafraîchir, overlay, quitter…)
• Clic gauche sur le tray icon → popup détaillé
• Survol du widget overlay → vue étendue avec barres, countdowns, estimation et sparkline 6h
• Double-clic sur le widget overlay → popup complet avec sparkline 24h et infos abonnement
• Glisser-déposer le widget overlay → repositionner (fonctionne aussi en vue étendue)
• Ctrl+Shift+U → afficher/masquer le widget overlay

Configuration

Fichier optionnel ~/.claude/usage-monitor-config.json :

{
  "refresh_interval_seconds": 300,
  "notification_thresholds": [80, 95],
  "notifications_enabled": true,
  "notify_on_reset": true,
  "always_on_top": true,
  "widget_opacity": 0.95,
  "widget_position": {
    "x": null,
    "y": null,
    "preset": "top-right",
    "screen_index": 0
  },
  "theme": "dark",
  "language": "auto",
  "hotkey_toggle": "ctrl+shift+u",
  "history_retention_days": 7
}

Options de langue

Valeur	Langue
"auto"	Détection automatique (défaut)
"fr"	Français
"en"	English
"de"	Deutsch
"es"	Español
"pt"	Português
"it"	Italiano

Démarrage automatique

Windows

Copier claude-usage-monitor.exe (ou un raccourci) dans :

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\

Linux (systemd)

cp assets/claude-usage-monitor.service ~/.config/systemd/user/
systemctl --user enable claude-usage-monitor
systemctl --user start claude-usage-monitor

Build de l'exécutable

uv pip install pyinstaller
uv run python build.py

L'exécutable est généré dans dist/claude-usage-monitor.exe (~21 Mo).

Architecture technique

src/claude_usage_monitor/
├── main.py           # Point d'entrée, orchestration threads
├── api.py            # Client OAuth API (token refresh automatique)
├── cache.py          # Cache JSON pour affichage immédiat au démarrage
├── config.py         # Gestion configuration utilisateur
├── i18n.py           # Internationalisation (6 langues)
├── overlay.py        # Widget overlay always-on-top (Win32/X11)
├── popup.py          # Popup détaillé avec sparklines
├── tray.py           # Tray icon système (pystray)
├── icon_generator.py # Génération d'icônes dynamiques (Pillow)
├── notifications.py  # Notifications système aux seuils
├── history.py        # Historique d'utilisation (7 jours)
├── screens.py        # Détection multi-écran
├── hotkeys.py        # Raccourcis clavier globaux (pynput)
├── themes.py         # Thèmes sombre/clair/auto
└── utils.py          # Utilitaires (formatage, couleurs)

Threading

• Thread principal : tkinter mainloop() (UI)
• Thread pystray : tray icon système (daemon thread)
• Thread polling : appels API en arrière-plan (daemon)
• Communication inter-threads via root.after(0, callback)

Testeurs Linux et macOS recherchés

L'application a été développée et testée sous Windows 11 uniquement. Le code inclut des fallbacks pour Linux et macOS, mais ils n'ont pas été validés en conditions réelles.

Si vous utilisez Linux ou macOS, vos retours sont les bienvenus ! Consultez CONTRIBUTING.md pour la liste des points à tester et le format de signalement.

Dépannage

"Token expiré — relancer Claude Code" / données périmées

Le token OAuth dans ~/.claude/.credentials.json peut devenir révoqué ou rate-limité (problème connu Anthropic). Claude Code garde un token valide en mémoire mais ne le réécrit pas toujours sur disque.

Solution : ouvrir un terminal et lancer :

claude auth login

L'app détecte automatiquement le nouveau fichier credentials (vérification toutes les 5 secondes) et récupère les données immédiatement.

"API occupée — réessai auto…"

L'API /api/oauth/usage a un rate-limiting très agressif (problème connu, issues Anthropic #31637, #30930). L'app gère cela avec :

• Backoff progressif (jusqu'à 5 minutes entre les appels)
• Tentative de refresh du token OAuth au premier 429
• Affichage des dernières données connues avec indicateur de péremption (⏳)

Widget overlay tronqué au survol

Si la vue étendue au survol apparaît tronquée, c'est un conflit entre les styles Win32 et tkinter dans l'exe compilé. L'approche actuelle (destroy/recreate de la fenêtre) résout ce problème de manière fiable.

Notes techniques

Approche hover (destroy/recreate)

L'expansion du widget au survol détruit et recrée la fenêtre tkinter au lieu de redimensionner en place. C'est nécessaire car les styles Win32 WS_EX_LAYERED + WS_EX_TOOLWINDOW + overrideredirect rendent le resize via geometry() et MoveWindow() peu fiable dans un exe PyInstaller. La fenêtre est recréée à la position exacte avec la taille expanded, puis re-détruite/recréée au collapse.

Gestion des tokens OAuth

L'app surveille le fichier ~/.claude/.credentials.json (mtime) toutes les 5 secondes. Quand le fichier change (login, refresh par Claude Code), l'app :

1. Détecte le nouveau token (comparaison avec le précédent)
2. Réinitialise le backoff 429
3. Fait un appel API immédiat

Le User-Agent claude-code/2.0.31 est utilisé pour obtenir les vrais codes d'erreur de l'API (sans lui, les 403 "token revoked" sont masqués par des 429 génériques).

Source de données

Utilise l'API OAuth usage de Claude Code (GET https://api.anthropic.com/api/oauth/usage) avec le header anthropic-beta: oauth-2025-04-20. API non-officielle, peut changer sans préavis.

Le token OAuth est lu depuis ~/.claude/.credentials.json (partagé avec Claude Code) et rafraîchi automatiquement à expiration.

Licence

Tous droits réservés — voir LICENSE.md

Ce projet est publié à titre de présentation et de consultation uniquement. Aucune utilisation, reproduction, modification, redistribution ou exploitation commerciale n'est autorisée sans accord écrit préalable de l'auteur. Voir CONTRIBUTING.md et SECURITY.md.