Statusline do Claude Code: configure a linha de status do terminal para produtividade (2026)

Autora: Jasmine, uma dev que vive dentro do Claude Code todos os dias no Windows.

O que é a statusline do Claude Code?

A statusline do Claude Code é uma linha personalizável renderizada no rodapé de toda sessão do Claude Code, gerada por um script de shell que você mesma configura. Sempre que o estado da sessão muda, o Claude Code chama esse script, envia todo o estado da sessão para ele como JSON pelo stdin e imprime o que o script devolve pelo stdout como a sua linha de status. Em outras palavras: você recebe um bloco de JSON, escolhe os campos que te interessam, formata do jeito que quiser, imprime, e o Claude Code apenas exibe o resultado.

O ponto essencial para você já gravar: a statusline roda localmente na sua máquina, não faz chamadas de API e não custa tokens. Não é um recurso de "IA" - é só um script bash/PowerShell/Python lendo o stdin. Então você pode mostrar o quanto quiser, muito ou pouco, sem mexer na conta da sua sessão. O Claude Code só reexecuta o script em eventos (troca de modelo, chamada de ferramenta, atualização de contexto e por aí vai) e faz um leve debounce nas chamadas, para que não fique disparando o tempo todo - o que significa que um script um pouco mais pesado não é problema, desde que você não exagere (veja a seção de desempenho mais abaixo).

Diferente da barra de status padrão (que só mostra o diretório de trabalho), uma statusline personalizada deixa você trazer exatamente o que importa para você enquanto programa. Se você está começando agora, leia primeiro o que é o Claude Code e para que ele serve para pegar o contexto, e depois volte aqui para configurar.

O que mostrar na statusline para ser mais produtiva?

Não amontoe todos os campos na statusline. A linha boa é aquela curta, que você lê num piscar de olhos e ainda consegue agir. Depois de alguns meses de uso real, estas são as coisas que eu acho mais valiosas de mostrar:

• Porcentagem de contexto restante - o item número um. Quando o contexto entra na zona de perigo, você pode dar /compact por conta própria ou dividir o trabalho, em vez de o Claude Code comprimir a conversa no meio da tarefa.
• Modelo ativo - saber se você está no Opus ou no Sonnet, para não usar uma marreta numa tachinha (ou o contrário). É fácil esquecer que você acabou de trocar de modelo.
• Custo da sessão - um valor em USD atualizado em tempo real te dá a noção de quais tarefas estão queimando dinheiro, principalmente quando você paga por token de API.
• Branch do Git + contagem de arquivos em stage/modificados - evite fazer commit na branch errada e veja quantas alterações não salvas você tem.
• Limites de uso de 5 horas / 7 dias (planos Pro/Max) - veja sua cota ficando baixa para não ser cortada no meio de uma tarefa longa.
• Diretório / worktree - útil quando você tem várias worktrees abertas ao mesmo tempo.

Minha regra: a linha 1 sempre tem modelo + % de contexto, e custo/Git/limite de uso só entram quando eu realmente preciso. Para mais dos comandos que eu uso todo dia, veja a cola do Claude Code.

O jeito mais rápido: o comando /statusline

Se você não quer mexer em arquivo de configuração, o caminho mais rápido é simplesmente pedir, em linguagem natural, dentro da sua própria sessão do Claude Code. Digite /statusline seguido de uma descrição do que você quer ver:

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

O Claude Code escreve o script para você, salva em ~/.claude/ e adiciona o bloco de configuração ao settings.json automaticamente. Como esse passo cria um arquivo novo e edita sua configuração, o Claude Code vai pedir que você aprove as mudanças antes de gravar - é só dar uma olhada e aceitar. Assim que terminar, a statusline aparece já na sua próxima interação.

Esse é o melhor jeito de conseguir um rascunho rápido, que depois você abre e ajusta na mão a seu gosto. Se você quiser entender primeiro os controles básicos e o fluxo de trabalho, veja o guia do Claude Code para iniciantes.

Configuração manual pelo settings.json (passo a passo)

Quer controle total? Configure na mão. São só 3 passos.

Passo 1 - Crie o script ~/.claude/statusline.sh que lê o JSON do stdin, usa o jq para pegar os campos que você quer e imprime uma linha:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
printf "[%s] 📁 %s | %s%% context" "$model" "$dir" "$pct"

Passo 2 - Torne-o executável:

chmod +x ~/.claude/statusline.sh

⚠️ O erro mais comum: esquecer o chmod +x faz a statusline não mostrar nada, sem nenhum erro claro. Se a sua linha de status está "muda", verifique primeiro a permissão de execução.

Passo 3 - Declare-o em ~/.claude/settings.json:

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

O Claude Code recarrega tudo na sua próxima interação - sem precisar reiniciar. Duas opções úteis: padding controla a margem esquerda (coloque 0 para encostar bem na borda), e refreshInterval (em milissegundos) força o script a rodar de novo num intervalo, para dados baseados em tempo como um relógio ou os limites de uso. Para um script bem curtinho, você pode até colocar o comando jq -r direto no campo command, sem arquivo separado - mas um arquivo separado é muito mais fácil de manter.

A tabela de dados JSON - o que a statusline recebe

A cada execução, o script recebe um objeto JSON completo pelo stdin. Aqui vai uma referência dos campos que você mais vai usar (fonte: a documentação oficial em code.claude.com/docs/en/statusline, acessada em 08/2026):

Observação importante: muitos campos podem estar ausentes ou null, principalmente antes da primeira resposta da API. Sempre use fallbacks no jq: // 0 para números, // "empty" ou // "" para strings. Alguns campos mais novos exigem uma build recente do Claude Code; não afirme que um campo não existe sem ter testado na build que você está rodando.

Scripts de exemplo para copiar e colar (escolha o que você precisa)

Os presets abaixo usam bash + jq. Se você escrever o seu em Python ou Node, o parsing de JSON já vem embutido, então eles ficam ainda mais curtos.

1) Barra de contexto - barra de progresso + %:

#!/bin/bash
input=$(cat)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
filled=$((pct / 10)); empty=$((10 - filled))
bar=$(printf '▓%.0s' $(seq 1 $filled))$(printf '░%.0s' $(seq 1 $empty))
printf "%s %s%%" "$bar" "$pct"

2) Git colorido - branch + arquivos em stage (verde) / modificados (amarelo), usando códigos de cor ANSI:

#!/bin/bash
input=$(cat)
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 ' ')
printf " %s \033[32m+%s\033[0m \033[33m~%s\033[0m" "$branch" "$staged" "$modified"

3) Custo + duração:

#!/bin/bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ms=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
sec=$((ms / 1000)); min=$((sec / 60)); s=$((sec % 60))
printf "\$%.2f | %dm %ds" "$cost" "$min" "$s"

4) Múltiplas linhas + limiares de cor - linha 1: modelo/diretório/branch; linha 2: uma barra que muda de cor (verde <70, amarelo 70-89, vermelho 90+) + custo + limite de uso:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
branch=$(git branch --show-current 2>/dev/null)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
rl=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
if [ "$pct" -ge 90 ]; then c="\033[31m"; elif [ "$pct" -ge 70 ]; then c="\033[33m"; else c="\033[32m"; fi
printf "[%s] 📁 %s %s\n" "$model" "$dir" "$branch"
printf "${c}%s%% context\033[0m | \$%.2f" "$pct" "$cost"
[ -n "$rl" ] && printf " | 5h: %s%%" "$rl"

Esse preset de múltiplas linhas é o que eu de fato uso todo dia: a linha de cima para me situar, a de baixo mudando de cor para me avisar quando o contexto está enchendo - muito eficaz para não levar um /compact no meio do fluxo.

Configurando no Windows (PowerShell + Git Bash)

A maioria dos guias por aí é só para bash. Se você está no Windows (como eu), há dois caminhos que funcionam.

Opção A - Git Bash: o mais simples. Os scripts .sh acima rodam direto, desde que o Git Bash e o jq estejam instalados. Aponte o command para o arquivo .sh como de costume.

Opção B - PowerShell: escreva um script .ps1 que lê o stdin e faz o parsing do JSON:

# C:/Users/you/.claude/statusline.ps1
$data = $input | Out-String | ConvertFrom-Json
$model = $data.model.display_name
$pct = [math]::Floor($data.context_window.used_percentage)
Write-Host "[$model] $pct% context" -NoNewline

Depois declare-o no settings.json:

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

⚠️ A armadilha da barra invertida no Windows: sempre escreva os caminhos com barras normais (/) no campo command. O Git Bash "come" a barra invertida \, então o comando falha em silêncio - a statusline não mostra nada e não reporta nenhum erro. O caractere ~ continua funcionando normalmente.

É exatamente isso que derruba muita gente no Windows: o script está certo, mas o caminho está com as barras erradas. Troque \ por / e ele roda.

Dica de desempenho: não deixe a statusline deixar sua sessão lenta

O script roda com muita frequência. Num repositório grande, git status ou git diff podem levar algumas centenas de milissegundos cada vez - multiplique isso e a sessão inteira fica levemente lenta. Algumas dicas para manter a statusline rápida:

• Faça cache dos resultados do Git em um arquivo temporário indexado por session_id, atualizando a cada ~5 segundos em vez de chamar o git a cada execução. Use session_id como chave de cache - não use $$/PID, porque muda a cada execução do script e deixa o cache inútil.
• Mantenha a saída curta - uma linha, poucos campos. Uma linha longa é lenta e difícil de ler.
• Use refreshInterval para dados baseados em tempo (relógio, limites de uso) em vez de recalcular tudo na marra.
• Leia COLUMNS/LINES para medir a largura e cortar quando o terminal estiver estreito.

Regra prática: se o script leva mais de ~300ms, você vai sentir o atraso. Cache e enxugamento são as duas maiores alavancas.

Problemas comuns & como resolver

Para diagnosticar, rode claude --debug e observe o código de saída e o stderr do script. Além disso, alguns emuladores (o Terminal.app, por exemplo) não suportam links OSC 8, então, se você embutir um hyperlink na sua statusline, pode ser que ele não fique clicável - isso é uma limitação do terminal, não um bug do script.

Não quer editar scripts? Use um construtor visual de linha de status

Nem todo mundo quer escrever bash ou PowerShell só para ter uma linha de status. Se esse é o seu caso, uma opção sem código é o bundle do AgentKit — agora $149 (de $198): o app de desktop tem um construtor visual de linha de status - arraste e solte os campos (modelo, contexto, custo, Git e por aí vai) em vez de codar na mão - junto com um único lugar para gerenciar sua licença, skills e integrações MCP. Para quem tem receio do terminal, é um jeito de montar uma statusline sem tocar no settings.json.

Vou ser franca com você: o /statusline e os scripts acima são totalmente gratuitos e bons o bastante para quase todo mundo - o construtor visual só é mais conveniente se você quer no-code ou quer gerenciar todo o seu conjunto de skills/agents em um só lugar. Se você quiser se aprofundar antes de decidir, leia o que é o AgentKit e se ele vale a pena (análise).

Perguntas frequentes (FAQ)

A statusline custa tokens?

Não. A statusline roda um script local na sua máquina e não faz chamadas à API do Claude, então não usa tokens. Você pode exibir quanta informação quiser sem afetar o custo da sua sessão.

Funciona no Windows?

Sim. Você pode rodar scripts .sh pelo Git Bash, ou escrever um .ps1 e chamá-lo com powershell -NoProfile -File. Só escreva seus caminhos com barras normais (/) para evitar a armadilha da barra invertida.

Por que minha statusline não aparece?

A causa mais comum é esquecer o chmod +x no script. Outras: o script imprime no stderr em vez do stdout, você não aceitou a confiança do workspace, o disableAllHooks está ligado, ou o caminho está com as barras erradas no Windows. Rode claude --debug para ver o erro.

Qual a diferença entre o /statusline e editar o settings.json?

O comando /statusline deixa o Claude Code gerar o script e configurar tudo para você a partir de uma descrição em linguagem natural - rápido e ótimo para iniciantes. Editar o settings.json na mão te dá controle total sobre o conteúdo e a formatação. Muita gente usa o /statusline para conseguir um rascunho e depois ajusta o arquivo na mão.

Qual é o sentido de mostrar a % de contexto?

Para gerenciar a conversa de forma proativa. Quando o contexto está quase cheio, você pode dar /compact ou dividir o trabalho por conta própria, em vez de o Claude Code comprimir tudo no meio da tarefa - o que costuma quebrar a sua linha de raciocínio.

Existe uma configuração pronta que não precisa de código?

Sim. O mais rápido é o /statusline, que deixa o Claude escrever para você. Se você quer uma interface totalmente de arrastar e soltar, sem código, o construtor visual de linha de status no app de desktop do AgentKit é uma opção.

Conclusão + próximos passos

Você não precisa de um script elaborado. Uma única linha simples mostrando modelo + % de contexto já dá um ganho de produtividade perceptível; é só ir incrementando conforme sentir necessidade. Comece com o /statusline, depois abra o arquivo e ajuste a seu gosto. Leia a cola do Claude Code para reunir os comandos que você vai usar sempre, e o guia do CLAUDE.md para ajudar o Claude Code a entender melhor o seu projeto. Está só começando? Volte para o que é o Claude Code.