Personalizar a linha de estado do Claude Code

No fundo do Claude Code há espaço para uma linha (ou várias) que és tu que controlas. O Claude Code corre um comando à tua escolha, passa-lhe o estado da sessão em JSON e mostra o que esse comando escrever. O mais útil que lá podes pôr é quanto do contexto já está ocupado, para que uma sessão longa nunca te apanhe de surpresa.

Este guia mostra a forma rápida, como fazer o script à mão, todas as opções, os dados que podes usar, um exemplo completo em duas linhas e o que verificar quando a linha fica em branco.

O que é a linha de estado

• É um comando. Pode ser um script em Bash, Python ou Node.js, ou um comando de uma linha.
• Recebe JSON pela entrada padrão, e o que escrever na saída padrão passa a ser a linha de estado. Cada linha escrita é uma linha no ecrã.
• Tem a sua própria linha, por cima do rodapé normal. Não substitui o rodapé, mas enquanto estiver ativa o Claude Code esconde a maior parte das dicas de teclado, como esc to interrupt e ? for shortcuts.
• Corre no teu computador e não gasta tokens.
• Desaparece por instantes durante o preenchimento automático, o menu de ajuda e os pedidos de permissão.

A forma rápida: pedir ao Claude

Escreve /statusline seguido do que queres ver:

> /statusline mostra o nome do modelo e a percentagem de contexto com uma barra de progresso

O Claude Code escreve um script em ~/.claude/ e acrescenta-o às tuas definições. Aprova as alterações aos ficheiros quando ele perguntar. Para o tirar mais tarde:

> /statusline remove a linha de estado

Para a maioria das pessoas, chega. O resto do guia é para quando queres perceber o que ele fez, ou fazer o teu.

Fazer a tua

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

1. 1

   Instalar o jq

   Em AlmaLinux, Rocky, RHEL ou Fedora:

   Terminal · o teu utilizador

   $ sudo dnf install jq

   Em Debian ou Ubuntu usa sudo apt install jq, e no macOS brew install jq.

2. 2

   Escrever o script

   Guarda 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 de reserva quando o campo falta ou vem a null, e o ${DIR##*/} fica só com o nome da pasta.

3. 3

   Torná-lo executável

   Terminal · o teu utilizador

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

4. 4

   Testá-lo antes de o Claude Code o correr

   Dá-lhe JSON à mão. Se isto não escrever nada, ou der erro, o Claude Code também vai mostrar uma linha em branco.

   Terminal · o teu utilizador

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

   Resultado

   [Opus] a-minha-app | 25% de contexto

5. 5

   Dizer ao Claude Code para o usar

   Acrescenta isto a ~/.claude/settings.json, junto com o que já lá estiver:

   ~/.claude/settings.json

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

   O Claude Code aplica a alteração assim que gravas o ficheiro.

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 ficheiro nenhum: jq -r '"[\(.model.display_name)] \(.context_window.used_percentage // 0)% de contexto"'
• padding: espaços a mais antes do conteúdo, em caracteres. Por omissão é 0. Soma-se ao espaçamento que já existe, por isso serve para recuar a linha, não para fixar a distância à margem do terminal.
• refreshInterval: volta a correr o comando 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: põe true se o teu script já mostra o vim.mode, para o texto -- INSERT -- não aparecer duas vezes.

A definição pode ficar nas tuas definições de utilizador (~/.claude/settings.json, para todos os projetos) ou no .claude/settings.json de um projeto.

Quando atualiza

O script corre quando uma sessão começa ou é retomada, e outra vez quando:

• chega uma nova mensagem do assistente
• o /compact termina
• muda o modo de permissões, ou liga e desliga o modo vim
• alteras o command nas definições
• dispara o temporizador do refreshInterval
• uma janela de limite de uso, ou uma cache de prompts ainda ativa, chega à hora de renovação ou de expiração indicada nos últimos dados

As atualizações são agrupadas: depois de várias alterações seguidas, o Claude Code espera 300 ms e corre o script uma vez. Se chegar uma atualização nova com o script ainda a correr, a execução em curso é cancelada. Um script lento não se acumula, mas pode deixar a linha desatualizada. Mantém-no rápido.

Os dados que podes usar

A lista completa está na documentação oficial (ligação no fim). 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, por isso pode diferir um pouco 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 já gastaste dos limites de 5 horas e semanal do teu plano, com resets_at como marca de tempo Unix. Só nos planos Pro e Max, e só depois da primeira resposta da sessão.
• cost.total_cost_usd: uma estimativa calculada a preços de tabela da API. Pode diferir do que pagas de facto. Num plano Pro ou Max, o uso conta para os limites do plano em vez de ser cobrado assim, por isso vê o 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 a null no início da sessão (context_window.used_percentage). Define sempre um valor de reserva no jq: // 0 para números com que fazes contas, e // empty para o que só queres mostrar quando existe.

Para veres exatamente o que a tua versão envia, aponta o command para um script que guarda a entrada:

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

Envia uma mensagem numa sessão e depois lê o ficheiro com jq . /tmp/statusline-input.json.

Um exemplo completo: duas linhas, cores e limites

A primeira linha mostra o modelo, a pasta e o ramo do git. A segunda mostra uma barra de contexto com dez blocos, que fica amarela aos 70% e vermelha aos 90%, e ainda o limite de 5 horas quando o teu plano o indica.

#!/bin/bash
# Linha 1: modelo, pasta, ramo 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 por 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:+ em $BRANCH}"
LINE2="${COLOR}${BAR}${RESET} ${PCT}% de contexto"
[ -n "$FIVE" ] && LINE2="$LINE2 | limite 5h ${FIVE}%"

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

Num projeto com git, a meio de uma sessão, fica assim:

[Opus 5] a-minha-app em main
█████░░░░░ 52% de contexto | limite 5h 23%

Alguns pormenores que poupam tempo:

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

Windows

O Claude Code corre o comando pelo Git Bash, se estiver instalado, ou pelo PowerShell, se não estiver. Escreve os caminhos no command com barras normais (/). O Git Bash come 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/utilizador/.claude/statusline.ps1"
  }
}

Quando a linha fica em branco

• Corre o script à mão com JSON de teste, como nos passos acima. Tem de escrever na saída padrão e terminar com código 0. Se terminar com outro código, ou não escrever nada, a linha fica em branco.
• Confirma que é executável: chmod +x ~/.claude/statusline.sh.
• Confirma que o jq está instalado e no PATH.
• Se ainda não confiaste na pasta, a linha de estado não corre. Reinicia o Claude Code e aceita o aviso de confiança.
• Com o disableAllHooks a true nas tuas definições, a linha de estado também fica desligada. Numa empresa, o allowManagedHooksOnly nas definições geridas só deixa correr uma linha de estado definida pelo administrador.
• Arranca com claude --debug. Fica registado o código de saída e o erro da primeira execução da linha de estado na sessão.
• As notificações (erros de MCP, avisos de atualização, o aviso de contexto a acabar) partilham o espaço com a linha de estado e, num terminal estreito, podem cortá-la.

Fontes

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