Personalizar a barra de status do Claude Code: scripts e ideias
Vá além da configuração inicial: o JSON que seu script statusline recebe, os campos que valem espaço na tela — modelo, tokens, custo, contexto, git —, ideias de cores e layout, e um script da comunidade pronto para roubar.
Resumão
- O /statusline escreve o script para você. Informe seu sistema operacional, peça escopo global e um arquivo .sh/.ps1 separado, e aprove os dois arquivos: uma entrada statusLine no ~/.claude/settings.json mais o script que ela aponta.
- O script lê um único objeto JSON no stdin — model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd, rate_limits — e imprime exatamente o que você quiser ver.
- Peça os campos como lista numerada, pinte a barra de contexto por limiares (verde abaixo de 50%, vermelho acima de 75%), arredonde os tokens para unidades K e vá para várias linhas quando uma ficar lotada.
- Ou instale um script da comunidade: npx contextbricks traz modelo, branch e commit do git, um medidor de tokens estilo tijolos e um aviso de limite semanal — assim você decide quando rodar /compact ou /clear.
Claude Code's Hidden Status Line: Tokens, Model and Project, Your Way
Canal: 호두의 AI 분석실 (Waldo AI Lab)5:27
ContextBricks: My Custom Claude Code Status Line
Script da comunidade: Jeremy Dawes6:17
Status line — official documentation
Docs: code.claude.com/docs
Os fatos desta página foram conferidos com a documentação oficial da status line e as duas gravações acima; os nomes de campos JSON citados correspondem exatamente à referência oficial. As capturas de tela são quadros dessas gravações.
As capturas de tela são quadros dos tutoriais de 호두의 AI 분석실 e Jeremy Dawes (ContextBricks), usados com atribuição e ligados ao instante original em cada passo.
Personalize a barra de status, passo a passo
Acerte o prompt do /statusline de uma vez
- 1
Um prompt de /statusline que diga seu SO, o escopo e o arquivo do script
Rode o /statusline e deixe três coisas claras de cara: seu sistema (Mac, Linux, Windows ou WSL), que a linha deve ser configurada globalmente e que você quer um arquivo .sh separado — .ps1 no Windows. Sem isso, o agente de configuração adivinha seu ambiente e pode mirar o shell errado, e um script no nível do projeto só aparece em um repositório. O prompt cabe em quatro linhas; guarde numa nota para reutilizar.
O prompt de /statusline pronto: SO, escopo global, arquivo separado — é só colar.Ver em 1:15 - 2
Aprove os dois arquivos que o agente cria
Conceda as permissões de leitura e escrita e o agente relata exatamente o que tocou: ~/.claude/settings.json agora contém a configuração statusLine, e um script como ~/.claude/statusline-command.sh gera o conteúdo da linha. Com a lógica num arquivo separado, mais tarde Claude edita o script — não suas configurações. Reinicie o Claude Code para a linha aparecer.
Arquivos criados/atualizados: settings.json guarda a entrada statusLine; o script monta o conteúdo.Ver em 3:20 - 3
Leia a especificação da linha padrão antes de ampliar
De fábrica, a linha gerada mostra o diretório atual, o nome do modelo como [Claude Opus 4.5], o output style quando não é o padrão, o modo vim, a branch git quando você está num repositório e a porcentagem usada da janela de contexto — por exemplo Claude-project [Claude Opus 4.5] (git:main) 12%. Como a configuração é global, vale para todas as sessões do Claude Code na máquina.
A lista de exibição padrão e um exemplo renderizado da linha gerada.Ver em 2:45
Decidir o que a linha mostra
- 4
Peça os campos que você quer — numerados
Peça os acréscimos como lista ordenada e o agente responde com uma ordem de exibição numerada. Esta execução produziu: nome do modelo, uma barra de progresso de 20 caracteres, uma porcentagem tipo 20%, tokens como 40000/200000, git:main e, por fim, o diretório do projeto — renderizado como Claude 3.5 Sonnet [==== ] 20% 40000/200000 git:main Claude-project. As mudanças vão para o script; reinicie o Claude Code para vê-las.
Ordem de exibição 1-6 com uma linha de exemplo, gravados no script.Ver em 3:45 - 5
Dê a cada elemento uma cor com significado
Peça uma cor por elemento e o script recebe códigos ANSI com limiares. A tabela combinada nesta rodada: modelo em ciano; barra de progresso verde abaixo de 50%, amarela de 50 a 75%, vermelha acima de 75%; porcentagem acompanha a barra; tokens em magenta; branch em verde; projeto em azul; separadores em cinza. Deixe o vermelho preso à barra de contexto — a cor de alerta fica reservada para pressão de verdade.
Tabela de cores elemento a elemento, com limiares para a barra de progresso.Ver em 4:15 - 6
Arredonde os tokens para unidades K e confira com o /context
Números crus como 21373/200000 cansam os olhos. Peça unidades K e a linha passa a ler 21k/200k — o agente avisa que o valor é arredondado. Depois confira: rode o /context na mesma sessão e compare; os totais batem. Uma curiosidade da demo: após o arredondamento, uma sessão de 22k e outra de 23K podem exibir o mesmo — bom o bastante para uma linha lida de relance.
21373/200000 vira 21k/200k; o /context confirma os mesmos totais.Ver em 4:30 - 7
Abra duas sessões e confirme que cada linha se acompanha
Abra dois terminais e inicie o Claude Code nos dois. Cada linha de status reporta a própria sessão: 11% e 22k/200k à esquerda, 9% e 18k/200k à direita, enquanto o /context de cada janela concorda com a sua linha. É por isso que branch e projeto pertencem à linha — com várias abas rodando, você vê de relance qual está pesada em vez de rodar /context em todas.
Duas sessões do Claude Code, cada linha de status com o próprio uso de contexto.Ver em 5:15
Roubar um script, ler todo dia
- 8
Pule a autoria: instale um script da comunidade com npx
Você não precisa escrever o script. O ContextBricks instala com um comando — npx contextbricks —, escreve ~/.claude/statusline.sh e atualiza o settings.json, salvando antes um backup. A lista dele: nome do modelo, mensagem git repo:branch [commit], indicadores de mudanças não commitadas, ahead e behind, linhas alteradas na sessão, uso de contexto em tempo real com visualização de tijolos e um detalhamento de tokens. Desinstala com ./uninstall.sh; o caminho de backup impresso restaura o script anterior.
npx contextbricks: script instalado, settings.json atualizado, capacidades listadas.Ver em 0:20 - 9
Leia o medidor enquanto o agente trabalha
A linha personalizada brilha no meio da sessão. Na demo ela mostra [Sonnet 4.5], +2381/-0 linhas, depois uma barra de contexto a 18% (36k/200k tokens) com o detalhe sys:4k tools:16k mcp:2k mem:10k msg:4k e 163k livres. O autor conta tokens interpretando a transcrição da conversa — uma estimativa, não um número da API —, exata o bastante, segundo ele, para decidir quando compactar ou limpar.
36k/200k tokens com detalhamento por categoria enquanto os docs de planejamento são escritos.Ver em 5:00 - 10
Encerre por sinal: o commit pousa, o limite semanal se aproxima
Depois de um commit no git, a linha ganha branch e commit: contextbricks:master [ffe9523] Add comprehensive planning documentation. A borda direita adiciona um segundo sinal — Approaching weekly limit. Entre a porcentagem de contexto, o marcador de commit e o aviso de limite, você sabe quando rodar /compact ou /clear de propósito, em vez de deixar a autocompactação interromper a tarefa.
Branch e commit aparecem na linha; o aviso de limite semanal fica à direita.Ver em 6:02
O que seu script pode ler — campo a campo
Tudo na linha vem de um único objeto JSON que o script recebe no stdin — no início da sessão e de novo a cada atualização: nova mensagem do assistente, um /compact concluído, uma mudança de modo de permissão. Estes são os campos oficiais que valem uma linha.
- 1Modelo e esforço — model.display_name como rótulo (Sonnet 4.5, Opus 4.5) e effort.level quando quiser o nível de raciocínio visível ao lado.
- 2Lugar — workspace.current_dir é o campo preferido para o diretório atual, workspace.project_dir o de lançamento, e workspace.repo.owner/.name identificam o repositório interpretado do remoto origin; a branch, com git branch --show-current.
- 3Contexto — context_window.used_percentage e remaining_percentage já vêm calculados, context_window.current_usage separa input, output, criação e leitura de cache, e context_window.context_window_size é 200000 por padrão (1000000 estendido).
- 4Dinheiro e tempo — cost.total_cost_usd para o custo da sessão (zera com /clear), cost.total_duration_ms e total_api_duration_ms para relógio real versus espera da API, além de cost.total_lines_added e total_lines_removed.
- 5Limites — rate_limits.five_hour e rate_limits.seven_day expõem used_percentage e resets_at nos planos Pro e Max; a documentação traz ainda um objeto prompt_cache com hit_ratio e expires_at para linhas atentas ao cache.
Práticas da documentação: cada echo ou print é uma linha própria, então layouts multilinha são só mais print; códigos ANSI pintam; as variáveis de ambiente COLUMNS e LINES informam a largura do terminal; e todo campo condicionalmente ausente merece um fallback jq como .context_window.used_percentage // 0, para a linha sobreviver aos primeiros segundos de sessão.
Quando a linha se porta mal
Quase toda linha de status quebrada remonta a cinco causas — e cada conserto está a um prompt ou a um comando de distância.
- 1Linha em branco ou tracinhos (--) — são campos nulos antes da primeira resposta da API. A documentação recomenda fallbacks jq (// 0, // empty), e o aviso de confiança do workspace precisa ser aceito ou a linha segue vazia.
- 2Script não roda — deixe-o executável com chmod +x, escreva no stdout em vez do stderr e rode claude --debug para ver os erros dele.
- 3Números estranhos — o autor do ContextBricks conta que Claude errou o cálculo de tokens várias tentativas seguidas. Peça ao agente para despejar o JSON cru num arquivo de depuração e reescrever o script com base nele; depois compare com o /context.
- 4Confusão de shells no Windows — o Claude Code usa Git Bash quando instalado e PowerShell caso contrário; barras normais nos caminhos e o script num .ps1 próprio.
- 5Linha lotada — peça multilinha (o caminho e as infos do repositório vão para uma segunda linha) ou enxugue: tokens em unidades K, uma cor só de separador e fora os campos que você nunca olha.
E se quiser sair de vez: /statusline delete (ou /statusline clear) remove o recurso, o uninstall.sh de um instalador da comunidade desfaz, e o backup das configurações deixado pelo instalador restaura seu script anterior.