Como personalizar a linha de status do Claude Code

Na parte de baixo do Claude Code tem espaço para uma linha (ou várias) que você controla. O Claude Code roda um comando que você escolhe, passa para ele o estado da sessão em JSON e mostra o que esse comando imprimir. A coisa mais útil para colocar ali é quanto do contexto já foi usado, para que uma sessão longa nunca pegue você de surpresa.

Este guia mostra o jeito rápido, como montar o script na mão, todas as opções, os dados que você pode usar, um exemplo completo em duas linhas e o que conferir quando a linha fica em branco.

O que é a linha de status

• É um comando. Pode ser um script em Bash, Python ou Node.js, ou um comando de uma linha só.
• Ela recebe JSON pela entrada padrão, e o que o comando imprimir na saída padrão vira a linha de status. Cada linha impressa é uma linha na tela.
• Ela ganha uma linha própria, acima do rodapé padrão. Não substitui o rodapé, mas enquanto estiver ativa o Claude Code esconde a maioria das dicas de teclado, como esc to interrupt e ? for shortcuts.
• Ela roda no seu computador e não gasta tokens.
• Ela some por um instante durante o autocompletar, o menu de ajuda e os pedidos de permissão.

O jeito rápido: peça para o Claude

Digite /statusline seguido do que você quer ver:

> /statusline mostre o nome do modelo e a porcentagem de contexto com uma barra de progresso

O Claude Code cria um script em ~/.claude/ e o registra nas suas configurações. Aprove as edições de arquivo quando ele pedir. Para tirar depois:

> /statusline remova a linha de status

Para a maioria das pessoas, isso basta. O resto do guia é para quando você quer entender o que ele montou, ou montar o seu.

Monte a sua

Os exemplos usam Bash e o jq, uma ferramenta pequena de linha de comando para JSON. Funcionam em Linux e macOS. O Windows tem uma seção própria perto do fim.

1. 1

   Instale o jq

   No AlmaLinux, Rocky, RHEL ou Fedora:

   Terminal · seu usuário

   $ sudo dnf install jq

   No Debian ou Ubuntu use sudo apt install jq, e no macOS brew install jq.

2. 2

   Escreva o script

   Salve isto em ~/.claude/statusline.sh:

   ~/.claude/statusline.sh

   #!/bin/bash
   input=$(cat)
   
   MODEL=$(echo "$input" | jq -r '.model.display_name')
   DIR=$(echo "$input" | jq -r '.workspace.current_dir')
   PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
   
   echo "[$MODEL] ${DIR##*/} | ${PCT}% de contexto"

   O // 0 dá ao jq um valor padrão quando o campo não existe ou vem null, e o ${DIR##*/} deixa só o nome da pasta.

3. 3

   Deixe o script executável

   Terminal · seu usuário

   $ chmod +x ~/.claude/statusline.sh

4. 4

   Teste antes de o Claude Code rodar

   Passe um JSON na mão. Se isso não imprimir nada, ou der erro, o Claude Code também vai mostrar uma linha em branco.

   Terminal · seu usuário

   $ echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/usuario/meu-app"},"context_window":{"used_percentage":25}}' | ~/.claude/statusline.sh

   Saída

   [Opus] meu-app | 25% de contexto

5. 5

   Configure o Claude Code para usar o script

   Adicione isto em ~/.claude/settings.json, junto com o que já estiver no arquivo:

   ~/.claude/settings.json

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

   O Claude Code aplica a mudança assim que você salva o arquivo.

Todas as opções

O objeto statusLine aceita estas chaves:

• type: sempre "command".
• command: o caminho do script, ou um comando escrito ali mesmo. Por exemplo, isto funciona sem arquivo nenhum: jq -r '"[\(.model.display_name)] \(.context_window.used_percentage // 0)% de contexto"'
• padding: espaços extras antes do conteúdo, em caracteres. O padrão é 0. Ele se soma ao espaçamento que já existe, então serve para recuar a linha, não para fixar a distância da borda do terminal.
• refreshInterval: roda o comando de novo a cada N segundos (mínimo 1), além das atualizações normais. Serve para um relógio, ou para dados que mudam enquanto o Claude está parado.
• hideVimModeIndicator: coloque true se o seu script já mostra o vim.mode, para o texto -- INSERT -- não aparecer duas vezes.

Esse bloco pode ficar nas suas configurações de usuário (~/.claude/settings.json, para todos os projetos) ou no .claude/settings.json de um projeto.

Quando ela atualiza

O script roda quando uma sessão começa ou é retomada, e de novo quando:

• chega uma nova mensagem do assistente
• o /compact termina
• o modo de permissão muda, ou o modo vim liga ou desliga
• você altera o command nas configurações
• o timer do refreshInterval dispara
• uma janela de limite de uso, ou um cache de prompt ainda ativo, chega no horário de renovação ou de expiração informado nos últimos dados

As atualizações são agrupadas: depois de várias mudanças seguidas, o Claude Code espera 300 ms e roda o script uma vez. Se chegar uma atualização nova com o script ainda rodando, a execução em andamento é cancelada. Um script lento não se acumula, mas pode deixar a linha desatualizada. Mantenha o script rápido.

Os dados que você pode usar

A lista completa está na documentação oficial (link no final). Estes são os campos mais usados:

• model.display_name: por exemplo, "Opus 5".
• workspace.current_dir e workspace.project_dir: a pasta atual e a pasta onde o Claude Code foi aberto.
• context_window.used_percentage: quanto do contexto está ocupado. Conta só os tokens de entrada, então pode ser um pouco diferente do /context. O context_window.context_window_size é o máximo.
• rate_limits.five_hour.used_percentage e rate_limits.seven_day.used_percentage: quanto você já usou dos limites de 5 horas e semanal do seu plano, com resets_at como timestamp Unix. Só nos planos Pro e Max, e só depois da primeira resposta da sessão.
• cost.total_cost_usd: uma estimativa calculada pelo preço de tabela da API. Pode ser diferente do que você paga de verdade. Em um plano Pro ou Max, o uso conta para os limites do plano em vez de ser cobrado assim, então encare esse número como uma medida do tamanho da sessão.
• cost.total_duration_ms: tempo desde o início da sessão.
• effort.level: low, medium, high, xhigh ou max. Não aparece se o modelo não suportar níveis de esforço.
• session_name, session_id, version, vim.mode, pr.number, worktree.name.

Alguns campos só aparecem quando se aplicam (rate_limits, vim, pr, worktree), e outros vêm null no começo da sessão (context_window.used_percentage). Sempre defina um valor padrão no jq: // 0 para números que entram em conta, e // empty para o que você só quer mostrar quando existir.

Para ver exatamente o que a sua versão envia, aponte o command para um script que salva a entrada:

#!/bin/bash
tee /tmp/statusline-input.json | jq -r '.model.display_name'

Mande uma mensagem em uma sessão e depois leia o arquivo com jq . /tmp/statusline-input.json.

Um exemplo completo: duas linhas, cores e limites

A primeira linha mostra o modelo, a pasta e a branch do git. A segunda mostra uma barra de contexto com dez blocos, que fica amarela a partir de 70% e vermelha a partir de 90%, e também o limite de 5 horas quando o seu plano informa esse dado.

#!/bin/bash
# Linha 1: modelo, pasta, branch do git. Linha 2: barra de contexto e limite de 5 horas.
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FIVE=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty' | cut -d. -f1)

GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

# Cor da barra: verde abaixo de 70%, amarela a partir de 70%, vermelha a partir de 90%
if [ "$PCT" -ge 90 ]; then COLOR=$RED
elif [ "$PCT" -ge 70 ]; then COLOR=$YELLOW
else COLOR=$GREEN; fi

# Dez blocos, um para cada 10% do contexto
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"

BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)

LINE1="[$MODEL] ${DIR##*/}${BRANCH:+ na $BRANCH}"
LINE2="${COLOR}${BAR}${RESET} ${PCT}% de contexto"
[ -n "$FIVE" ] && LINE2="$LINE2 | limite 5h ${FIVE}%"

printf '%b\n' "$LINE1" "$LINE2"

Em um projeto com git, no meio de uma sessão, fica assim:

[Opus 5] meu-app na main
█████░░░░░ 52% de contexto | limite 5h 23%

Alguns detalhes que economizam tempo:

• Cores: são códigos de escape ANSI. O printf '%b' interpreta esses códigos de forma mais confiável que o echo -e nos vários shells.
• Largura: o script não consegue perguntar a largura ao terminal (o tput cols não funciona ali), porque o Claude Code captura a saída. Leia as variáveis de ambiente COLUMNS e LINES, que o Claude Code define antes de rodar o script.
• Links: as sequências de escape OSC 8 deixam o texto clicável nos terminais que suportam, como iTerm2, Kitty e WezTerm. O Terminal.app não suporta.
• Comandos lentos: um git status em um repositório grande pode atrasar a linha. A página oficial tem um exemplo que guarda o resultado do git em um arquivo com o session_id no nome e só atualiza a cada poucos segundos.

Windows

O Claude Code roda o comando pelo Git Bash, se ele estiver instalado, ou pelo PowerShell, se não estiver. Escreva os caminhos no command com barras normais (/). O Git Bash some com as barras invertidas, e a linha falha sem mostrar erro. Para usar um script de PowerShell:

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

Quando a linha fica em branco

• Rode o script na mão com um JSON de teste, como nos passos acima. Ele precisa imprimir na saída padrão e terminar com código 0. Se terminar com outro código, ou não imprimir nada, a linha fica em branco.
• Confira se ele é executável: chmod +x ~/.claude/statusline.sh.
• Confira se o jq está instalado e no PATH.
• Se você ainda não confiou na pasta, a linha de status não roda. Reinicie o Claude Code e aceite o aviso de confiança.
• Com disableAllHooks definido como true nas suas configurações, a linha de status também fica desligada. Em uma empresa, o allowManagedHooksOnly nas configurações gerenciadas só permite uma linha de status definida pelo administrador.
• Abra com claude --debug. Ele registra o código de saída e o erro da primeira execução da linha de status na sessão.
• As notificações (erros de MCP, avisos de atualização, o aviso de contexto acabando) dividem o espaço com a linha de status e, em um terminal estreito, podem cortar o seu texto.

Fontes

• Customize your status line, documentação do Claude Code (em inglês)
• Settings, documentação do Claude Code (em inglês)
• jq