> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Personnalisez votre barre de statut
> Configurez une barre de statut personnalisée pour surveiller l'utilisation de la fenêtre de contexte, les coûts et l'état git dans Claude Code
La barre de statut est une barre personnalisable en bas de Claude Code qui exécute n'importe quel script shell que vous configurez. Elle reçoit les données de session JSON sur stdin et affiche tout ce que votre script imprime, vous donnant une vue persistante et en un coup d'œil de l'utilisation du contexte, des coûts, de l'état git, ou de tout ce que vous voulez suivre.
Les barres de statut sont utiles quand vous :
* Voulez surveiller l'utilisation de la fenêtre de contexte pendant que vous travaillez
* Avez besoin de suivre les coûts de session
* Travaillez sur plusieurs sessions et avez besoin de les distinguer
* Voulez que la branche git et l'état soient toujours visibles
La barre de statut s'affiche dans sa propre ligne au-dessus des badges de pied de page intégrés et ne les remplace pas. Avec une barre de statut personnalisée configurée, Claude Code cesse d'afficher la plupart des indices de clavier du pied de page, y compris `esc to interrupt`, le secours `? for shortcuts`, et l'indice de [dictée vocale](/docs/fr/voice-dictation) `hold space to speak`. Pour ajouter des badges de lien cliquables au pied de page quand un ID apparaît dans la conversation, sans écrire de script, configurez [`footerLinksRegexes`](/docs/fr/settings-reference#footerlinksregexes) à la place.
Voici un exemple d'une [barre de statut multi-lignes](#display-multiple-lines) qui affiche les informations git sur la première ligne et une barre de contexte codée par couleur sur la deuxième.
Cette page vous guide à travers [la configuration d'une barre de statut basique](#set-up-a-status-line), explique [comment les données circulent](#how-status-lines-work) de Claude Code à votre script, liste [tous les champs que vous pouvez afficher](#available-data), et fournit [des exemples prêts à l'emploi](#examples) pour les modèles courants comme l'état git, le suivi des coûts et les barres de progression.
Configurer une barre de statut
Utilisez la [commande `/statusline`](#use-the-%2Fstatusline-command) pour que Claude Code génère un script pour vous, ou [créez manuellement un script](#manually-configure-a-status-line) et ajoutez-le à vos paramètres.
Utiliser la commande /statusline
La commande `/statusline` accepte des instructions en langage naturel décrivant ce que vous voulez afficher. Claude Code génère un fichier script dans `~/.claude/` et met à jour vos paramètres automatiquement :
```text theme={null}
/statusline show model name and context percentage with a progress bar
```
Approuvez les invites de modification de fichier si Claude Code demande une permission lors de la configuration.
Ajoutez un champ `statusLine` à vos paramètres utilisateur (`~/.claude/settings.json`, où `~` est votre répertoire personnel) ou [paramètres de projet](/docs/fr/settings#where-settings-live). Définissez `type` sur `"command"` et pointez `command` vers un chemin de script ou une commande shell en ligne. Pour une procédure complète de création d'un script, voir [Construire une barre de statut étape par étape](#build-a-status-line-step-by-step).
```json theme={null}
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}
```
Le champ `command` s'exécute dans un shell, vous pouvez donc aussi utiliser des commandes en ligne au lieu d'un fichier script. Cet exemple utilise `jq` pour analyser l'entrée JSON et afficher le nom du modèle et le pourcentage de contexte :
```json theme={null}
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}
```
Le champ optionnel `padding` ajoute un espacement horizontal supplémentaire (en caractères) au contenu de la barre de statut. Par défaut `0`. Cet espacement s'ajoute à l'espacement intégré de l'interface, il contrôle donc l'indentation relative plutôt que la distance absolue du bord du terminal.
Le champ optionnel `refreshInterval` réexécute votre commande toutes les N secondes en plus des [mises à jour basées sur les événements](#how-status-lines-work). Le minimum est `1`. Définissez ceci quand votre barre de statut affiche des données basées sur le temps comme une horloge, ou quand les sous-agents en arrière-plan modifient l'état git pendant que la session principale est inactive. Laissez-le non défini pour s'exécuter uniquement sur les événements.
Le champ optionnel `hideVimModeIndicator` supprime le texte intégré `-- INSERT --` sous l'invite. Définissez ceci sur `true` quand votre script affiche [`vim.mode`](#available-data) lui-même, afin que le mode ne soit pas affiché deux fois.
Désactiver la barre de statut
Exécutez `/statusline` et demandez-lui de supprimer ou d'effacer votre barre de statut (par exemple, `/statusline delete`, `/statusline clear`, `/statusline remove it`). Vous pouvez aussi supprimer manuellement le champ `statusLine` de votre settings.json.
Construire une barre de statut étape par étape
Cette procédure montre ce que `/statusline` configure pour vous en créant manuellement une barre de statut qui affiche le modèle actuel, le répertoire de travail et le pourcentage d'utilisation de la fenêtre de contexte.
L'exécution de [`/statusline`](#use-the-%2Fstatusline-command) avec une description de ce que vous voulez configure tout cela automatiquement pour vous.
Ces exemples utilisent des scripts Bash, qui fonctionnent sur macOS et Linux. Sur Windows, voir [Configuration Windows](#windows-configuration) pour des exemples PowerShell et Git Bash.
Claude Code envoie les données JSON à votre script via stdin. Ce script utilise [`jq`](https://jqlang.org/), un analyseur JSON en ligne de commande que vous devrez peut-être installer, pour extraire le nom du modèle, le répertoire et le pourcentage de contexte, puis imprime une ligne formatée.
Enregistrez ceci dans `~/.claude/statusline.sh` (où `~` est votre répertoire personnel, tel que `/Users/username` sur macOS ou `/home/username` sur Linux) :
```bash theme={null}
#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)
# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"
```
Marquez le script comme exécutable pour que votre shell puisse l'exécuter :
```bash theme={null}
chmod +x ~/.claude/statusline.sh
```
Dites à Claude Code d'exécuter votre script comme barre de statut. Ajoutez cette configuration à `~/.claude/settings.json`, qui définit `type` sur `"command"` (ce qui signifie « exécuter cette commande shell ») et pointe `command` vers votre script :
```json theme={null}
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
```
Votre barre de statut apparaît en bas de l'interface. Claude Code recharge les paramètres automatiquement et exécute votre script dès que vous enregistrez le fichier.
Comment fonctionnent les barres de statut
Claude Code exécute votre script avec les [données de session JSON](#available-data) sur stdin et affiche tout ce que le script imprime sur stdout.
La barre de statut s'exécute localement et ne consomme pas de tokens API. Elle se cache temporairement pendant certaines interactions UI, y compris le menu d'aide et les demandes de permission.
Quand la barre de statut se met à jour
Votre script s'exécute une fois au démarrage d'une session, y compris quand vous en reprenez une. Après cela, il s'exécute à nouveau quand :
* Un nouveau message d'assistant arrive
* `/compact` se termine
* Le mode de permission change
* Le mode Vim bascule
* Vous modifiez la `command` dans vos paramètres `statusLine`
* Un minuteur [`refreshInterval`](#manually-configure-a-status-line) s'écoule, si vous en avez défini un
* Une fenêtre de [limite de débit](#rate-limit-usage) dans les données que votre script a reçues en dernier atteint son heure `resets_at`
* Un [cache de prompt](#prompt-cache-fields) chaud dans les données que votre script a reçues en dernier atteint son heure `expires_at`
Claude Code débounce les mises à jour à 300 ms, donc les changements rapides se regroupent et votre script s'exécute une fois après que les changements s'arrêtent. Un changement de la `command` elle-même ignore le débounce : Claude Code exécute la nouvelle commande immédiatement. Si une nouvelle mise à jour se déclenche pendant que votre script s'exécute encore, Claude Code annule le script en cours. Si vous modifiez votre script, les modifications apparaissent la prochaine fois qu'un déclencheur de mise à jour le réexécute.
Les déclencheurs basés sur les événements peuvent devenir silencieux quand la session principale est inactive, par exemple pendant qu'un coordinateur attend les sous-agents en arrière-plan. Pour garder les segments basés sur le temps ou provenant de sources externes à jour pendant les périodes inactives, définissez [`refreshInterval`](#manually-configure-a-status-line) pour aussi réexécuter la commande sur un minuteur fixe.
Ce que votre script peut afficher
Votre script peut afficher plus qu'une seule ligne de texte brut :
* **Plusieurs lignes** : chaque instruction `echo` ou `print` s'affiche comme une ligne séparée. Voir l'[exemple multi-lignes](#display-multiple-lines).
* **Couleurs** : utilisez les [codes d'échappement ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) comme `\033[32m` pour le vert (le terminal doit les supporter). Voir l'[exemple d'état git](#git-status-with-colors).
* **Liens** : utilisez les [séquences d'échappement OSC 8](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) pour rendre le texte cliquable (Cmd+clic sur macOS, Ctrl+clic sur Windows/Linux). Nécessite un terminal qui supporte les hyperliens comme iTerm2, Kitty ou WezTerm. Voir l'[exemple de liens cliquables](#clickable-links).
Dimensionner la sortie au terminal
Claude Code capture la sortie de votre script au lieu de la connecter directement au terminal, donc `tput cols` et la détection de largeur au niveau du langage ne peuvent pas lire la taille du terminal depuis l'intérieur du script. Lisez plutôt les variables d'environnement `COLUMNS` et `LINES`. Claude Code définit ces variables aux dimensions actuelles du terminal avant d'exécuter votre script.
Données disponibles
Claude Code envoie les champs JSON suivants à votre script via stdin :
| Champ | Description |
| - | - |
| `model.id`, `model.display_name` | Identifiant du modèle actuel et nom d'affichage |
| `cwd`, `workspace.current_dir` | Répertoire de travail actuel. Les deux champs contiennent la même valeur ; `workspace.current_dir` est préféré pour la cohérence avec `workspace.project_dir`. |
| `workspace.project_dir` | Répertoire où Claude Code a été lancé, qui peut différer de `cwd` si le répertoire de travail change pendant une session |
| `workspace.added_dirs` | Répertoires supplémentaires ajoutés via `/add-dir` ou `--add-dir`. Tableau vide si aucun n'a été ajouté |
| `workspace.git_worktree` | Nom du git worktree quand le répertoire actuel se trouve à l'intérieur d'un worktree lié créé avec `git worktree add`. Absent dans le worktree principal. Rempli pour n'importe quel git worktree, contrairement à `worktree.*`, qui est présent uniquement pendant une [session worktree](/docs/fr/worktrees) |
| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | Identité du référentiel analysée à partir de la télécommande `origin`, par exemple `"github.com"`, `"anthropics"`, `"claude-code"`. Absent en dehors d'un référentiel git ou quand aucune télécommande `origin` n'est configurée. Pour un projet gitlab.com imbriqué dans des sous-groupes, `owner` est le chemin d'espace de noms complet avec des barres obliques, tel que `"group/subgroup"`. Avant v2.1.260, `workspace.repo` était absent pour ces projets |
| `cost.total_cost_usd` | Coût total estimé de la session en USD, calculé côté client au prix catalogue sauf si une table [`modelPricing`](/docs/fr/settings-reference#modelpricing) est en vigueur. Peut différer de votre facture réelle. Se réinitialise à 0 \$ quand `/clear` démarre une nouvelle session. Avant v2.1.211, le total s'accumulait après `/clear` |
| `cost.total_duration_ms` | Temps écoulé total depuis le début de la session, en millisecondes. S'accumule entre les reprises et n'inclut pas le temps pendant lequel la session n'est pas en cours d'exécution |
| `cost.total_api_duration_ms` | Temps total passé à attendre les réponses API en millisecondes |
| `cost.total_lines_added`, `cost.total_lines_removed` | Lignes de code modifiées |
| `context_window.total_input_tokens`, `context_window.total_output_tokens` | Comptages de jetons actuellement dans la fenêtre de contexte, à partir de la réponse API la plus récente. L'entrée inclut les lectures et écritures du cache. |
| `context_window.context_window_size` | Taille maximale de la fenêtre de contexte en jetons. 200 000 par défaut, ou 1 000 000 pour les modèles avec contexte étendu. |
| `context_window.used_percentage` | Pourcentage pré-calculé de fenêtre de contexte utilisée |
| `context_window.remaining_percentage` | Pourcentage pré-calculé de fenêtre de contexte restante |
| `context_window.current_usage` | Comptages de jetons du dernier appel API, décrits dans [champs de fenêtre de contexte](#context-window-fields) |
| `exceeds_200k_tokens` | Si le comptage total de jetons (jetons d'entrée, de cache et de sortie combinés) de la réponse API la plus récente dépasse 200 k. C'est un seuil fixe indépendamment de la taille réelle de la fenêtre de contexte. |
| `fast_mode` | Si le [mode rapide](/docs/fr/fast-mode) est activé pour la session |
| `effort.level` | Effort de raisonnement actuel (`low`, `medium`, `high`, `xhigh`, ou `max`). Reflète la valeur de session en direct, y compris les changements `/effort` en cours de session. Absent quand le modèle actuel ne supporte pas le paramètre d'effort |
| `thinking.enabled` | Si la réflexion étendue est activée pour la session |
| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | Pourcentage de la limite de débit de 5 heures ou 7 jours consommée, de 0 à 100 |
| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | Secondes d'époque Unix quand la fenêtre de limite de débit de 5 heures ou 7 jours se réinitialise |
| `rate_limits.spend_limit.used_percentage`, `rate_limits.spend_limit.resets_at` | Derrière une passerelle d'applications Claude, la part de votre limite de dépenses que vous avez utilisée et le moment où sa période se réinitialise. Consultez [champs de limite de dépenses](#spend-limit-fields). Nécessite Claude Code v2.1.251 ou ultérieur |
| `rate_limits.spend_limit.used_usd`, `rate_limits.spend_limit.limit_usd`, `rate_limits.spend_limit.period` | Vos dépenses estimées et votre limite en dollars américains, ainsi que la période de la limite. Ces champs peuvent être absents. Consultez [champs de limite de dépenses](#spend-limit-fields). Nécessite v2.1.284 ou ultérieur à la fois sur Claude Code et sur la passerelle |
| `prompt_cache` | Les statistiques du [cache d'invite](/docs/fr/prompt-caching) de la session pour la conversation principale : ratio de succès, manques, et si le cache est chaud. Consultez [champs de cache d'invite](#prompt-cache-fields) pour chaque champ. Absent jusqu'à la première réponse API de la conversation principale. Nécessite Claude Code v2.1.251 ou ultérieur |
| `session_id` | Identifiant de session unique |
| `session_name` | Nom de session. Utilise le nom personnalisé défini avec l'indicateur `--name` ou `/rename` quand il existe, sinon le titre de session généré par l'IA. Le [nom d'affichage par défaut](/docs/fr/sessions#name-your-sessions), tel que `my-app-3f`, ne remplit pas ce champ. Absent quand la session n'a ni nom personnalisé ni titre généré par l'IA |
| `prompt_id` | UUID identifiant le prompt utilisateur actuellement traité. Correspond à l'attribut [`prompt.id` sur les événements OpenTelemetry](/docs/fr/monitoring-usage#event-correlation-attributes). Absent jusqu'à la première entrée utilisateur |
| `transcript_path` | Chemin vers le fichier de transcription de conversation |
| `version` | Version de Claude Code |
| `output_style.name` | Nom du style de sortie actuel |
| `vim.mode` | Mode vim actuel (`NORMAL`, `INSERT`, `VISUAL`, ou `VISUAL LINE`) quand le [mode vim](/docs/fr/interactive-mode#vim-editor-mode) est activé |
| `agent.name` | Nom de l'agent lors de l'exécution avec l'indicateur `--agent` ou les paramètres d'agent configurés |
| `pr.number`, `pr.url` | Demande de tirage ouverte pour la branche actuelle. Reflète le badge PR dans le pied de page. Dans un référentiel avec une télécommande GitLab, Claude Code remplit ces champs à partir de la [demande de fusion](/docs/fr/interactive-mode#gitlab-merge-requests) ouverte de la branche, donc `pr.number` est le numéro de demande de fusion. Les données de demande de fusion nécessitent Claude Code v2.1.234 ou ultérieur. Absent quand ce n'est pas dans un référentiel git, jusqu'à ce qu'une demande de tirage ou une demande de fusion soit trouvée, ou une fois qu'elle fusionne ou se ferme |
| `pr.review_state` | État d'examen de la PR ouverte : `approved`, `pending`, `changes_requested`, ou `draft`. Peut être indépendamment absent même quand `pr` est présent |
| `pr.kind` | `mr` quand `pr` décrit une [demande de fusion GitLab](/docs/fr/interactive-mode#gitlab-merge-requests). Absent pour les demandes de tirage GitHub, donc les scripts écrits avant ce champ continuent de fonctionner. Pour une demande de fusion, Claude Code définit `review_state` à `approved` quand GitLab rapporte qu'elle est fusionnable, `pending` pour tout autre état ouvert, et `draft` pour un brouillon. Nécessite Claude Code v2.1.234 ou ultérieur |
| `worktree.name` | Nom du worktree actif. Présent uniquement pendant une [session worktree](/docs/fr/worktrees) |
| `worktree.path` | Chemin absolu vers le répertoire du worktree |
| `worktree.branch` | Nom de la branche git pour le worktree (par exemple, `"worktree-my-feature"`). Absent pour les worktrees basés sur des hooks |
| `worktree.original_cwd` | Le répertoire dans lequel Claude se trouvait avant d'entrer dans le worktree |
| `worktree.original_branch` | Branche git extraite avant d'entrer dans le worktree. Absent pour les worktrees basés sur des hooks |
Votre commande de barre de statut reçoit cette structure JSON via stdin :
```json theme={null}
{
"cwd": "/current/working/directory",
"session_id": "abc123...",
"session_name": "my-session",
"prompt_id": "550e8400-e29b-41d4-a716-446655440000",
"transcript_path": "/path/to/transcript.jsonl",
"model": {
"id": "claude-opus-5-5",
"display_name": "Opus"
},
"workspace": {
"current_dir": "/current/working/directory",
"project_dir": "/original/project/directory",
"added_dirs": [],
"git_worktree": "feature-xyz",
"repo": {
"host": "github.com",
"owner": "anthropics",
"name": "claude-code"
}
},
"version": "2.1.90",
"output_style": {
"name": "default"
},
"cost": {
"total_cost_usd": 0.01234,
"total_duration_ms": 45000,
"total_api_duration_ms": 2300,
"total_lines_added": 156,
"total_lines_removed": 23
},
"context_window": {
"total_input_tokens": 15500,
"total_output_tokens": 1200,
"context_window_size": 200000,
"used_percentage": 8,
"remaining_percentage": 92,
"current_usage": {
"input_tokens": 8500,
"output_tokens": 1200,
"cache_creation_input_tokens": 5000,
"cache_read_input_tokens": 2000
}
},
"exceeds_200k_tokens": false,
"prompt_cache": {
"warm": true,
"caching_observed": true,
"ttl": "1h",
"expires_at": 1738429200,
"requests": 14,
"misses": 2,
"expected_rebuilds": 1,
"hit_ratio": 0.91,
"cache_write_tokens": 352000,
"miss_recache_tokens": 310200,
"last_miss_at": 1738425230,
"last_miss_cause": {
"causes": ["tools_changed"],
"tools_added": 2,
"tools_removed": 0
},
"miss_causes": {
"tools_changed": 2
},
"recache_tokens_if_cold": 45000
},
"fast_mode": false,
"effort": {
"level": "high"
},
"thinking": {
"enabled": true
},
"rate_limits": {
"five_hour": {
"used_percentage": 23.5,
"resets_at": 1738425600
},
"seven_day": {
"used_percentage": 41.2,
"resets_at": 1738857600
},
"spend_limit": {
"used_percentage": 62.8,
"resets_at": 1740787200,
"used_usd": 314.12,
"limit_usd": 500,
"period": "monthly"
}
},
"vim": {
"mode": "NORMAL"
},
"agent": {
"name": "security-reviewer"
},
"pr": {
"number": 1234,
"url": "https://github.com/anthropics/claude-code/pull/1234",
"review_state": "pending"
},
"worktree": {
"name": "my-feature",
"path": "/path/to/.claude/worktrees/my-feature",
"branch": "worktree-my-feature",
"original_cwd": "/path/to/project",
"original_branch": "main"
}
}
```
**Champs qui peuvent être absents** (non présents dans JSON) :
* `session_name` : apparaît quand un nom personnalisé a été défini avec `--name` ou `/rename`, ou une fois qu'un titre de session généré par l'IA existe. Le nom d'affichage par défaut, tel que `my-app-3f`, ne le remplit pas
* `prompt_id` : apparaît uniquement après la première entrée utilisateur
* `workspace.git_worktree` : apparaît uniquement quand le répertoire actuel se trouve à l'intérieur d'un git worktree lié
* `workspace.repo` : apparaît uniquement à l'intérieur d'un référentiel git avec une télécommande `origin` configurée
* `effort` : apparaît uniquement quand le modèle actuel supporte le paramètre d'effort de raisonnement
* `vim` : apparaît uniquement quand le mode vim est activé
* `agent` : apparaît uniquement lors de l'exécution avec l'indicateur `--agent` ou les paramètres d'agent configurés
* `pr` : apparaît uniquement tant qu'une PR ouverte ou une demande de fusion GitLab est trouvée pour la branche actuelle, et est supprimée une fois qu'elle fusionne ou se ferme. `pr.review_state` et `pr.kind` peuvent être indépendamment absents
* `worktree` : apparaît uniquement pendant une [session worktree](/docs/fr/worktrees). Quand présent, `branch` et `original_branch` peuvent aussi être absents pour les worktrees basés sur des hooks
* `rate_limits` : apparaît uniquement pour les abonnés Claude.ai Pro et Max, ou derrière une passerelle d'applications Claude qui définit une limite de dépenses pour vous, et uniquement après la première réponse API dans la session. Chaque fenêtre (`five_hour`, `seven_day`, `spend_limit`) peut être indépendamment absente, et Claude Code supprime une fenêtre une fois que son heure `resets_at` passe. Utilisez `jq -r '.rate_limits.five_hour.used_percentage // empty'` pour gérer l'absence avec élégance.
* `prompt_cache` : apparaît après la première réponse API de la conversation principale. Consultez [champs de cache d'invite](#prompt-cache-fields)
**Champs qui peuvent être `null`** :
* `context_window.current_usage` : `null` avant le premier appel API dans une session, et à nouveau après `/compact` jusqu'à ce que le prochain appel API le remplisse à nouveau
* `context_window.used_percentage`, `context_window.remaining_percentage` : peuvent être `null` au début de la session
Gérez les champs manquants avec un accès conditionnel et les valeurs null avec des valeurs par défaut de secours dans vos scripts.
Champs de fenêtre de contexte
L'objet `context_window` décrit la fenêtre de contexte en direct à partir de la réponse API la plus récente.
* **Totaux combinés** (`total_input_tokens`, `total_output_tokens`) : jetons actuellement dans la fenêtre de contexte. `total_input_tokens` est la somme de `input_tokens`, `cache_creation_input_tokens`, et `cache_read_input_tokens` ; `total_output_tokens` est les jetons de sortie de la réponse la plus récente. Les deux sont `0` avant la première réponse API.
* **Utilisation par composant** (`current_usage`) : les mêmes comptages de jetons ventilés par catégorie. Utilisez ceci quand vous avez besoin des accès au cache séparés de l'entrée fraîche.
L'objet `current_usage` contient :
* `input_tokens` : jetons d'entrée dans le contexte actuel
* `output_tokens` : jetons de sortie générés
* `cache_creation_input_tokens` : jetons écrits dans le cache
* `cache_read_input_tokens` : jetons lus du cache
Pour comprendre ce que signifient les champs de cache et comment ils sont facturés, consultez [vérifier les performances du cache](/docs/fr/prompt-caching#check-cache-performance).
Le champ `used_percentage` est calculé à partir des jetons d'entrée uniquement : `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. Il n'inclut pas `output_tokens`.
Si vous calculez le pourcentage de contexte manuellement à partir de `current_usage`, utilisez la même formule d'entrée uniquement pour correspondre à `used_percentage`.
L'objet `current_usage` est `null` avant le premier appel API dans une session, et à nouveau immédiatement après `/compact` jusqu'à ce que le prochain appel API le remplisse à nouveau.
Champs de limite de dépenses
Derrière une [passerelle d'applications Claude avec des limites de dépenses](/docs/fr/claude-apps-gateway-spend-limits#usage-warnings-in-claude-code), l'objet `rate_limits.spend_limit` décrit la limite de dépenses qui s'applique à vous. Il apparaît après la première réponse API de la session et nécessite Claude Code v2.1.251 ou ultérieur. Votre script reçoit ses champs selon des calendriers distincts :
* `used_percentage` et `resets_at` : arrivent avec chaque réponse, ils sont donc présents chaque fois que `spend_limit` l'est. `used_percentage` va de 0 à 100, ou au-dessus de 100 une fois que vous dépassez la limite, et `resets_at` correspond aux secondes d'époque Unix auxquelles la période de la limite se réinitialise.
* `used_usd`, `limit_usd` et `period` : vos dépenses estimées jusqu'à présent et votre limite en dollars américains, ainsi que la période couverte par la limite, parmi `daily`, `weekly` ou `monthly`. La passerelle [calcule `used_usd` à partir des comptages de tokens](/docs/fr/claude-apps-gateway-spend-limits#how-requests-are-priced), il s'agit donc d'une estimation et non d'un montant facturé. Claude Code les lit depuis la passerelle dans une requête distincte, environ toutes les cinq minutes pendant que vous envoyez des requêtes. Les montants en dollars peuvent avoir environ cinq minutes de retard sur `used_percentage`, si bien que les deux peuvent brièvement diverger. Nécessite v2.1.284 ou ultérieur à la fois sur Claude Code et sur la passerelle.
Traitez `used_usd`, `limit_usd` et `period` comme facultatifs même quand `spend_limit` est présent. Votre script reçoit le pourcentage avant eux, et ils restent absents si vous définissez `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, qui désactive cette requête. Lisez chacun avec une valeur de secours dans votre script, par exemple `jq -r '.rate_limits.spend_limit.used_usd // empty'`.
Champs de cache d'invite
L'objet `prompt_cache` résume comment la conversation principale de la session utilise le [cache d'invite](/docs/fr/prompt-caching). Claude Code le calcule à partir des comptages de jetons de cache dans les réponses de l'API, donc il fonctionne sur chaque fournisseur.
L'objet apparaît après la première réponse API de la conversation principale. Claude Code ne compte pas les demandes de sous-agent dans ces statistiques. Nécessite Claude Code v2.1.251 ou ultérieur.
Le tableau liste chaque champ avec sa signification. Les horodatages sont des secondes d'époque Unix, la même unité que `rate_limits.*.resets_at`. Une barre de statut courte affiche généralement un ou deux de ceux-ci ; `warm` et `hit_ratio` résument l'état du cache le plus directement.
| Champ | Description |
| - | - |
| `warm` | Si le préfixe mis en cache est toujours dans sa durée de vie. `false` quand la dernière réponse n'a rapporté aucun jeton de cache, même si `caching_observed` est `true` |
| `caching_observed` | Si une réponse cette session a rapporté des jetons de cache. `false` signifie que la mise en cache d'invite est désactivée, ou votre fournisseur ou passerelle ne la rapporte pas |
| `ttl` | [Durée de vie du cache](/docs/fr/prompt-caching#cache-lifetime) du préfixe mis en cache actuel : `"5m"` ou `"1h"` |
| `expires_at` | Quand le préfixe mis en cache quitte sa durée de vie et devient froid, en secondes d'époque. `null` quand la dernière réponse n'a rapporté aucun jeton de cache |
| `requests` | Demandes API enregistrées pour la conversation principale cette session |
| `misses` | Demandes qui ont retraité le contenu que le cache tenait déjà : plus de 5 % et au moins 2 000 jetons de ce que la demande aurait pu lire du cache, sans compaction ou suppression de résultats d'outils pour expliquer la pénurie de lectures de cache |
| `expected_rebuilds` | Reconstructions de cache qui ont suivi une compaction ou une suppression d'anciens résultats d'outils |
| `hit_ratio` | Jetons lus du cache en tant que fraction de tous les jetons d'entrée cette session, de 0 à 1. Le dénominateur compte les lectures de cache, les écritures de cache, et l'entrée non mise en cache. `null` tant que ces comptages sont tous zéro |
| `cache_write_tokens` | Tous les jetons écrits dans le cache cette session, l'écriture initiale de la première demande incluse |
| `miss_recache_tokens` | Jetons écrits dans le cache par les demandes comptées comme manques |
| `last_miss_at` | Quand le dernier manque s'est produit, en secondes d'époque. `null` tant que la session n'a pas de manques |
| `last_miss_cause` | Ce que Claude Code a identifié comme la cause probable du dernier manque, décrit sous [Cause du dernier manque](#last-miss-cause). Nécessite Claude Code v2.1.260 ou ultérieur |
| `miss_causes` | Combien des manques diagnostiqués de cette session avaient chaque cause, indexés par les mêmes noms de cause que `last_miss_cause`. Nécessite Claude Code v2.1.260 ou ultérieur |
| `recache_tokens_if_cold` | Jetons que la prochaine demande remise en cache si le cache est devenu froid d'ici là. `null` juste après une compaction ou une suppression d'anciens résultats d'outils, jusqu'à ce que la prochaine demande enregistre la taille de la conversation réécrite |
Claude Code affiche les mêmes statistiques dans le terminal, sur la ligne [`/usage` de la commande `Prompt cache (main)`](/docs/fr/costs#prompt-cache-statistics).
Cause du dernier manque
L'objet `last_miss_cause` rapporte ce que Claude Code a identifié comme la cause probable du manque le plus récent. Son tableau `causes` contient un ou plusieurs noms de cause, tels que `tools_changed`, `system_prompt_changed`, `ttl_expired_5m`, ou `likely_server_side`. L'objet est `null` jusqu'au premier manque de la session, et à nouveau chaque fois que Claude Code ne pouvait pas identifier une cause pour le manque le plus récent. Nécessite Claude Code v2.1.260 ou ultérieur.
Deux causes ajoutent des comptages à l'objet :
* `tools_added` et `tools_removed` : avec `tools_changed`, combien d'outils ont été ajoutés à ou supprimés de la demande
* `system_char_delta` : avec `system_prompt_changed`, le changement dans la longueur de l'invite système, en caractères
Exemples
Ces exemples montrent les modèles courants de barre de statut. Pour utiliser n'importe quel exemple :
1. Enregistrez le script dans un fichier comme `~/.claude/statusline.sh` (ou `.py`/`.js`)
2. Le rendre exécutable : `chmod +x ~/.claude/statusline.sh`
3. Ajouter le chemin à vos [paramètres](#manually-configure-a-status-line)
Les exemples Bash utilisent [`jq`](https://jqlang.org/) pour analyser JSON. Python et Node.js ont l'analyse JSON intégrée.
Utilisation de la fenêtre de contexte
Affiche le modèle actuel et l'utilisation de la fenêtre de contexte avec une barre de progression visuelle. Chaque script lit JSON depuis stdin, extrait le champ `used_percentage` et construit une barre de 10 caractères où les blocs remplis (▓) représentent l'utilisation :
```bash Bash theme={null}
#!/bin/bash
# Read all of stdin into a variable
input=$(cat)
# Extract fields with jq, "// 0" provides fallback for null
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# Build progress bar: printf -v creates a run of spaces, then
# ${var// /▓} replaces each space with a block character
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%"
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys
# json.load reads and parses stdin in one step
data = json.load(sys.stdin)
model = data['model']['display_name']
# "or 0" handles null values
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)
# String multiplication builds the bar
filled = pct * 10 // 100
bar = '▓' * filled + '░' * (10 - filled)
print(f"[{model}] {bar} {pct}%")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
// Node.js reads stdin asynchronously with events
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
// Optional chaining (?.) safely handles null fields
const pct = Math.floor(data.context_window?.used_percentage || 0);
// String.repeat() builds the bar
const filled = Math.floor(pct * 10 / 100);
const bar = '▓'.repeat(filled) + '░'.repeat(10 - filled);
console.log(`[${model}] ${bar} ${pct}%`);
});
```
État git avec couleurs
Affiche la branche git avec des indicateurs codés par couleur pour les fichiers en attente et modifiés. Ce script utilise les [codes d'échappement ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) pour les couleurs de terminal : `\033[32m` est vert, `\033[33m` est jaune, et `\033[0m` réinitialise à la valeur par défaut.
Chaque script vérifie si le répertoire actuel est un dépôt git, compte les fichiers en attente et modifiés, et affiche des indicateurs codés par couleur :
```bash Bash theme={null}
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
GREEN='\033[32m'
YELLOW='\033[33m'
RESET='\033[0m'
if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
GIT_STATUS=""
[ "$STAGED" -gt 0 ] && GIT_STATUS="${GREEN}+${STAGED}${RESET}"
[ "$MODIFIED" -gt 0 ] && GIT_STATUS="${GIT_STATUS}${YELLOW}~${MODIFIED}${RESET}"
echo -e "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH $GIT_STATUS"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys, subprocess, os
data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])
GREEN, YELLOW, RESET = '\033[32m', '\033[33m', '\033[0m'
try:
subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()
staged_output = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()
modified_output = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()
staged = len(staged_output.split('\n')) if staged_output else 0
modified = len(modified_output.split('\n')) if modified_output else 0
git_status = f"{GREEN}+{staged}{RESET}" if staged else ""
git_status += f"{YELLOW}~{modified}{RESET}" if modified else ""
print(f"[{model}] 📁 {directory} | 🌿 {branch} {git_status}")
except:
print(f"[{model}] 📁 {directory}")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);
const GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RESET = '\x1b[0m';
try {
execSync('git rev-parse --git-dir', { stdio: 'ignore' });
const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
let gitStatus = staged ? `${GREEN}+${staged}${RESET}` : '';
gitStatus += modified ? `${YELLOW}~${modified}${RESET}` : '';
console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} ${gitStatus}`);
} catch {
console.log(`[${model}] 📁 ${dir}`);
}
});
```
Suivi des coûts et de la durée
Suivez les coûts API de votre session et le temps écoulé. Le champ `cost.total_cost_usd` accumule le coût estimé de tous les appels API dans la session actuelle. Le champ `cost.total_duration_ms` mesure le temps écoulé total depuis le début de la session, tandis que `cost.total_api_duration_ms` suit uniquement le temps passé à attendre les réponses API.
Chaque script formate le coût en devise et convertit les millisecondes en minutes et secondes :
```bash Bash theme={null}
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))
echo "[$MODEL] 💰 $COST_FMT | ⏱️ ${MINS}m ${SECS}s"
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys
data = json.load(sys.stdin)
model = data['model']['display_name']
cost = data.get('cost', {}).get('total_cost_usd', 0) or 0
duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0
duration_sec = duration_ms // 1000
mins, secs = duration_sec // 60, duration_sec % 60
print(f"[{model}] 💰 ${cost:.2f} | ⏱️ {mins}m {secs}s")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const cost = data.cost?.total_cost_usd || 0;
const durationMs = data.cost?.total_duration_ms || 0;
const durationSec = Math.floor(durationMs / 1000);
const mins = Math.floor(durationSec / 60);
const secs = durationSec % 60;
console.log(`[${model}] 💰 $${cost.toFixed(2)} | ⏱️ ${mins}m ${secs}s`);
});
```
Afficher plusieurs lignes
Votre script peut afficher plusieurs lignes pour créer un affichage plus riche.
Cet exemple combine plusieurs techniques : couleurs basées sur des seuils (vert sous 70 %, jaune 70-89 %, rouge 90 %+), une barre de progression et des informations de branche git. Chaque instruction `print` ou `echo` crée une ligne séparée :
```bash Bash theme={null}
#!/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)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'
# Pick bar color based on context usage
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"
MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))
BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"
echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys, subprocess, os
data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])
cost = data.get('cost', {}).get('total_cost_usd', 0) or 0
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)
duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0
CYAN, GREEN, YELLOW, RED, RESET = '\033[36m', '\033[32m', '\033[33m', '\033[31m', '\033[0m'
bar_color = RED if pct >= 90 else YELLOW if pct >= 70 else GREEN
filled = pct // 10
bar = '█' * filled + '░' * (10 - filled)
mins, secs = duration_ms // 60000, (duration_ms % 60000) // 1000
try:
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True, stderr=subprocess.DEVNULL).strip()
branch = f" | 🌿 {branch}" if branch else ""
except:
branch = ""
print(f"{CYAN}[{model}]{RESET} 📁 {directory}{branch}")
print(f"{bar_color}{bar}{RESET} {pct}% | {YELLOW}${cost:.2f}{RESET} | ⏱️ {mins}m {secs}s")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);
const cost = data.cost?.total_cost_usd || 0;
const pct = Math.floor(data.context_window?.used_percentage || 0);
const durationMs = data.cost?.total_duration_ms || 0;
const CYAN = '\x1b[36m', GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RED = '\x1b[31m', RESET = '\x1b[0m';
const barColor = pct >= 90 ? RED : pct >= 70 ? YELLOW : GREEN;
const filled = Math.floor(pct / 10);
const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
const mins = Math.floor(durationMs / 60000);
const secs = Math.floor((durationMs % 60000) / 1000);
let branch = '';
try {
branch = execSync('git branch --show-current', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
branch = branch ? ` | 🌿 ${branch}` : '';
} catch {}
console.log(`${CYAN}[${model}]${RESET} 📁 ${dir}${branch}`);
console.log(`${barColor}${bar}${RESET} ${pct}% | ${YELLOW}$${cost.toFixed(2)}${RESET} | ⏱️ ${mins}m ${secs}s`);
});
```
Liens cliquables
Cet exemple crée un lien cliquable vers votre dépôt GitHub. Maintenez Cmd (macOS) ou Ctrl (Windows/Linux) et cliquez pour ouvrir le lien dans votre navigateur.
Chaque script obtient l'URL du dépôt distant, convertit le format SSH en HTTPS et enveloppe le nom du dépôt dans les codes d'échappement OSC 8. La version Bash utilise `printf '%b'` qui interprète les échappements de barre oblique inverse de manière plus fiable que `echo -e` sur différents shells :
```bash Bash theme={null}
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
# Convert git SSH URL to HTTPS
REMOTE=$(git remote get-url origin 2>/dev/null | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')
if [ -n "$REMOTE" ]; then
REPO_NAME=$(basename "$REMOTE")
# OSC 8 format: \e]8;;URL\a then TEXT then \e]8;;\a
# printf %b interprets escape sequences reliably across shells
printf '%b' "[$MODEL] 🔗 \e]8;;${REMOTE}\a${REPO_NAME}\e]8;;\a\n"
else
echo "[$MODEL]"
fi
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys, subprocess, re, os
data = json.load(sys.stdin)
model = data['model']['display_name']
# Get git remote URL
try:
remote = subprocess.check_output(
['git', 'remote', 'get-url', 'origin'],
stderr=subprocess.DEVNULL, text=True
).strip()
# Convert SSH to HTTPS format
remote = re.sub(r'^git@github\.com:', 'https://github.com/', remote)
remote = re.sub(r'\.git$', '', remote)
repo_name = os.path.basename(remote)
# OSC 8 escape sequences
link = f"\033]8;;{remote}\a{repo_name}\033]8;;\a"
print(f"[{model}] 🔗 {link}")
except:
print(f"[{model}]")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
const { execSync } = require('child_process');
const path = require('path');
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
try {
let remote = execSync('git remote get-url origin', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
// Convert SSH to HTTPS format
remote = remote.replace(/^git@github\.com:/, 'https://github.com/').replace(/\.git$/, '');
const repoName = path.basename(remote);
// OSC 8 escape sequences
const link = `\x1b]8;;${remote}\x07${repoName}\x1b]8;;\x07`;
console.log(`[${model}] 🔗 ${link}`);
} catch {
console.log(`[${model}]`);
}
});
```
Utilisation des limites de débit
Affiche dans la barre de statut l'utilisation des limites de débit d'abonnement Claude.ai, ou vos dépenses par rapport à la limite de dépenses d'une passerelle d'applications Claude. Pour les abonnés, l'objet `rate_limits` contient une fenêtre glissante `five_hour` et une fenêtre hebdomadaire `seven_day`. Chaque fenêtre fournit `used_percentage`, de 0 à 100, et `resets_at`, les secondes d'époque Unix auxquelles la fenêtre se réinitialise. Derrière une passerelle, lisez l'objet `spend_limit`, décrit dans [champs de limite de dépenses](#spend-limit-fields).
L'objet `rate_limits` n'est présent que pour les abonnés Claude.ai Pro et Max, ou derrière une passerelle d'applications Claude avec des limites de dépenses, et uniquement après la première réponse API. Chaque script gère les champs absents avec élégance et, derrière une passerelle, affiche `spend: $314.12 / $500`, ou `spend: 63%` lorsque les champs en dollars sont absents :
```bash Bash theme={null}
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
# "// empty" produces no output when rate_limits is absent
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"
# Behind a Claude apps gateway: dollars when the gateway reports them, else the percentage
SPEND_PCT=$(echo "$input" | jq -r '.rate_limits.spend_limit.used_percentage // empty')
SPEND_USD=$(echo "$input" | jq -r '.rate_limits.spend_limit | select(.used_usd != null) | "$\(.used_usd) / $\(.limit_usd)"')
[ -n "$SPEND_PCT" ] && LIMITS="${LIMITS:+$LIMITS }spend: ${SPEND_USD:-$(printf '%.0f' "$SPEND_PCT")%}"
[ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys
data = json.load(sys.stdin)
model = data['model']['display_name']
parts = []
rate = data.get('rate_limits', {})
five_h = rate.get('five_hour', {}).get('used_percentage')
week = rate.get('seven_day', {}).get('used_percentage')
if five_h is not None:
parts.append(f"5h: {five_h:.0f}%")
if week is not None:
parts.append(f"7d: {week:.0f}%")
# Behind a Claude apps gateway: dollars when the gateway reports them, else the percentage
spend = rate.get('spend_limit', {})
if spend.get('used_percentage') is not None:
if spend.get('used_usd') is not None:
parts.append(f"spend: ${spend['used_usd']} / ${spend['limit_usd']}")
else:
parts.append(f"spend: {spend['used_percentage']:.0f}%")
if parts:
print(f"[{model}] | {' '.join(parts)}")
else:
print(f"[{model}]")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const parts = [];
const fiveH = data.rate_limits?.five_hour?.used_percentage;
const week = data.rate_limits?.seven_day?.used_percentage;
if (fiveH != null) parts.push(`5h: ${Math.round(fiveH)}%`);
if (week != null) parts.push(`7d: ${Math.round(week)}%`);
// Behind a Claude apps gateway: dollars when the gateway reports them, else the percentage
const spend = data.rate_limits?.spend_limit;
if (spend?.used_percentage != null) {
parts.push(spend.used_usd != null
? `spend: $${spend.used_usd} / $${spend.limit_usd}`
: `spend: ${Math.round(spend.used_percentage)}%`);
}
console.log(parts.length ? `[${model}] | ${parts.join(' ')}` : `[${model}]`);
});
```
Mettre en cache les opérations coûteuses
Votre script de barre de statut s'exécute fréquemment pendant les sessions actives. Les commandes comme `git status` ou `git diff` peuvent être lentes, surtout dans les grands dépôts. Cet exemple met en cache les informations git dans un fichier temporaire et ne les actualise que toutes les 5 secondes.
Le nom du fichier de cache doit être stable dans les invocations de barre de statut au sein d'une session, mais unique dans les sessions afin que les sessions concurrentes dans différents dépôts ne lisent pas l'état git en cache les unes des autres. Les identifiants basés sur les processus comme `$$`, `os.getpid()` ou `process.pid` changent à chaque invocation et annulent le cache. Utilisez plutôt le `session_id` de l'entrée JSON : il est stable pour la durée de vie d'une session et unique par session.
Chaque script vérifie si le fichier de cache est manquant ou plus ancien que 5 secondes avant d'exécuter les commandes git :
```bash Bash theme={null}
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
SESSION_ID=$(echo "$input" | jq -r '.session_id')
CACHE_FILE="/tmp/statusline-git-cache-$SESSION_ID"
CACHE_MAX_AGE=5 # seconds
cache_is_stale() {
[ ! -f "$CACHE_FILE" ] || \
# stat -c %Y (Linux) or stat -f %m (macOS) prints the file's last-modified
# time. The Linux form must run first: on Linux, the macOS form prints a
# filesystem report to stdout before failing, and that output would be
# captured by the command substitution and break the arithmetic.
[ $(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
}
if cache_is_stale; then
if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
else
echo "||" > "$CACHE_FILE"
fi
fi
IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"
if [ -n "$BRANCH" ]; then
echo "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH +$STAGED ~$MODIFIED"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi
```
```python Python theme={null}
#!/usr/bin/env python3
import json, sys, subprocess, os, time
data = json.load(sys.stdin)
model = data['model']['display_name']
directory = os.path.basename(data['workspace']['current_dir'])
session_id = data['session_id']
CACHE_FILE = f"/tmp/statusline-git-cache-{session_id}"
CACHE_MAX_AGE = 5 # seconds
def cache_is_stale():
if not os.path.exists(CACHE_FILE):
return True
return time.time() - os.path.getmtime(CACHE_FILE) > CACHE_MAX_AGE
if cache_is_stale():
try:
subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)
branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()
staged = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()
modified = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()
staged_count = len(staged.split('\n')) if staged else 0
modified_count = len(modified.split('\n')) if modified else 0
with open(CACHE_FILE, 'w') as f:
f.write(f"{branch}|{staged_count}|{modified_count}")
except:
with open(CACHE_FILE, 'w') as f:
f.write("||")
with open(CACHE_FILE) as f:
branch, staged, modified = f.read().strip().split('|')
if branch:
print(f"[{model}] 📁 {directory} | 🌿 {branch} +{staged} ~{modified}")
else:
print(f"[{model}] 📁 {directory}")
```
```javascript Node.js theme={null}
#!/usr/bin/env node
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
const data = JSON.parse(input);
const model = data.model.display_name;
const dir = path.basename(data.workspace.current_dir);
const sessionId = data.session_id;
const CACHE_FILE = `/tmp/statusline-git-cache-${sessionId}`;
const CACHE_MAX_AGE = 5; // seconds
const cacheIsStale = () => {
if (!fs.existsSync(CACHE_FILE)) return true;
return (Date.now() / 1000) - fs.statSync(CACHE_FILE).mtimeMs / 1000 > CACHE_MAX_AGE;
};
if (cacheIsStale()) {
try {
execSync('git rev-parse --git-dir', { stdio: 'ignore' });
const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;
fs.writeFileSync(CACHE_FILE, `${branch}|${staged}|${modified}`);
} catch {
fs.writeFileSync(CACHE_FILE, '||');
}
}
const [branch, staged, modified] = fs.readFileSync(CACHE_FILE, 'utf8').trim().split('|');
if (branch) {
console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} +${staged} ~${modified}`);
} else {
console.log(`[${model}] 📁 ${dir}`);
}
});
```
Configuration Windows
Sur Windows, Claude Code exécute les commandes de barre de statut via Git Bash quand Git Bash est installé, ou via PowerShell quand Git Bash est absent.
Git Bash traite les barres obliques inverses non échappées comme des caractères d'échappement, donc un chemin de style Windows comme `C:\Users\username\script.mjs` atteint le script runner avec ses séparateurs supprimés et la commande échoue sans erreur visible. Écrivez les chemins de fichiers dans la chaîne `command` avec des barres obliques avant, comme indiqué dans les exemples ci-dessous. Le raccourci `~` fonctionne également et se développe dans votre répertoire personnel Windows.
Pour exécuter un script PowerShell comme votre barre de statut, invoquez-le via `powershell`. Cela fonctionne que Claude Code achemine la commande via Git Bash ou PowerShell :
```json settings.json theme={null}
{
"statusLine": {
"type": "command",
"command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
}
}
```
```powershell statusline.ps1 theme={null}
$input_json = $input | Out-String | ConvertFrom-Json
$cwd = $input_json.cwd
$model = $input_json.model.display_name
$used = $input_json.context_window.used_percentage
$dirname = Split-Path $cwd -Leaf
if ($used) {
Write-Host "$dirname [$model] ctx: $used%"
} else {
Write-Host "$dirname [$model]"
}
```
Ou, quand Git Bash est installé, exécutez un script Bash directement :
```json settings.json theme={null}
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
```
```bash statusline.sh theme={null}
#!/usr/bin/env bash
input=$(cat)
cwd=$(echo "$input" | grep -o '"cwd":"[^"]*"' | cut -d'"' -f4)
model=$(echo "$input" | grep -o '"display_name":"[^"]*"' | cut -d'"' -f4)
dirname="${cwd##*[/\\]}"
echo "$dirname [$model]"
```
Barres de statut des sous-agents
Le paramètre `subagentStatusLine` rend un corps de ligne personnalisé pour chaque [sous-agent](/docs/fr/sub-agents) affiché dans le panneau d'agent sous l'invite. Utilisez-le pour remplacer la ligne par défaut `name · description · token count` par votre propre formatage.
```json theme={null}
{
"subagentStatusLine": {
"type": "command",
"command": "~/.claude/subagent-statusline.sh"
}
}
```
La commande s'exécute une fois par cycle d'actualisation et reçoit toutes les lignes de sous-agent visibles en tant qu'objet JSON unique sur stdin. L'entrée inclut les [champs d'entrée de hook de base](/docs/fr/hooks#common-input-fields), un champ `columns` avec la largeur de ligne utilisable, et un tableau `tasks` contenant une entrée par ligne, décrit dans [Champs de tâche](#task-fields).
Écrivez une ligne JSON sur stdout par ligne que vous voulez remplacer, sous la forme `{"id": "", "content": ""}`. La chaîne `content` est rendue telle quelle, y compris les couleurs ANSI et les hyperliens OSC 8. Omettez le `id` d'une tâche pour conserver le rendu par défaut pour cette ligne ; émettez une chaîne `content` vide pour la masquer.
Les mêmes portes de confiance, `disableAllHooks` et [`allowManagedHooksOnly`](/docs/fr/settings-reference#allowmanagedhooksonly) qui s'appliquent à `statusLine` s'appliquent ici. Les plugins peuvent expédier un `subagentStatusLine` par défaut dans leur [`settings.json`](/docs/fr/plugins/manifest-reference#standard-layout), mais contrairement aux hooks, les valeurs des plugins ne s'exécutent pas sous `allowManagedHooksOnly` même lorsque le plugin est forcé activé dans les paramètres gérés `enabledPlugins`.
Champs de tâche
Chaque entrée du tableau `tasks` décrit une ligne de sous-agent avec les champs ci-dessous. Les champs marqués comme facultatifs sont omis lorsqu'ils n'ont pas de valeur ; prévoyez donc leur absence dans votre script.
| Champ | Type | Description |
| :- | :- | :- |
| `id` | string | Identifiant de la tâche. Renvoyez-le en tant que `id` dans la ligne que vous écrivez en retour pour cette ligne |
| `name` | string, facultatif | Nom par lequel le sous-agent est [désigné](/docs/fr/sub-agents#subagent-names), lorsqu'il en a un |
| `type` | string | Type de tâche : `local_agent` |
| `agentType` | string | Type de sous-agent sous lequel la tâche s'exécute, comme le sous-agent intégré [`Explore`](/docs/fr/sub-agents#built-in-subagents) ou un sous-agent personnalisé `code-reviewer`. Contient la même valeur que celle reçue par les hooks en tant que [`agent_type`](/docs/fr/hooks#subagentstart). Nécessite Claude Code v2.1.293 ou une version ultérieure |
| `status` | string | État de la tâche, comme `running`, `completed`, `failed` ou `killed` |
| `description` | string | Courte description de la tâche, comme celle que Claude a donnée lors du lancement du sous-agent |
| `label` | string | Court résumé de la progression de la tâche lorsque Claude Code en dispose, sinon le même texte que `description` |
| `startTime` | number | Moment où la tâche a démarré, en millisecondes depuis l'epoch Unix |
| `model` | string, facultatif | ID du modèle résolu sur lequel la tâche s'exécute. Omis jusqu'à ce que le modèle soit résolu. Nécessite Claude Code v2.1.205 ou une version ultérieure |
| `effort` | string ou number, facultatif | Effort de raisonnement défini pour le sous-agent dans son [frontmatter de définition](/docs/fr/sub-agents#supported-frontmatter-fields) ou lors de l'invocation individuelle : `low`, `medium`, `high`, `xhigh`, `max`, ou un budget de tokens numérique. Il s'agit de la valeur configurée, et l'effort que Claude Code applique peut différer lorsque le modèle ne supporte pas ce niveau. Omis lorsqu'aucun effort n'est défini. Nécessite Claude Code v2.1.213 ou une version ultérieure |
| `contextWindowSize` | number, facultatif | Fenêtre de contexte de `model` en tokens, calculée de la même manière que [`context_window.context_window_size`](#context-window-fields) de la barre de statut principale, vous pouvez donc rendre un pourcentage par ligne à partir de `tokenCount`. Omis lorsque `model` l'est. Nécessite Claude Code v2.1.205 ou une version ultérieure |
| `tokenCount` | number | Nombre de tokens courant du sous-agent, la valeur affichée par la ligne par défaut |
| `tokenSamples` | array of numbers | Jusqu'aux 16 dernières lectures de `tokenCount`, une par cycle d'actualisation, de la plus ancienne à la plus récente et se terminant par la valeur actuelle |
| `cwd` | string | Répertoire de travail du sous-agent : son propre répertoire lorsqu'il s'exécute dans l'un d'eux, comme un worktree isolé, sinon le répertoire de travail de la session |
Conseils
* **Tester avec une entrée fictive** : `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`
* **Garder la sortie courte** : la barre de statut a une largeur limitée, donc une sortie longue peut être tronquée ou s'enrouler maladroitement
* **Mettre en cache les opérations lentes** : votre script s'exécute fréquemment pendant les sessions actives, donc les commandes comme `git status` peuvent causer des ralentissements. Voir l'[exemple de mise en cache](#cache-expensive-operations) pour savoir comment gérer cela.
Les projets communautaires comme [ccstatusline](https://github.com/sirmalloc/ccstatusline) et [starship-claude](https://github.com/martinemde/starship-claude) fournissent des configurations pré-construites avec des thèmes et des fonctionnalités supplémentaires.
Dépannage
Si la barre de statut est vide, commencez par [La barre de statut n'apparaît pas](#status-line-not-appearing). Un dossier que vous n'avez pas approuvé et un script qui échoue laissent également la barre vide, comme le décrivent [Confiance de l'espace de travail requise](#workspace-trust-required) et [Erreurs de script ou blocages](#script-errors-or-hangs).
La barre de statut n'apparaît pas
Si vous avez configuré une barre de statut et que rien ne s'affiche en bas de l'interface, effectuez les vérifications suivantes :
* Vérifiez que votre script est exécutable : `chmod +x ~/.claude/statusline.sh`
* Vérifiez que votre script affiche sur stdout, pas stderr
* Exécutez votre script manuellement pour vérifier qu'il produit une sortie
* Sur Windows avec Git Bash installé, les barres obliques inverses dans le chemin `command` sont probablement consommées comme caractères d'échappement avant l'exécution du script. Utilisez des barres obliques avant dans le chemin. Voir [Configuration Windows](#windows-configuration).
* Si `disableAllHooks` est défini sur `true` en dehors des paramètres gérés après l'application de la [priorité des paramètres](/docs/fr/hooks#disable-or-remove-hooks), Claude Code exécute uniquement un `statusLine` à partir des paramètres gérés, et sans `statusLine` géré, la barre de statut est désactivée. Supprimez le paramètre ou définissez-le sur `false` dans le fichier qui le définit pour le réactiver. Voir [`disableAllHooks`](/docs/fr/settings-reference#disableallhooks).
* Si votre organisation définit `allowManagedHooksOnly` dans les paramètres gérés, votre barre de statut personnalisée disparaît sans avertissement : vous ne pouvez obtenir une barre de statut que d'une valeur `statusLine` dans ces paramètres gérés. Voir [ce qui s'exécute sous `allowManagedHooksOnly`](/docs/fr/settings-reference#what-runs-under-allowmanagedhooksonly) pour le comportement complet, et demandez à votre administrateur si ce paramètre s'applique à vous.
* Exécutez `claude --debug` pour journaliser le stderr de votre script à chaque invocation de barre de statut, et son code de sortie à la première invocation dans une session
* Demandez à Claude de lire votre fichier de paramètres et d'exécuter la commande `statusLine` directement pour afficher les erreurs
La barre de statut affiche `--` ou des valeurs vides
Les champs peuvent être `null` avant la fin de la première réponse API ; gérez donc les valeurs null dans votre script avec des valeurs de secours telles que `// 0` dans jq. Redémarrez Claude Code si les valeurs restent vides après plusieurs messages.
Le pourcentage de contexte affiche des valeurs inattendues
La barre de statut rapporte les décomptes de la dernière réponse API, tandis que `/context` ajoute une estimation pour les messages ajoutés depuis cette réponse, donc `/context` peut afficher une valeur plus élevée jusqu'à la réponse suivante. Utilisez `used_percentage` pour l'état de contexte le plus simple et précis. Pour la formule derrière `used_percentage`, voir [Champs de la fenêtre de contexte](#context-window-fields).
Les liens OSC 8 ne sont pas cliquables
Le fait qu'un lien soit cliquable dépend de votre terminal, de la détection par Claude Code du support des hyperliens dans celui-ci, de la suppression éventuelle de la séquence d'échappement par SSH ou tmux, et de la manière dont votre script l'affiche :
* Vérifiez que votre terminal supporte les hyperliens OSC 8 (iTerm2, Kitty, WezTerm)
* Terminal.app ne supporte pas les liens cliquables
* Si le texte du lien apparaît mais n'est pas cliquable, Claude Code peut ne pas avoir détecté le support des hyperliens dans votre terminal. Définissez la variable d'environnement `FORCE_HYPERLINK` pour remplacer la détection avant de lancer Claude Code :
```bash theme={null}
FORCE_HYPERLINK=1 claude
```
Dans PowerShell, définissez d'abord la variable dans la session actuelle :
```powershell theme={null}
$env:FORCE_HYPERLINK = "1"; claude
```
* Les sessions SSH et tmux peuvent supprimer les séquences OSC selon la configuration
* Si les séquences d'échappement apparaissent comme du texte littéral comme `\e]8;;`, utilisez `printf '%b'` au lieu de `echo -e` pour une gestion plus fiable des échappements
Problèmes d'affichage avec les séquences d'échappement
Les séquences d'échappement complexes (couleurs ANSI, liens OSC 8) peuvent occasionnellement causer une sortie brouillée si elles chevauchent d'autres mises à jour UI. Les barres de statut multi-lignes avec codes d'échappement sont plus sujettes aux problèmes de rendu que le texte brut sur une seule ligne.
Si vous voyez du texte corrompu, essayez de simplifier votre script en sortie en texte brut.
Confiance de l'espace de travail requise
Tant que vous n'avez pas accepté la boîte de dialogue de confiance de l'espace de travail, la barre de statut reste vide. Parce que `statusLine` exécute une commande shell, Claude Code l'exécute selon la même [règle de confiance de l'espace de travail que les hooks dans les fichiers de paramètres](/docs/fr/permissions#what-runs-before-you-trust-a-folder). Accepter la boîte de dialogue pour le dossier, ou pour un répertoire parent dont la confiance s'étend à celui-ci, est suffisant.
Jusqu'à ce moment, `claude --debug` consigne `Status line command skipped: workspace trust not accepted`. Redémarrez Claude Code et acceptez la boîte de dialogue de confiance pour l'activer.
Erreurs de script ou blocages
Claude Code n'affiche la sortie de votre script qu'une fois que celui-ci se termine avec le code 0 :
* Les scripts qui se terminent avec des codes non nuls ou ne produisent aucune sortie font que la barre de statut devient vide
* Les scripts lents bloquent la barre de statut de se mettre à jour jusqu'à ce qu'ils se terminent. Gardez les scripts rapides pour éviter une sortie obsolète.
* Si une nouvelle mise à jour se déclenche pendant qu'un script lent s'exécute, le script en cours est annulé
* Testez votre script indépendamment avec une entrée fictive avant de le configurer
Les notifications partagent la ligne de la barre de statut
En dehors du [rendu en plein écran](/docs/fr/fullscreen), Claude Code affiche les notifications sur la même ligne que votre barre de statut. En rendu en plein écran, Claude Code donne aux notifications leur propre ligne.
* Les notifications système comme les erreurs de serveur MCP et les mises à jour automatiques s'affichent sur le côté droit de la ligne. Les notifications transitoires telles que l'avertissement de contexte faible circulent également dans cette zone.
* L'activation du mode verbeux ajoute un compteur de tokens à cette zone
* Sur les terminaux étroits, ces notifications peuvent tronquer votre sortie de barre de statut