Vous travaillez deux heures sur Claude Code, vous êtes en plein milieu d'un chantier, et le message tombe : limite atteinte, revenez dans cinq heures. La plupart des gens y voient un problème de quota. Vous avez surtout consommé votre fenêtre de contexte sans jamais la voir.
La status line de Claude Code est une barre d'information en bas de votre terminal, visible à chaque message. Elle affiche votre modèle, votre branche git, le coût de la session, et le pourcentage de contexte consommé. C'est le retour d'information qui manque par défaut.
Ce guide couvre l'installation, les données affichables, la personnalisation et le dépannage. Vous n'avez rien à coder.
✅ Ce que vous allez découvrir dans ce guide Status line Claude Code :
- Ce qu'est la status line : une barre permanente en bas du terminal, et où elle fonctionne.
- Pourquoi votre contexte décide de votre limite : le mécanisme des tokens et de l'historique de conversation.
- Comment ça marche : Claude Code envoie du JSON à un script, le script imprime du texte.
- Installation : trois méthodes selon votre niveau, de la commande automatique au fichier clé en main.
- Des exemples de scripts prêts à copier, du minimal au complet.
- Les données disponibles : modèle, coût, contexte, git, limites de débit, worktree.
- Lire votre statusline : ce que chaque bloc affiche et à quel seuil réagir.
- Personnalisation : fichier de configuration, seuils, et ccstatusline pour repartir de zéro.
- Dépannage : les cinq cas qui font qu'elle ne s'affiche pas.
Qu'est-ce que la status line de Claude Code ?
La status line est une barre personnalisable en bas de Claude Code qui exécute le script shell de votre choix. Claude Code lui envoie les données de la session au format JSON, le script imprime ce qu'il veut, et Claude Code affiche le résultat. Elle apparaît sur sa propre ligne, au-dessus des badges intégrés, sans les remplacer.
Elle tourne en local et ne consomme aucun token API. Elle se masque temporairement pendant certaines interactions : suggestions d'autocomplétion, menu d'aide, demandes de permission.
Ce que Claude Code affiche par défaut
Au premier lancement, vous n'avez quasiment rien en bas de votre terminal. Au mieux le nom du dossier courant. Vous pouvez taper /context pour ouvrir le panneau Context usage et voir où vous en êtes, mais c'est ponctuel : il faut penser à le lancer, lire le tableau, puis reprendre votre travail. La barre, elle, reste sous vos yeux à chaque message.
CLI, application desktop : où ça fonctionne ?
La barre est une fonction du terminal. Vous en profitez dans votre terminal système, dans le terminal intégré de VS Code ou dans JetBrains. L'application desktop seule ne l'affiche pas : vous y avez la commande /context, plus limitée. Mac, Windows et Linux fonctionnent de la même manière, avec une réserve sur Windows détaillée plus bas.
Pourquoi votre contexte décide de votre limite ?
Un token est un fragment de texte. Vos messages sont découpés en tokens en entrée, les réponses de Claude en tokens en sortie. Les deux remplissent votre limite. Jusque-là, rien de surprenant.
Le mécanisme qui coûte cher est ailleurs. À chaque message, Claude ne reçoit pas seulement votre dernière phrase : il reçoit toute la conversation depuis le début. Plus l'échange s'allonge, plus chaque nouveau message pèse lourd. L'utilisation de la fenêtre de contexte augmente, la qualité des réponses baisse, et vous atteignez votre plafond sans avoir vu la progression.
La fenêtre fait 200 000 tokens par défaut, ou 1 000 000 sur les modèles à contexte étendu. Le champ used_percentage calcule le pourcentage à partir des tokens d'entrée seuls, cache compris. C'est ce chiffre que la barre affiche en permanence.
À retenir : le guide d'installation de Kaio retient un repère pratique de 40 %. Au-delà, la qualité se dégrade suffisamment pour justifier un /compact. À 80 %, mieux vaut repartir sur une nouvelle conversation avec /clear. Ce sont des seuils d'usage observés, pas des valeurs publiées par Anthropic.
Comment fonctionne la statusline : le script et le JSON
Claude Code exécute votre script et lui envoie un objet JSON sur l'entrée standard. Le script lit ce JSON, extrait ce qui l'intéresse, et imprime du texte sur la sortie standard. Tout ce qui est imprimé s'affiche. Chaque instruction echo ou print crée une ligne supplémentaire, ce qui permet des affichages sur deux lignes.
Un script local branché sur les données de la session, c'est une pièce du harness d'un agent, l'outillage qui entoure le modèle et lui fournit son contexte.
Le script peut renvoyer des couleurs via les codes d'échappement ANSI, et des liens cliquables via les séquences OSC 8, à condition que votre terminal les supporte. iTerm2, Kitty et WezTerm les gèrent. Terminal.app sur macOS, non.
Le JSON que reçoit votre script
Voici une version réduite de ce que Claude Code envoie à chaque mise à jour. L'objet complet compte une trentaine de champs.
{
"session_id": "abc123",
"model": {
"id": "claude-opus-5",
"display_name": "Opus"
},
"workspace": {
"current_dir": "/Users/vous/projets/youno",
"repo": { "host": "github.com", "name": "youno-app" }
},
"cost": {
"total_cost_usd": 0.42,
"total_lines_added": 156,
"total_lines_removed": 23
},
"context_window": {
"used_percentage": 18,
"context_window_size": 200000
}
}L'objet workspace.repo n'apparaît que dans un dépôt git avec un remote origin configuré. Le bloc rate_limits n'existe que pour les abonnés Claude.ai Pro et Max, après la première réponse API de la session.
Quand la statusline se met à jour ?
Le script tourne une première fois au démarrage de la session, y compris quand vous la reprenez. Ensuite il se relance à l'arrivée d'un nouveau message de Claude, à la fin d'un /compact, au changement de mode de permission, et au basculement du mode vim. Les mises à jour sont regroupées toutes les 300 millisecondes pour éviter les rafales.
Si vous affichez une horloge ou des données qui bougent pendant que la session est inactive, ajoutez le champ refreshInterval à votre configuration. Il relance la commande toutes les N secondes, avec un minimum de 1.
Installer et configurer votre status line Claude Code
Trois méthodes, de la plus rapide à la plus complète.
La commande /statusline
Claude Code embarque une commande dédiée qui accepte des instructions en langage naturel. Vous décrivez ce que vous voulez voir, il génère le script dans ~/.claude/, met à jour vos paramètres et branche le tout. Vous pouvez aussi simplement demander à Claude de vous la configurer, il utilisera cette commande.
/statusline show model name and context percentage with a progress barAcceptez les demandes de modification de fichier s'il vous en demande. Pour retirer la barre, relancez /statusline en demandant de la supprimer.
La configuration manuelle dans settings.json
Ajoutez un champ statusLine dans ~/.claude/settings.json pour tous vos projets, ou dans les paramètres du projet pour une portée limitée. Le type doit valoir command, et command pointe vers un chemin de script ou une commande en ligne.
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}Le champ padding ajoute un espacement horizontal en caractères, par défaut 0. Rendez ensuite votre script exécutable avec chmod +x. Les exemples en bash de la documentation utilisent jq, un analyseur JSON en ligne de commande qu'il faut installer séparément. Python et Node.js analysent le JSON nativement.
L'installation clé en main
Pour éviter d'écrire le script vous-même, il existe un fichier de prompt à glisser dans Claude Code. Il vérifie les dépendances, crée les fichiers, branche la barre dans votre settings.json et lance un test. Vous redémarrez Claude Code, elle apparaît.
Trois prérequis : utiliser Claude Code en CLI, l'avoir lancé au moins une fois pour que le dossier ~/.claude/ existe, et disposer de Bun. Si Bun manque, le prompt l'installe.
Récupérez le prompt d'installation : le fichier que Kaio a créé. Vous le glissez dans Claude Code, il installe la statusline complète. Télécharger le prompt.
Exemples de scripts pour votre statusline
Deux scripts prêts à copier dans ~/.claude/statusline.sh. Les deux utilisent jq. Pensez au chmod +x avant de les brancher.
Le script minimal : modèle et barre de contexte
Il lit le JSON, extrait le nom du modèle et le pourcentage de contexte, puis construit une barre de dix blocs.
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"
echo "[$MODEL] $BAR $PCT%"Le // 0 fournit une valeur de repli quand le champ vaut null, ce qui arrive en début de session. Sans lui, la barre reste vide.
Le script complet : git, coût et répertoire
Celui-ci ajoute le nom du dépôt, la branche git courante et le coût de la session.
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
REPO=$(echo "$input" | jq -r '.workspace.repo.name // empty')
BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=$(git branch --show-current 2>/dev/null)
echo "[$MODEL] ${REPO:-${DIR##*/}} ${BRANCH:+| $BRANCH} | $(printf '$%.2f' "$COST")"Le test git rev-parse évite les erreurs hors dépôt git. Pour afficher la taille du terminal, lisez les variables COLUMNS et LINES : Claude Code les définit avant d'exécuter le script, et tput cols ne fonctionne pas depuis l'intérieur. Cette fonctionnalité demande Claude Code v2.1.153 ou ultérieur.
Si vous découvrez l'outil, on a détaillé ailleurs Claude Code appliqué aux workflows marketing.
Quelles données afficher dans votre statusline ?
Claude Code envoie une trentaine de champs (fields). Voici ceux qui servent réellement au quotidien.
| Champ JSON | Ce qu'il affiche | Bon à savoir |
|---|---|---|
| model.display_name | Le nom du modèle en cours | Utile quand vous alternez entre modèles |
| context_window.used_percentage | Pourcentage de fenêtre consommée | Peut être null en début de session |
| cost.total_cost_usd | Coût de la session, ou session cost | Calculé côté client, remis à zéro par /clear |
| cost.total_lines_added | Lignes de code ajoutées | Existe aussi en version supprimées |
| workspace.current_dir | Répertoire de travail courant | Préféré à cwd, qui contient la même valeur |
| workspace.repo.name | Nom du dépôt, ou repo | Absent hors dépôt git avec remote origin |
| rate_limits.five_hour | Pourcentage de limite 5 h consommée | Abonnés Claude.ai Pro et Max uniquement |
| effort.level | Niveau d'effort, ou effort level | Absent si le modèle ne gère pas ce paramètre |
| prompt_id | Identifiant du prompt en cours | Demande Claude Code v2.1.196 ou ultérieur |
| worktree.name | Nom du worktree actif | Présent uniquement en session --worktree |
Plusieurs champs peuvent être absents ou valoir null. current_usage est null avant le premier appel API et juste après un /compact. Gérez ces cas dans votre script avec une valeur de repli, par exemple // 0 avec jq.
Le réglage subagentStatusLine permet aussi de personnaliser l'affichage de chaque sous-agent dans le panneau sous le prompt. Les champs model et contextWindowSize par tâche demandent Claude Code v2.1.205 ou ultérieur.
Lire votre statusline
Une fois installée, la barre affiche de gauche à droite votre branche git, votre chemin, votre modèle, votre mode de permission, le contexte et le coût. Un astérisque après le nom de branche signale des modifications non commitées.
Le mode de permission se lit à l'icône.
| Mode | Ce que ça veut dire |
|---|---|
| auto | Claude agit sans vous demander |
| default | Claude demande avant chaque action |
| plan | Claude réfléchit sans exécuter |
| acceptEdits | Claude édite les fichiers sans confirmation |
| bypassPermissions | Tout est autorisé |
Le bloc de contexte est celui qui change votre façon de travailler. Il affiche un pourcentage et un nombre de tokens, avec un code couleur qui évolue selon le remplissage.
| Niveau de contexte | Ce que ça veut dire | Quoi faire |
|---|---|---|
| Moins de 40 % | Vous travaillez tranquille | Rien |
| 40 à 69 % | Ça se remplit, les performances baissent | Lancer /compact |
| 70 à 79 % | Qualité dégradée | /compact sans attendre |
| 80 % et plus | Critique | /clear ou nouvelle conversation |
En bref : le pourcentage de contexte est le seul chiffre qui vous fait gagner du temps d'utilisation sur la journée. Compacter à 40 % plutôt qu'à 80 % évite les réponses dégradées et repousse le moment où vous touchez votre plafond.
Personnaliser votre status line : configuration et seuils
Une fois la barre en place, quatre niveaux de personnalisation existent selon votre appétit pour le code.
Le fichier de configuration. Sur l'installation clé en main, tout l'affichage est piloté par ~/.claude/scripts/statusline/statusline.config.json. Vous y changez l'affichage sur une ou deux lignes avec oneLine, le caractère séparateur, la longueur et le style de la barre de progression, la taille de fenêtre de référence, et l'affichage du coût du jour. Vous sauvegardez, vous redémarrez Claude Code.
Les seuils. Ils se trouvent en haut de src/lib/render-pure.ts : STRESS_CONTEXT_THRESHOLD à 85, STRESS_FIVE_HOUR_THRESHOLD à 90, HIDE_COST_THRESHOLD à 0.10. Quand le contexte dépasse 85 % et la fenêtre 5 h dépasse 90 % en même temps, un avertissement rouge apparaît en début de ligne.
ccstatusline et les outils de la communauté
Si vous préférez construire votre barre sans toucher au code, ccstatusline est un outil open source hébergé sur GitHub qui ouvre un menu interactif dans le terminal avec npx ccstatusline@latest. Vous y choisissez les lignes, les couleurs, le powerline, les widgets et des commandes bash personnalisées. D'autres projets GitHub proposent des configurations prêtes à l'emploi avec leurs propres thèmes.
Windows : la réserve à connaître
Claude Code passe par Git Bash quand il est installé, sinon par PowerShell. Git Bash traite les antislashs comme des caractères d'échappement : écrivez toujours vos chemins avec des slashs avant, sinon la commande échoue sans message d'erreur visible. Pour lancer un script PowerShell, invoquez-le via powershell -NoProfile -File.
Windows Terminal ne fait pas partie de la liste de détection automatique des hyperliens. Si vos liens s'affichent sans être cliquables, lancez Claude Code avec la variable FORCE_HYPERLINK à 1.
Cette logique de configuration une fois pour toutes est celle qu'on applique aux systèmes GTM. C'est aussi ce qui structure notre travail d'agence CRM pour SaaS B2B : ce qui est documenté et versionné tourne sans dépendre de personne. C'est le même réflexe que nos équipes locales appliquent quand elles reprennent un CRM existant, documenter d'abord et automatiser ensuite.
Dépannage : quand la statusline ne s'affiche pas
Cinq causes reviennent systématiquement.
Le script n'est pas exécutable. Lancez chmod +x sur votre fichier. Vérifiez ensuite qu'il écrit bien sur la sortie standard et pas sur la sortie d'erreur, et exécutez-le à la main pour confirmer qu'il produit quelque chose. Un script qui sort en code non nul ou qui n'imprime rien laisse la barre vide.
La confiance de l'espace de travail n'est pas accordée. Comme statusLine exécute une commande shell, elle demande la même validation que les hooks. Sans acceptation de la boîte de dialogue, la barre reste blanche. Dans le même esprit, si disableAllHooks vaut true dans vos paramètres, elle est désactivée avec le reste.
Les valeurs affichent des tirets ou du vide. Les champs peuvent valoir null avant la fin du premier appel API. Ajoutez des valeurs de repli dans votre script.
Une erreur rouge apparaît dans la barre. Sur l'installation clé en main, la dépendance manque : allez dans ~/.claude/scripts/statusline et lancez bun install. Si le terminal répond que la commande bun est introuvable, installez Bun puis ouvrez un nouveau terminal.
Pour aller plus loin, claude --debug enregistre le code de sortie et la sortie d'erreur de la première exécution de la session.
Important : un script lent bloque l'affichage jusqu'à ce qu'il se termine. Si vous appelez git status dans un gros dépôt, mettez le résultat en cache dans un fichier temporaire nommé d'après le session_id, qui reste stable sur toute la session.
Conclusion
La barre de Claude Code prend deux minutes à installer et vous donne le seul chiffre qui compte vraiment au quotidien : votre pourcentage de contexte. Compactez à 40 %, repartez à zéro à 80 %, et vous arrêterez de découvrir votre limite au pire moment.
Récupérez le prompt d'installation, glissez-le dans Claude Code, redémarrez. C'est tout ce qu'il y a à faire. La même discipline s'applique à un CRM : nos spécialistes terrain font ce travail chez des SaaS B2B toute l'année.
