Personnalisez votre barre de statut

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.

• 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

​

Configurer une barre de statut

​

Utiliser la commande /statusline

/statusline show model name and context percentage with a progress bar

​

Configurer manuellement une barre de statut

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

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

​

Désactiver la barre de statut

​

Construire une barre de statut étape par étape

#!/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"

chmod +x ~/.claude/statusline.sh

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

​

Comment fonctionnent les barres de statut

• Plusieurs lignes : chaque instruction echo ou print s’affiche comme une ligne séparée. Voir l’exemple multi-lignes.
• Couleurs : utilisez les codes d’échappement ANSI comme \033[32m pour le vert (le terminal doit les supporter). Voir l’exemple d’état git.
• Liens : utilisez les séquences d’échappement OSC 8 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.

​

Données disponibles

{
  "cwd": "/current/working/directory",
  "session_id": "abc123...",
  "session_name": "my-session",
  "transcript_path": "/path/to/transcript.jsonl",
  "model": {
    "id": "claude-opus-4-7",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory",
    "added_dirs": [],
    "git_worktree": "feature-xyz"
  },
  "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,
  "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
    }
  },
  "vim": {
    "mode": "NORMAL"
  },
  "agent": {
    "name": "security-reviewer"
  },
  "worktree": {
    "name": "my-feature",
    "path": "/path/to/.claude/worktrees/my-feature",
    "branch": "worktree-my-feature",
    "original_cwd": "/path/to/project",
    "original_branch": "main"
  }
}

​

Champs de fenêtre de contexte

• 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.

• 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

​

Exemples

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

​

Utilisation de la fenêtre de contexte

#!/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%"

​

État git avec couleurs

#!/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

​

Suivi des coûts et de la durée

#!/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"

​

Afficher plusieurs lignes

#!/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"

​

Liens cliquables

#!/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

​

Utilisation des limites de débit

#!/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")%"

[ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"

​

Mettre en cache les opérations coûteuses

#!/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 -f %m is macOS, stat -c %Y is Linux
    [ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$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

​

Configuration Windows

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

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

​

Barres de statut des sous-agents

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

​

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 pour savoir comment gérer cela.

​

Dépannage

• 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
• Si disableAllHooks est défini sur true dans vos paramètres, la barre de statut est également désactivée. Supprimez ce paramètre ou définissez-le sur false pour le réactiver.
• Exécutez claude --debug pour enregistrer le code de sortie et stderr de la première invocation de barre de statut dans une session
• Demandez à Claude de lire votre fichier de paramètres et d’exécuter la commande statusLine directement pour afficher les erreurs

• Les champs peuvent être null avant la fin de la première réponse API
• Gérez les valeurs null dans votre script avec des valeurs par défaut de secours telles que // 0 dans jq
• Redémarrez Claude Code si les valeurs restent vides après plusieurs messages

• Utilisez used_percentage pour l’état de contexte le plus simple et précis
• Le pourcentage de contexte peut différer de la sortie /context en raison du moment où chacun est calculé

• 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. Cela affecte couramment Windows Terminal et d’autres émulateurs ne figurant pas dans la liste de détection automatique. Définissez la variable d’environnement FORCE_HYPERLINK pour remplacer la détection avant de lancer Claude Code :
  FORCE_HYPERLINK=1 claude
  
  Dans PowerShell, définissez d’abord la variable dans la session actuelle :
  $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

• 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
• Si vous voyez du texte corrompu, essayez de simplifier votre script en sortie en texte brut
• 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

• La commande de barre de statut s’exécute uniquement si vous avez accepté la boîte de dialogue de confiance de l’espace de travail pour le répertoire actuel. Parce que statusLine exécute une commande shell, elle nécessite la même acceptation de confiance que les hooks et autres paramètres exécutant des shells.
• Si la confiance n’est pas acceptée, vous verrez la notification statusline skipped · restart to fix au lieu de votre sortie de barre de statut. Redémarrez Claude Code et acceptez l’invite de confiance pour l’activer.

• 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 système comme les erreurs de serveur MCP et les mises à jour automatiques s’affichent sur le côté droit de la même ligne que votre barre de statut. Les notifications transitoires telles que l’avertissement de contexte faible circulent également dans cette zone.
• L’activation du mode verbeux ajoute un compteur de jetons à cette zone
• Sur les terminaux étroits, ces notifications peuvent tronquer votre sortie de barre de statut