Claude Code Statusline : Personnaliser la Barre de Statut du Terminal (2026)

Claude Code Statusline : la barre de statut qui transforme votre terminal en cockpit

La statusline de Claude Code est cette petite barre discrète, en bas de votre terminal, qui peut devenir le tableau de bord le plus utile de votre journée de développeur. Par défaut, elle affiche peu de chose. Mais une fois personnalisée, elle vous montre en permanence le modèle actif, le pourcentage de fenêtre de contexte consommée, le coût de la session, la branche git, le nombre de lignes modifiées — bref, tout ce que vous deviez auparavant aller chercher à la main.

Concrètement, la statusline Claude Code est un script shell que vous configurez une fois et qui s'exécute à chaque mise à jour de la session. Claude Code lui envoie un objet JSON complet via l'entrée standard (stdin), votre script en extrait ce qui vous intéresse, et le texte qu'il affiche apparaît instantanément en bas de l'écran. C'est simple, rapide, et terriblement efficace pour garder un œil sur ce qui compte.

Dans ce guide tutoriel en français, vous allez apprendre à mettre en place une barre de statut en moins de cinq minutes, à comprendre tous les champs JSON disponibles, à écrire votre propre script bash avec une barre de progression colorée, et à éviter les pièges classiques (script qui ne s'affiche pas, permissions, performances).

Sommaire

Qu'est-ce que la statusline de Claude Code ?<a id="quest-ce-que-statusline"></a>

La statusline (barre de statut) est une ligne personnalisable affichée en bas de l'interface Claude Code. Elle exécute n'importe quel script shell de votre choix et affiche ce que ce script imprime sur la sortie standard. Le mécanisme est volontairement minimaliste : Claude Code envoie les données de session au format JSON, votre script les lit, les transforme, et renvoie une chaîne de texte.

Elle est particulièrement utile quand vous voulez :

Comment circulent les données

Le flux est le suivant : à chaque événement (nouveau message de l'assistant, fin d'un /compact, changement de mode de permission, bascule du mode vim), Claude Code exécute votre script et lui transmet un objet JSON via stdin. Votre script lit ce JSON, extrait les champs voulus, et affiche le résultat. Les mises à jour sont « debouncées » à 300 ms : si plusieurs changements surviennent coup sur coup, le script ne tourne qu'une fois, une fois la situation stabilisée.

Cette logique de personnalisation rejoint celle des output styles pour personnaliser le comportement de l'agent : Claude Code est conçu pour être façonné à votre main, de l'apparence du terminal jusqu'au ton de ses réponses.

Méthode express : la commande /statusline<a id="commande-statusline"></a>

Le moyen le plus rapide d'obtenir une barre de statut est de laisser Claude Code l'écrire pour vous. La commande /statusline accepte des instructions en langage naturel décrivant ce que vous voulez afficher.

Dans votre session Claude Code, tapez par exemple :

/statusline affiche le nom du modèle et le pourcentage de contexte avec une barre de progression

Claude Code génère alors un fichier script dans ~/.claude/, le rend exécutable, et met à jour automatiquement votre fichier de paramètres. En quelques secondes, votre barre de statut est opérationnelle, sans une seule ligne de bash écrite à la main.

Vous pouvez raffiner par itérations : « ajoute la branche git en vert », « affiche aussi le coût de la session », « passe la barre sur deux lignes ». Et pour faire le ménage, /statusline delete (ou clear, remove it) supprime la configuration.

C'est l'approche idéale pour démarrer. Mais comprendre ce qui se passe sous le capot vous permettra d'aller beaucoup plus loin — c'est l'objet des sections suivantes.

Configuration manuelle dans settings.json<a id="configuration-manuelle"></a>

Si vous préférez le contrôle total, ajoutez un champ statusLine à vos paramètres utilisateur (~/.claude/settings.json) ou aux paramètres de projet (.claude/settings.json). Réglez type sur "command" et pointez command vers un script ou une commande inline :

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

Comme command s'exécute dans un shell, vous pouvez aussi passer une commande inline sans créer de fichier. Cet exemple utilise jq (un parseur JSON en ligne de commande) pour afficher le nom du modèle et le pourcentage de contexte :

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% contexte\"'"
  }
}

Le fichier settings.json est le même point d'entrée que celui qui pilote les hooks pour automatiser votre workflow. Si vous configurez déjà des hooks, ajouter une statusline n'est qu'un champ de plus dans le même fichier — pensez à versionner la version projet pour la partager avec votre équipe.

Tous les champs JSON disponibles<a id="champs-json"></a>

Voici le cœur du sujet. À chaque exécution, votre script reçoit un objet JSON riche. Voici les champs les plus utiles :

Certains champs n'apparaissent que dans certaines conditions : workspace.repo seulement dans un dépôt git avec remote origin, effort seulement si le modèle supporte le paramètre d'effort, vim seulement si le mode vim est actif, rate_limits seulement pour les abonnés Claude.ai (Pro/Max). D'autres peuvent être null en début de session (used_percentage avant le premier appel API). Règle d'or : utilisez toujours un fallback du type // 0 ou // empty dans vos requêtes jq.

Le champ context_window.used_percentage est le plus précieux au quotidien. Pour bien comprendre pourquoi surveiller ce pourcentage change tout, lisez notre guide sur la gestion du contexte, le compact et le context rot : une barre de statut bien réglée vous évite de laisser la fenêtre se dégrader silencieusement.

Écrire son propre script bash pas à pas<a id="script-bash"></a>

Passons à la pratique. Voici un script complet qui affiche le modèle et une barre de progression du contexte sur dix caractères, avec des blocs pleins (▓) et vides (░).

Créez le fichier ~/.claude/statusline.sh :

#!/bin/bash
# Lit tout stdin dans une variable
input=$(cat)

# Extrait les champs avec jq, "// 0" gère les valeurs nulles
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Construit la barre de progression
BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

echo "[$MODEL] $BAR $PCT% contexte"

Rendez-le exécutable — étape cruciale, souvent oubliée :

chmod +x ~/.claude/statusline.sh

Puis pointez votre settings.json vers ce script (voir la section configuration manuelle). Le résultat affiche par exemple : [Opus] ▓▓▓░░░░░░░ 32% contexte.

Ajouter la couleur et le coût

Pour aller plus loin, enrichissons avec la branche git, le coût et des couleurs ANSI (\033[32m pour le vert, \033[0m pour réinitialiser) :

#!/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')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

GREEN='\033[32m'
CYAN='\033[36m'
RESET='\033[0m'

BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
[ -n "$BRANCH" ] && GIT=" ${GREEN}⎇ $BRANCH${RESET}" || GIT=""

printf "${CYAN}[%s]${RESET}%s | %s%% ctx | $%.3f\n" "$MODEL" "$GIT" "$PCT" "$COST"

Ce script affiche le modèle en cyan, la branche git en vert, le pourcentage de contexte et le coût de la session. Suivre ce coût en direct est une excellente habitude FinOps : nos stratégies pour réduire la facture Claude Code deviennent bien plus concrètes quand le montant s'affiche en permanence sous vos yeux.

Vidéo : maîtriser l'environnement Claude Code

La statusline n'est qu'une pièce d'un environnement Claude Code bien réglé (settings, hooks, MCP, sous-agents). Cette session de la chaîne Sophiene IA fait le tour complet de l'outil en 2026 et resitue la personnalisation du terminal dans le tableau d'ensemble :

Options avancées : refreshInterval, padding, multi-lignes<a id="options-avancees"></a>

Trois options de configuration méritent votre attention.

refreshInterval : rafraîchir sur un timer

Par défaut, la statusline ne se met à jour que sur événement. Mais si vous affichez une horloge, ou si des sous-agents en arrière-plan modifient l'état git pendant que la session principale est inactive, ces déclencheurs restent muets. Le champ refreshInterval (minimum 1 seconde) ré-exécute votre commande à intervalle fixe :

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

Cette gestion d'état partagé entre une session principale et des agents secondaires est au cœur des workflows multi-agents. Si vous orchestrez des flottes d'agents — notamment des agents IA open-source et auto-hébergés que la formation OpenClaw détaille en profondeur — un refreshInterval court garde votre barre synchronisée avec ce que font les agents en tâche de fond.

padding et hideVimModeIndicator

Le champ padding (défaut 0) ajoute une marge horizontale en caractères. Le champ hideVimModeIndicator, mis à true, supprime le texte intégré -- INSERT -- quand votre script affiche déjà vim.mode lui-même, pour éviter le doublon.

Statusline sur plusieurs lignes

Votre script peut imprimer plusieurs lignes : Claude Code affiche chaque echo sur sa propre ligne. Un pattern courant met la branche git et le répertoire sur la première ligne, et une barre de contexte colorée avec le coût sur la seconde. Pratique quand vous travaillez sur plusieurs branches en parallèle — un usage qui se marie parfaitement avec les sessions parallèles via git worktree, où distinguer visuellement chaque worktree fait gagner un temps précieux.

Astuce v2.1.153+ : depuis l'intérieur du script, `tput cols` ne fonctionne pas (Claude Code capture la sortie). Lisez plutôt les variables d'environnement `COLUMNS` et `LINES` que Claude Code positionne avant chaque exécution.

Dépannage : ma statusline ne s'affiche pas<a id="depannage"></a>

Quelques causes récurrentes quand rien n'apparaît :

Une fois ces points vérifiés, votre barre de statut devrait apparaître instantanément. La personnalisation de l'environnement fait partie des réflexes qui séparent un utilisateur occasionnel d'un développeur productif — exactement ce que couvre la formation Claude Code complète, qui transforme l'outil en véritable méthode de travail professionnelle, des settings jusqu'aux workflows multi-agents, avec des projets pratiques mis à jour à chaque release d'Anthropic.

FAQ : questions fréquentes sur la statusline Claude Code<a id="faq"></a>

Comment ajouter une statusline dans Claude Code ?

Le plus simple est de taper /statusline suivi d'une description en langage naturel (ex. « affiche le modèle et le pourcentage de contexte »). Claude Code génère le script et met à jour vos paramètres automatiquement. Pour un contrôle total, ajoutez manuellement un champ statusLine de type "command" dans ~/.claude/settings.json pointant vers votre script shell.

Pourquoi ma statusline ne s'affiche-t-elle pas ?

Dans 90 % des cas, le script n'a pas la permission d'exécution : lancez chmod +x ~/.claude/statusline.sh. Vérifiez aussi que jq est installé (pour les scripts bash), que le chemin dans command est correct, et testez le script à la main en lui injectant un JSON d'exemple via un pipe pour repérer une erreur éventuelle.

Quels champs puis-je afficher dans la barre de statut ?

Claude Code envoie un JSON riche : modèle (model.display_name), répertoire et branche (workspace.*), coût (cost.total_cost_usd), contexte (context_window.used_percentage), niveau d'effort (effort.level), output style, nombre de lignes modifiées, version, et plus encore. Certains champs n'apparaissent que sous conditions (dépôt git, mode vim, abonnement Claude.ai), pensez à gérer leur absence avec un fallback // 0 ou // empty.

Comment afficher le pourcentage de contexte avec une barre de progression ?

Extrayez .context_window.used_percentage avec jq, calculez le nombre de blocs pleins sur une largeur fixe (par exemple 10 caractères), puis construisez une chaîne avec des blocs ▓ pour la partie remplie et ░ pour le reste. Le script complet est donné dans la section « Écrire son propre script bash » de ce guide.

La statusline ralentit-elle Claude Code ?

Non, si le script est rapide. Les mises à jour sont debouncées à 300 ms et, si une nouvelle mise à jour arrive pendant l'exécution, celle en cours est annulée. Évitez les appels réseau et les commandes lourdes dans le script. Pour des données basées sur le temps, utilisez refreshInterval plutôt que de relancer une logique coûteuse à chaque événement.

Peut-on avoir une statusline différente par projet ?

Oui. Le champ statusLine peut vivre dans les paramètres de projet (.claude/settings.json à la racine du dépôt) plutôt que dans les paramètres utilisateur globaux. Versionnez ce fichier et toute l'équipe partagera la même barre de statut, par exemple avec des couleurs ou des indicateurs propres au projet.

Pour aller plus loin