Statusline Claude Code : configurez la vôtre avec /statusline (2026)
Transformez le bas de votre terminal en tableau de bord en direct — modèle, barre de fenêtre de contexte, branche git, dossier et coût. Douze étapes illustrées, de la commande /statusline intégrée à une barre colorée et soignée, sans oublier les correctifs quand elle refuse de s'afficher.
L'essentiel
- /statusline est intégré à Claude Code. Lancez-la, décrivez la barre souhaitée en une phrase, et un agent statusline-setup écrit le script et câble le bloc statusLine dans ~/.claude/settings.json à votre place.
- Sous Windows, l'agent propose trois voies : convertir votre profil PowerShell, pointer vers une config WSL ou Git Bash, ou partir sur une config par défaut affichant utilisateur, répertoire, modèle et usage du contexte.
- Le script lit un document JSON sur stdin — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd et d'autres — et tout ce qu'il affiche par echo devient votre barre. Couleurs ANSI et plusieurs lignes sont autorisées.
- Tout tourne en local et ne coûte aucun token. Les mises à jour se déclenchent sur les événements de session (ou toutes les N secondes avec refreshInterval), et /statusline clear supprime tout quand vous voulez repartir de zéro.
How to Set Up a Custom Status Line in Claude Code CLI to Track API Costs and Context Usage (2026)
Vidéo:ProgrammingKnowledge23:32
Claude Code最該裝的不是Skill，是這個腳本｜彩色進度條、費用、git 分支一眼看完
Vidéo:YAHA學堂8:44
Your Claude Code Terminal Should Look Like This (Status Line Setup)
Vidéo:Leon van Zyl9:02
How to Add a Custom Status Line in Claude Code on Windows 11 (Project-Level Setup)
Vidéo:Devtamin7:27
Status line — Claude Code documentation
Docs:code.claude.com
Les étapes 1 à 4 ont été enregistrées sous Windows PowerShell et les étapes 5 à 12 sur macOS ; les captures viennent exclusivement d'enregistrements d'écran propres — les images avec face-cam du créateur ou overlays incrustés ont été écartées.
Les astuces de configuration — indiquer son système d'exploitation, garder le script global et dans son propre fichier, la dépendance jq et l'astuce du fichier de debug — viennent des deux vidéos supplémentaires créditées ci-dessus. Les noms de champs et le comportement de rafraîchissement des sections approfondies suivent la documentation officielle de la ligne d'état.
Le pas à pas /statusline — 12 étapes illustrées
Lancez /statusline et laissez Claude câbler
- 1
Démarrez Claude Code dans votre terminal
Lancez claude dans PowerShell, Terminal ou n'importe quel shell. Une session toute neuve n'affiche que la boîte de bienvenue et une invite vide — la bande sous la zone de saisie, où vivra votre statusline, n'existe pas tant qu'aucun bloc statusLine n'a été ajouté à ~/.claude/settings.json.
Une session Claude Code v2.1.83 flambant neuve dans Windows PowerShell — boîte de bienvenue, invite vide, pas encore de ligne d'état.Voir à 0:22 - 2
Tapez la commande /statusline
Le menu des commandes slash la décrit sans détour : configurer l'interface de ligne d'état de Claude Code. Appuyez sur Entrée. Cette commande intégrée comprend le langage naturel, donc jamais besoin d'écrire un script à la main — même si vous restez libre de modifier ensuite tout ce qu'elle génère.
L'autocomplétion présente /statusline comme la commande qui configure l'interface de ligne d'état de Claude Code.Voir à 0:32 - 3
Répondez aux questions de l'agent de configuration
Un agent dédié statusline-setup prend la main. Sous Windows, il signale qu'aucune config de shell standard n'a été trouvée et propose trois voies : coller votre profil PS1 pour qu'il soit converti, pointer vers une config WSL ou Git Bash, ou opter pour une config par défaut affichant utilisateur, répertoire, modèle et usage du contexte. Les trois aboutissent au même bloc settings.json.
Les trois options Windows de l'agent : convertir un PS1, pointer vers une config personnalisée, ou partir d'une config par défaut sensée.Voir à 1:20 - 4
Vérifiez la config et le script écrits
Quand l'agent termine, il affiche un aperçu de la barre — nom d'utilisateur, répertoire, branche git, modèle, pourcentage de contexte — et dit précisément où tout a atterri : la config dans ~/.claude/settings.json, le script dans ~/.claude/statusline-command.sh. Sur macOS et Linux, le même flux peut convertir votre prompt .zshrc ou .bashrc existant au lieu de repartir de zéro.
Configuration confirmée avec un aperçu de hardik | ~/Dev/project | main | Claude Opus 4.6 | ctx:42% et les deux chemins de fichiers.Voir à 3:06
Décrivez la barre voulue en langage naturel
- 5
Demandez la barre exacte que vous voulez
Relancez /statusline quand vous voulez et décrivez la barre en une phrase : affiche le nom du modèle et le pourcentage de contexte avec une barre de progression. Les demandes dans d'autres langues fonctionnent aussi — la commande n'est qu'un prompt envoyé à l'agent. Chaque nouvelle demande réécrit le même script au lieu d'empiler des doublons.
Une demande en langage naturel — nom du modèle plus barre de progression du pourcentage de contexte — constitue toute l'interface.Voir à 1:07 - 6
Regardez l'outil statusline-setup à l'œuvre
Claude Code fait appel à un outil intégré statusline-setup qui lit votre ~/.claude/settings.json et votre script statusline actuels, puis les réécrit. La carte au survol de Claude résume la fonctionnalité : configurer une barre d'état personnalisée pour surveiller l'usage de la fenêtre de contexte, les coûts et l'état git.
L'outil statusline-setup en cours d'exécution, lisant settings et script, avec la description de la fonctionnalité au survol.Voir à 1:12 - 7
Voici votre nouvelle barre
Une fois terminé, l'agent récapitule le design — nom du modèle en cyan gras, une barre de contexte de vingt caractères qui reste verte jusqu'à 49 %, passe au jaune à 50 % et au rouge à 80 % — et la barre est déjà active en bas de votre terminal. Pas de redémarrage nécessaire ; demandez les ajustements dans la même session.
Le récapitulatif de l'agent au-dessus de la barre Opus 4.6 (1M de contexte) en direct, affichant 2 % de contexte.Voir à 1:27
Lisez le script généré
- 8
Un document JSON arrive sur stdin
Ouvrez le script généré — ~/.claude/statusline.sh sur macOS et Linux, ou la variante .ps1 / statusline-command.sh sous Windows. À chaque mise à jour, Claude Code injecte en JSON un instantané de la session dans l'entrée standard du script. Le Bash généré l'analyse avec jq : .model.display_name, .workspace.current_dir, .cost.total_cost_usd, .cost.total_duration_ms et .context_window.used_percentage.
Le parseur : cinq lectures jq sur stdin, puis un BAR_COLOR choisi aux seuils de 90 % et 70 % de contexte.Voir à 5:46 - 9
Tout ce que vous affichez par echo devient la barre
La fin du script est de la pure mise en forme : coût formaté avec printf, millisecondes converties en minutes et secondes, et un echo par ligne de statusline — modèle avec dossier et branche git sur la première, barre, pourcentage, coût et chronomètre sur la seconde. Les séquences d'échappement ANSI sont les bienvenues, et chaque echo supplémentaire ajoute simplement une ligne.
Deux lignes echo, deux rangées : modèle avec répertoire et branche, puis barre, pourcentage, coût et chronomètre.Voir à 6:13 - 10
Ajoutez la conscience de git de la même façon
Les données git sont à un sous-processus de distance : git rev-parse --git-dir détecte un dépôt, git branch --show-current nomme la branche, et git diff --cached --numstat et --numstat comptent les fichiers staged et modifiés. Les exemples générés colorient les comptages staged en vert et les modifiés en jaune — une protection à petits frais si vous gardez plusieurs sessions Claude Code ouvertes sur des branches différentes.
GIT_STATUS assemblé à partir des comptages staged et modifiés, colorié en vert et jaune avec des codes ANSI.Voir à 5:01
Reprenez le contrôle : clear, réécriture, multi-lignes
- 11
Tout repose sur un seul bloc settings.json
Jetez un œil à ~/.claude/settings.json : toute la fonctionnalité tient en un objet statusLine — type "command" plus la commande à lancer, bash ~/.claude/statusline-command.sh dans cette configuration. Lancez /statusline clear et l'agent retire le bloc ; décrivez une nouvelle barre et il le réécrit. Un .claude/settings.json au niveau du projet fonctionne aussi, si vous voulez une barre par dépôt.
Un diff de /statusline clear : le bloc statusLine quitte settings.json, prêt à être réécrit.Voir à 1:41 - 12
Passez en multi-lignes avec coût, durée et liens de dépôt
Les lignes s'empilent gratuitement : l'exemple multi-lignes de la doc officielle imprime un lien de dépôt cliquable via des séquences d'échappement OSC 8, puis une seconde ligne avec la barre de contexte, le coût de session formaté avec printf '$%.2f' et les minutes et secondes écoulées. Seuils, pourcentages de rate limit, mode vim — demandez n'importe quelle combinaison et itérez jusqu'à ce que le tableau de bord vous convienne.
Un exemple annoté : un lien de dépôt OSC 8 en ligne un ; barre, coût et durée en ligne deux.Voir à 7:31
Le JSON stdin reçu par votre script statusline
Claude Code appelle votre script avec un instantané JSON de la session sur l'entrée standard. Voici les champs à connaître, d'après la documentation officielle — mentionnez l'un d'eux dans une phrase /statusline et l'agent le câble pour vous :
- 1Bases de la session — session_id, transcript_path, cwd et version, plus session_name et prompt_id dès que vous avez envoyé un prompt.
- 2model.id et model.display_name — le modèle Claude actif que votre barre affiche généralement en tête.
- 3workspace.current_dir, workspace.project_dir et workspace.added_dirs, plus workspace.git_worktree et repo.owner / repo.name quand le dossier appartient à un dépôt hébergé.
- 4context_window.used_percentage et remaining_percentage — le chiffre utilisé compte les tokens d'entrée, de création de cache et de lecture de cache, mais pas les tokens de sortie.
- 5context_window.current_usage détaille le tout en input_tokens, output_tokens, cache_creation_input_tokens et cache_read_input_tokens ; il vaut null avant le premier appel API et juste après /compact.
- 6cost.total_cost_usd, cost.total_duration_ms, cost.total_api_duration_ms, cost.total_lines_added et cost.total_lines_removed pour les barres de type dépense-et-rythme.
- 7rate_limits.five_hour et rate_limits.seven_day avec used_percentage et resets_at sur les plans Pro/Max (une paire spend_limit apparaît pour les configurations via gateway) — chaque fenêtre peut être absente indépendamment, prévoyez donc le garde-fou.
- 8Extras — exceeds_200k_tokens, fast_mode, effort.level, thinking.enabled, output_style.name, vim.mode, agent.name, pr.number / pr.url / pr.review_state et la famille worktree.*.
Les noms de champs suivent la documentation officielle de la ligne d'état, qui fournit aussi des scripts prêts à l'emploi pour Bash, Python et Node.js, une variante Windows PowerShell, et une recette git en cache pour les machines lentes.
Dépannage : statusline absente, fausse ou périmée
La plupart des pannes de statusline tiennent à l'une de cinq causes. Toutes se corrigent depuis la même session — aucune réinstallation requise.
- 1Rien ne s'affiche du tout — vérifiez d'abord le JSON de ~/.claude/settings.json ; sur un setup Windows enregistré, la barre est restée muette jusqu'à ce qu'un caractère parasite dans le chemin de la commande soit corrigé et la session relancée. La barre se cache aussi quand des prompts de permission sont ouverts, et un workspace doit être approuvé avant que les scripts tournent.
- 2Barre vide sans erreur — votre script est sorti avec un code non nul ou n'a rien affiché. Lancez-le à la main, p. ex. echo '{"model":{"display_name":"Opus"}}' | bash ~/.claude/statusline.sh, et lisez la sortie ; claude --debug journalise aussi le stderr du script.
- 3Ça ne marche que dans un projet — le bloc a atterri dans un .claude/settings.json au niveau du projet au lieu de votre répertoire personnel. Déplacez-le vers ~/.claude/settings.json pour une barre dans tous les projets.
- 4Les chiffres semblent faux — le script lit probablement la mauvaise propriété. Demandez à Claude de décharger le JSON brut de stdin dans un fichier de debug, lisez ce fichier et corrigez le champ ; la session macOS enregistrée a corrigé son propre pourcentage exactement ainsi.
- 5Le script existe mais n'affiche rien sur macOS ou Linux — jq manque. Installez-le (brew install jq, sudo apt install jq ou l'équivalent Windows), puis demandez à Claude de mettre à jour la ligne d'état pour que le script soit régénéré en conséquence.
À quelle fréquence la barre se rafraîchit (et ce que ça coûte)
Le script s'exécute une fois au démarrage de la session, puis à chaque événement : un nouveau message de l'assistant, la fin d'un /compact, un changement de mode de permission ou de mode vim, une modification de la commande elle-même, une réinitialisation de fenêtre de rate limit ou l'expiration d'un cache de prompt encore chaud. Les mises à jour sont amorties à 300 millisecondes, et une exécution en cours est annulée quand une plus récente arrive.
Les mises à jour étant pilotées par les événements, la barre peut se taire pendant que vous restez inactif — en attendant une longue exécution de sous-agent, par exemple. Ajoutez refreshInterval au bloc statusLine pour relancer le script toutes les N secondes avec des données temporelles. Rien de tout cela ne touche l'API : le script tourne en local et ne consomme aucun token, et chaque ligne echo supplémentaire s'affiche comme une rangée de plus.
Deux réglages de plus pour les bricoleurs : hideVimModeIndicator masque le texte intégré -- INSERT -- si votre script affiche lui-même le mode vim, et un réglage distinct subagentStatusLine donne aux sous-agents leurs propres lignes personnalisées dans le panneau de l'agent.