Claude Code Statusline : surveiller ses rate limits en temps réel

Claude Code rate-limite ses utilisateurs. Pas brutalement — avec des quotas superposés : taille du contexte actif, quota de session, quota hebdomadaire, quotas par modèle. Le problème : aucune visibilité sans taper /usage dans l'interface, ce qui implique de sortir du flux de travail, lire un texte formaté, mémoriser les chiffres, et reprendre. Sur une session intense de développement, ça arrive souvent, et c'est toujours au mauvais moment.

L'idée de départ était simple : l'équivalent d'un tmux powerline, mais pour les quotas Claude Code. Une barre en bas de l'écran, toujours là, mise à jour en arrière-plan. Résultat : un script Bash, construit avec Claude Code lui-même lors d'une seule session, qui affiche les informations de claude code rate limit status en permanence sans jamais bloquer le terminal actif.

Ce que ça affiche

La barre ressemble à ça en pratique :

🌿 main │ 🤖 Sonnet 4.6 │ 🟢 Ctx ▓▓░░░░░░ 34% │ ⏳ 🟡 ▓▓▓░░░░░ 46% → 19h00 (3h20m) │ 📅 🟡 42% / Snt 🔴 59% ↻ lun 14h 🔄 5m

Chaque segment a sa fonction :

• 🌿 main — branche git courante du répertoire actif
• 🤖 Sonnet 4.6 — modèle actif dans la session Claude Code
• 🟢 Ctx ▓▓░░░░░░ 34% — pourcentage de la fenêtre de contexte consommé
• ⏳ 🟡 ▓▓▓░░░░░ 46% → 19h00 (3h20m) — quota de session : usage actuel, heure de reset, temps restant avant ce reset
• 📅 🟡 42% / Snt 🔴 59% ↻ lun 14h — quota hebdomadaire global et quota hebdomadaire Sonnet spécifiquement, avec le jour et l'heure de reset
• 🔄 5m — temps depuis le dernier refresh des données

Le code couleur suit une règle simple : vert en dessous de 50%, jaune entre 50 et 80%, rouge au-delà. C'est suffisant pour savoir d'un coup d'œil si on peut se permettre une longue refactorisation ou s'il vaut mieux finir la tâche en cours et attendre le reset.

L'architecture : deux chemins, une seule commande

La partie intéressante. Claude Code accepte une clé statusLine dans ~/.claude/settings.json :

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/hooks/statusline.sh"
  }
}

Claude Code appelle cette commande à chaque refresh de la status bar et affiche ce que le script écrit sur stdout. La contrainte : ce chemin doit être rapide. Un appel réseau synchrone ici gèle l'interface. La solution est un split en deux chemins distincts.

Le chemin rapide (appelé à chaque refresh) : le script lit ~/.claude/usage-exact.json et formate les données en texte. C'est une lecture de fichier locale — quasi-instantané, pas de latence perceptible.

Le chemin lent (toutes les 10 minutes, en arrière-plan) : le script lance une session tmux détachée nommée claude-usage-bg, ouvre une nouvelle instance Claude Code à l'intérieur, exécute /usage automatiquement, parse la sortie texte par regex, et écrit le résultat dans ~/.claude/usage-exact.json.

Pourquoi tmux ? Claude Code est un CLI interactif, pas une API scriptable. Il n'existe pas de mode --quiet ou --json pour récupérer les données d'usage programmatiquement. La seule façon de spawner une nouvelle instance sans bloquer la session active est de l'isoler dans une session tmux détachée. Un fichier de lock à /tmp/claude-usage-refresh.lock évite les scrapers en doublon. Un timeout de 120 secondes tue les processus zombies si quelque chose se passe mal.

C'est le pattern cache-first appliqué à une status bar : le rendu lit toujours depuis le cache, la mise à jour du cache se fait en dehors du chemin critique. Jamais bloquer sur un appel réseau ou un processus externe pour afficher une barre de statut.

Parser du texte avec des regex

Il n'existe pas d'API pour les données /usage de Claude Code. La sortie est du texte lisible par un humain, formaté pour un terminal. Donc on parse du texte avec des regex — pas élégant, mais c'est ce qu'on a.

La logique globale : capturer la sortie de /usage via tmux capture-pane, extraire les nombres et les horaires par pattern matching, convertir les heures de reset en timestamps. Un détail non documenté qui coûte du temps au débogage : Claude Code affiche les heures de reset dans le fuseau horaire local de la machine, sans l'indiquer explicitement. Le script détecte le timezone automatiquement depuis la sortie elle-même et ajuste le calcul du countdown en conséquence. Sans ça, le compteur est faux de l'offset UTC dès qu'on n'est pas en UTC.

L'autre détail réel : quand on automatise le CLI Claude Code, la première ouverture d'une nouvelle session affiche parfois un prompt de confiance ("Trust this directory ?") qui bloque l'exécution. Ce cas doit être géré explicitement dans le script — envoyer la réponse attendue via tmux send-keys avant d'envoyer la commande /usage. Ce genre de cas ne figure nulle part dans la documentation.

Installation

curl -fsSL https://raw.githubusercontent.com/ohugonnot/claude-code-statusline/main/install.sh | bash

L'installeur fait dans l'ordre :

1. Vérifie les dépendances : jq, tmux, python3
2. Propose de les installer via apt ou brew si manquantes
3. Copie le script dans ~/.claude/hooks/statusline.sh
4. Patche ~/.claude/settings.json de façon non-destructive avec jq — les clés existantes ne sont pas écrasées

L'intervalle de refresh est configurable : bash install.sh --refresh 300 pour une mise à jour toutes les 5 minutes au lieu de 10.

Ce qu'on a appris en le construisant

Claude Code est un outil pour humains. L'automatiser demande de gérer des prompts interactifs, des timeouts, des race conditions entre sessions. Ce n'est pas une API — c'est un CLI qui suppose un opérateur humain. Dès qu'on essaie de le scripter, on tombe sur des cas limites que rien dans la doc n'anticipe.

Le pattern cache-first est le seul viable pour une status bar. Toute architecture qui bloque le chemin de rendu sur un appel réseau ou un processus externe produit une interface gelée ou lente. Le cache local avec mise à jour asynchrone est la seule option qui reste réactive quelle que soit la latence du chemin lent.

Construire un outil Claude Code avec Claude Code teste ses propres limites. On a touché le rate limit plusieurs fois pendant le développement — ce qui est à la fois ironique et utile. Ça rend concret ce qu'on essaie de monitorer, et ça force à penser à l'expérience d'un utilisateur qui approche des quotas.

tmux comme bus d'isolation de processus : pas élégant, mais fiable. La solution propre serait une API. En l'absence d'API, on prend le bon outil pour le job réel — pas pour le job idéal. tmux isole un processus interactif, capture sa sortie, et le laisse s'exécuter en dehors du terminal actif. C'est exactement ce dont on avait besoin.

Conclusion

Le projet est open source, MIT, disponible sur github.com/ohugonnot/claude-code-statusline . Installation en une ligne. Si vous utilisez Claude Code intensivement, vous connaissez la frustration de tomber sur un quota sans l'avoir vu venir — en plein milieu d'une refactorisation, au moment où l'agent avait enfin compris le contexte. Ce script rend les limites visibles avant qu'elles soient atteintes. C'est tout ce qu'il fait, et c'est suffisant.