Statusline do Claude Code: monte a sua com /statusline (2026)
Transforme a parte de baixo do seu terminal em um painel ao vivo — modelo, barra da janela de contexto, branch do git, pasta e custo. Doze passos ilustrados, do comando /statusline nativo até uma barra caprichada e colorida, além das correções para quando ela não aparece.
Resumo
- O /statusline vem embutido no Claude Code. Execute, descreva a barra que quer em uma frase e um agente statusline-setup escreve o script e conecta o bloco statusLine no ~/.claude/settings.json por você.
- No Windows, o agente oferece três caminhos: converter seu perfil do PowerShell, apontar para uma configuração do WSL ou Git Bash, ou montar um padrão do zero com usuário, diretório, modelo e uso de contexto.
- O script lê um documento JSON pelo stdin — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd e mais — e tudo o que ele imprimir com echo vira a sua barra. Cores ANSI e várias linhas são permitidas.
- Tudo roda localmente e não custa tokens. As atualizações disparam nos eventos da sessão (ou a cada N segundos com refreshInterval), e o /statusline clear remove tudo quando você quer recomeçar.
How to Set Up a Custom Status Line in Claude Code CLI to Track API Costs and Context Usage (2026)
Canal:ProgrammingKnowledge23:32
Claude Code最該裝的不是Skill，是這個腳本｜彩色進度條、費用、git 分支一眼看完
Canal:YAHA學堂8:44
Your Claude Code Terminal Should Look Like This (Status Line Setup)
Canal:Leon van Zyl9:02
How to Add a Custom Status Line in Claude Code on Windows 11 (Project-Level Setup)
Canal:Devtamin7:27
Status line — Claude Code documentation
Docs:code.claude.com
Os passos 1 a 4 foram gravados no Windows PowerShell e os passos 5 a 12 no macOS; os frames vêm apenas de gravações de tela limpas — frames com câmera do criador ou overlays queimados foram excluídos.
As dicas de configuração — informar o sistema operacional, manter o script global e em arquivo próprio, o requisito do jq e o truque do arquivo de debug — vêm dos dois vídeos adicionais creditados acima. Os nomes de campos e o comportamento de atualização das seções a fundo seguem a documentação oficial da linha de status.
O passo a passo do /statusline — 12 etapas ilustradas
Execute o /statusline e deixe o Claude fazer a fiação
- 1
Abra o Claude Code no seu terminal
Inicie o claude no PowerShell, Terminal ou qualquer shell. Uma sessão recém-aberta mostra apenas a caixa de boas-vindas e um prompt vazio — a faixa abaixo da entrada, onde a sua statusline vai viver, não existe até que um bloco statusLine seja adicionado ao ~/.claude/settings.json.
Uma sessão novinha do Claude Code v2.1.83 no Windows PowerShell — caixa de boas-vindas, prompt vazio, ainda sem linha de status.Ver em 0:22 - 2
Digite o comando /statusline
O menu de comandos slash o descreve sem rodeios: configurar a interface de linha de status do Claude Code. Aperte Enter. Esse comando nativo entende linguagem natural, então você nunca precisa escrever um script à mão — embora possa editar depois tudo o que ele gerar.
O autocompletar apresenta o /statusline como o comando que configura a interface de linha de status do Claude Code.Ver em 0:32 - 3
Responda às perguntas do agente de configuração
Um agente dedicado statusline-setup assume. No Windows ele avisa que não encontrou uma configuração padrão de shell e oferece três caminhos: colar seu perfil PS1 para ser convertido, apontar para uma configuração do WSL ou Git Bash, ou adotar um padrão com usuário, diretório, modelo e uso de contexto. Os três terminam no mesmo bloco do settings.json.
As três opções do Windows no agente: converter um PS1, apontar para uma configuração própria ou partir de um padrão sensato.Ver em 1:20 - 4
Confira a config e o script que ele escreveu
Quando o agente termina, ele imprime uma prévia da barra — nome de usuário, diretório, branch do git, modelo, porcentagem de contexto — e diz exatamente onde cada coisa ficou: a config em ~/.claude/settings.json e o script em ~/.claude/statusline-command.sh. No macOS e no Linux, o mesmo fluxo pode converter o seu prompt existente do .zshrc ou .bashrc em vez de começar do zero.
Setup confirmado com prévia de hardik | ~/Dev/project | main | Claude Opus 4.6 | ctx:42% e os dois caminhos de arquivo.Ver em 3:06
Descreva a barra que quer em linguagem natural
- 5
Peça exatamente a barra que você quer
Rode o /statusline de novo quando quiser e descreva a barra em uma frase: mostre o nome do modelo e a porcentagem de contexto com uma barra de progresso. Pedidos em outros idiomas também funcionam — o comando é só um prompt para o agente. Cada novo pedido reescreve o mesmo script em vez de empilhar duplicados.
Um pedido em linguagem natural — nome do modelo mais barra de progresso da porcentagem de contexto — é toda a interface.Ver em 1:07 - 6
Veja a ferramenta statusline-setup em ação
O Claude Code despacha uma ferramenta nativa statusline-setup que lê o seu ~/.claude/settings.json e o script de statusline atuais e depois os reescreve. O card ao passar o mouse do Claude resume a função: configurar uma barra de status personalizada para monitorar o uso da janela de contexto, os custos e o estado do git.
A ferramenta statusline-setup no meio da execução, lendo settings e script, com a descrição da função ao passar o mouse.Ver em 1:12 - 7
Conheça a sua nova barra
Ao terminar, o agente resume o design — nome do modelo em ciano negrito, uma barra de contexto de vinte caracteres que fica verde até 49%, fica amarela em 50% e vermelha em 80% — e a barra já está ativa na base do seu terminal. Sem reiniciar; peça os ajustes na mesma sessão.
O resumo do agente acima da barra Opus 4.6 (1M de contexto) ao vivo, marcando 2% de contexto.Ver em 1:27
Leia o script que ele gerou
- 8
Um documento JSON chega pelo stdin
Abra o script gerado — ~/.claude/statusline.sh no macOS e Linux, ou a variante .ps1 / statusline-command.sh no Windows. A cada atualização, o Claude Code encaminha um snapshot JSON da sessão para a entrada padrão do script. O Bash gerado faz o parse com jq: .model.display_name, .workspace.current_dir, .cost.total_cost_usd, .cost.total_duration_ms e .context_window.used_percentage.
O parser: cinco leituras com jq a partir do stdin e depois um BAR_COLOR escolhido nos limiares de 90% e 70% de contexto.Ver em 5:46 - 9
Tudo o que você imprimir com echo vira a barra
O final do script é pura apresentação: custo formatado com printf, milissegundos convertidos em minutos e segundos, e um echo por linha da statusline — modelo com pasta e branch do git na primeira; barra, porcentagem, custo e cronômetro na segunda. Sequências de cor ANSI são bem-vindas, e cada echo extra simplesmente adiciona uma linha.
Duas linhas echo, duas fileiras: modelo com diretório e branch, depois barra, porcentagem, custo e cronômetro.Ver em 6:13 - 10
Adicione a consciência de git do mesmo jeito
Os dados de git estão a um subprocesso de distância: git rev-parse --git-dir detecta um repositório, git branch --show-current nomeia o branch, e git diff --cached --numstat e --numstat contam os arquivos em staged e os modificados. Os exemplos gerados colorem as contagens staged de verde e as modificadas de amarelo — uma proteção barata se você mantém várias sessões do Claude Code abertas em branches diferentes.
GIT_STATUS montado a partir das contagens staged e modified, colorido de verde e amarelo com códigos ANSI.Ver em 5:01
Assuma o controle: clear, reescrita, multi-linha
- 11
Tudo pende de um único bloco no settings.json
Espie o ~/.claude/settings.json: a função inteira é um objeto statusLine — type "command" mais o comando a executar, bash ~/.claude/statusline-command.sh nesse setup. Rode /statusline clear e o agente remove o bloco; descreva uma barra nova e ele o reescreve. Um .claude/settings.json no nível do projeto também funciona, caso queira uma barra por repositório.
Um diff do /statusline clear: o bloco statusLine sai do settings.json, pronto para ser reescrito.Ver em 1:41 - 12
Vá para multi-linha com custo, duração e links do repositório
As linhas se empilham de graça: o exemplo multilinha da documentação oficial imprime um link de repositório clicável com sequências de escape OSC 8 e depois uma segunda linha com a barra de contexto, o custo da sessão formatado com printf '$%.2f' e os minutos e segundos decorridos. Limiares, porcentagens de rate limit, modo vim — peça qualquer combinação e itere até o painel servir como você quer.
Um exemplo anotado: um link de repositório OSC 8 na linha um; barra, custo e duração na linha dois.Ver em 7:31
O JSON do stdin que o seu script de statusline recebe
O Claude Code chama o seu script com um snapshot JSON da sessão pela entrada padrão. Estes são os campos que valem a pena conhecer, segundo a documentação oficial — mencione qualquer um em uma frase com o /statusline e o agente conecta para você:
- 1O básico da sessão — session_id, transcript_path, cwd e version, mais session_name e prompt_id depois que você enviou um prompt.
- 2model.id e model.display_name — o modelo do Claude ativo que a sua barra costuma exibir primeiro.
- 3workspace.current_dir, workspace.project_dir e workspace.added_dirs, mais workspace.git_worktree e repo.owner / repo.name quando a pasta pertence a um repositório hospedado.
- 4context_window.used_percentage e remaining_percentage — o número usado conta tokens de entrada, de criação de cache e de leitura de cache, mas não os de saída.
- 5context_window.current_usage decompõe isso em input_tokens, output_tokens, cache_creation_input_tokens e cache_read_input_tokens; é null antes da primeira chamada de API e logo após o /compact.
- 6cost.total_cost_usd, cost.total_duration_ms, cost.total_api_duration_ms, cost.total_lines_added e cost.total_lines_removed para barras de gasto e ritmo.
- 7rate_limits.five_hour e rate_limits.seven_day com used_percentage e resets_at nos planos Pro/Max (em setups via gateway aparece um par spend_limit) — cada janela pode faltar de forma independente, então proteja o script.
- 8Extras — exceeds_200k_tokens, fast_mode, effort.level, thinking.enabled, output_style.name, vim.mode, agent.name, pr.number / pr.url / pr.review_state e a família worktree.*.
Os nomes de campos seguem a documentação oficial da linha de status, que também traz scripts prontos para Bash, Python e Node.js, uma variante para Windows PowerShell e uma receita de git em cache para máquinas mais lentas.
Solução de problemas: statusline ausente, errada ou desatualizada
Quase toda falha de statusline se resume a uma de cinco causas. Todas se resolvem na mesma sessão — sem precisar reinstalar nada.
- 1Nada aparece — confira primeiro o JSON do ~/.claude/settings.json; em um setup do Windows gravado, a barra ficou muda até corrigirem um caractere a mais no caminho do comando e reiniciarem a sessão. A barra também se esconde enquanto prompts de permissão estão abertos, e um workspace precisa ser confiável antes de os scripts rodarem.
- 2Barra em branco sem erro — seu script saiu com código diferente de zero ou não imprimiu nada. Execute-o à mão, por exemplo echo '{"model":{"display_name":"Opus"}}' | bash ~/.claude/statusline.sh, e leia a saída; o claude --debug também registra o stderr do script.
- 3Funciona só em um projeto — o bloco caiu em um .claude/settings.json de projeto em vez da sua pasta pessoal. Mova para o ~/.claude/settings.json para ter a barra em todo projeto.
- 4Os números parecem errados — o script provavelmente lê a propriedade errada. Peça ao Claude para despejar o JSON cru do stdin em um arquivo de debug, leia esse arquivo e corrija o campo; a sessão de macOS gravada corrigiu a própria porcentagem exatamente assim.
- 5O script existe mas não renderiza nada no macOS ou Linux — falta o jq. Instale (brew install jq, sudo apt install jq ou o equivalente no Windows) e peça ao Claude para atualizar a linha de status para que o script seja regenerado contra ele.
Com que frequência a barra atualiza (e o que custa)
O script roda uma vez no início da sessão e depois sempre que algo acontece: uma nova mensagem do assistente, o fim de um /compact, uma mudança de modo de permissão ou de modo vim, uma edição no próprio comando, um rate limit que reinicia ou um cache de prompt morno que expira. As atualizações têm debounce de 300 milissegundos, e uma execução em andamento é cancelada quando uma mais nova chega.
Como as atualizações são orientadas a eventos, a barra pode ficar quieta enquanto você espera — um subagent em uma tarefa longa, por exemplo. Adicione refreshInterval ao bloco statusLine para reexecutar o script a cada N segundos com dados temporais. Nada disso toca a API: o script roda localmente e não consome tokens, e cada linha echo extra aparece como mais uma fileira.
Mais dois ajustes para quem gosta de mexer: o hideVimModeIndicator suprime o texto embutido -- INSERT -- se o seu script renderiza o modo vim por conta própria, e uma configuração separada, a subagentStatusLine, dá aos subagents linhas personalizadas no painel do agente.