Come Monitorare l'Utilizzo del Codice di Claude in Tempo Reale con Python

Il progetto Claude-Code-Usage-Monitor offre diverse modalità di installazione, tra cui l'installazione moderna con uv (raccomandata), l'installazione con pip e l'utilizzo di altri package manager come pipx e conda.

Installazione Moderna con uv (Raccomandata)

uv è uno strumento moderno che semplifica l'installazione e la gestione dei pacchetti Python, creando ambienti isolati automaticamente e risolvendo problemi di compatibilità. Per installare uv, segui questi passaggi:

curl -LsSf https://astral.sh/uv/install.sh | sh

Dopo l'installazione di uv, riavvia il terminale e procedi con l'installazione di Claude-Code-Usage-Monitor:

uv tool install claude-monitor

Per eseguire il monitor da qualsiasi directory, usa il comando:

claude-monitor

Installazione con pip

Se preferisci utilizzare pip, puoi installare Claude-Code-Usage-Monitor con il seguente comando:

pip install claude-monitor

Se il comando claude-monitor non viene riconosciuto, aggiungi ~/.local/bin al tuo PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Per eseguire il monitor, usa il comando:

claude-monitor

Installazione con Altri Package Manager

pipx (Ambienti Isolati)

pipx install claude-monitor

Per eseguire il monitor:

claude-monitor

conda/mamba

pip install claude-monitor

Per eseguire il monitor:

claude-monitor

Dopo l'installazione, è possibile configurare il monitor per adattarlo alle proprie esigenze. Ecco alcune opzioni di configurazione:

Utilizzo Base

Per avviare il monitor con la configurazione predefinita (piano Pro con limite di circa 7.000 token), usa il comando:

claude-monitor

Per uscire dal monitor, premi Ctrl+C.

Specificare il Piano

È possibile specificare il piano di utilizzo tramite l'opzione --plan:

• pro: Piano Pro (circa 7.000 token) - Predefinito
• max5: Piano Max5 (circa 35.000 token)
• max20: Piano Max20 (circa 140.000 token)
• custom_max: Auto-rileva il limite massimo dalle sessioni precedenti

Esempio:

claude-monitor --plan max5

Configurare gli Orari di Reset Personalizzati

È possibile impostare un orario di reset personalizzato tramite l'opzione --reset-hour:

claude-monitor --reset-hour 3

Questo imposta l'orario di reset alle 3:00 AM.

Configurare il Fuso Orario

Il fuso orario predefinito è Europe/Warsaw. È possibile modificarlo tramite l'opzione --timezone:

claude-monitor --timezone US/Eastern

Il monitoraggio fornisce diverse metriche in tempo reale per tenere traccia dell'utilizzo del codice con Claude:

• Real-time Monitoring: Aggiornamenti ogni 3 secondi con un refresh fluido.
• Visual Progress Bars: Barre di progresso colorate per token e tempo.
• Smart Predictions: Calcola quando i token si esauriranno in base al burn rate corrente.
• Auto-Detection: Passa automaticamente al limite massimo personalizzato quando il limite Pro viene superato.
• Warning System: Avvisi quando i token superano i limiti o si esauriscono prima del reset della sessione.

Come Funzionano le Sessioni di Claude

Claude Code opera su un sistema a finestra di sessione mobile di 5 ore:

1. Inizio Sessione: Inizia con il tuo primo messaggio a Claude.
2. Durata Sessione: Dura esattamente 5 ore dal primo messaggio.
3. Limiti Token: Si applicano all'interno di ogni finestra di sessione di 5 ore.
4. Sessioni Multiple: Puoi avere diverse sessioni attive contemporaneamente.
5. Finestre Mobili: Nuove sessioni possono iniziare mentre altre sono ancora attive.

Calcolo del Burn Rate

Il monitor calcola il burn rate, ovvero la velocità con cui consumi i token, analizzando il tuo utilizzo recente. In termini semplici, tiene traccia di quanti token consumi ogni minuto e, basandosi su questo, stima quando raggiungerai il tuo limite. Questo ti permette di prevedere se dovrai rallentare l'utilizzo o se sei al sicuro fino al prossimo reset.

1. Raccolta Dati: Raccoglie l'utilizzo dei token da tutte le sessioni nell'ultima ora.
2. Analisi Pattern: Identifica le tendenze di consumo tra le sessioni sovrapposte.
3. Tracciamento Velocità: Calcola i token consumati al minuto.
4. Motore di Predizione: Stima quando i token della sessione corrente si esauriranno.
5. Aggiornamenti in Tempo Reale: Regola le previsioni man mano che i pattern di utilizzo cambiano.

Problemi di Installazione

Errore "externally-managed-environment"

Su distribuzioni Linux moderne (Ubuntu 23.04+, Debian 12+, Fedora 38+), potresti incontrare questo errore. Le soluzioni sono, in ordine di preferenza:

1. Usare uv (Raccomandato)
2. Usare pipx (Ambiente Isolato)
3. Usare un ambiente virtuale
4. Forzare l'installazione (Non Raccomandato)

Esempio Pratico: Se stai usando Ubuntu 23.04 e ricevi questo errore, prova prima con uv. Se ancora non funziona, crea un ambiente virtuale con python3 -m venv .venv, attivalo con source .venv/bin/activate, e poi installa claude-monitor con pip install claude-monitor.

Comando Non Trovato Dopo l'Installazione con pip

Se il comando claude-monitor non viene trovato dopo l'installazione con pip:

1. Controlla se è un problema di PATH
2. Aggiungi ~/.local/bin a PATH
3. Verifica la posizione di installazione
4. Esegui direttamente con Python

Esempio Pratico: Dopo aver installato con pip, prova ad eseguire which claude-monitor. Se non restituisce nulla, apri il file ~/.bashrc (o ~/.zshrc se usi Zsh) e aggiungi la riga export PATH="$HOME/.local/bin:$PATH". Salva il file e poi esegui source ~/.bashrc (o source ~/.zshrc) per aggiornare il tuo ambiente.

Problemi di Runtime

Nessuna sessione attiva trovata

Se incontri l'errore Nessuna sessione attiva trovata, segui questi passaggi:

1. Test Iniziale: Avvia Claude Code e invia almeno due messaggi.
2. Percorso di Configurazione: Considera di specificare un percorso di configurazione personalizzato.

Esempio Pratico: Assicurati di aver effettivamente interagito con Claude tramite l'API prima di avviare il monitor. Invia un paio di richieste di test e verifica che vengano elaborate correttamente. Se l'errore persiste, verifica che il monitor stia leggendo correttamente i dati della sessione; in rari casi, potrebbe essere necessario configurare manualmente il percorso ai file di sessione.

In questo articolo, abbiamo esplorato come monitorare l'utilizzo del codice di Claude in tempo reale con Python utilizzando il progetto Claude-Code-Usage-Monitor. Abbiamo coperto l'installazione, la configurazione, la comprensione delle metriche e la risoluzione dei problemi comuni. Con questo strumento, puoi ottimizzare i costi, gestire le limitazioni delle API AI in modo efficace e avere una visione chiara del tuo consumo di token.

Per approfondire, consulta la documentazione ufficiale di Claude e la documentazione delle API Anthropic.