Skip to main content
A linha de status é uma barra personalizável na parte inferior do Claude Code que executa qualquer script de shell que você configurar. Ela recebe dados de sessão JSON em stdin e exibe tudo o que seu script imprime, oferecendo uma visualização persistente e rápida do uso de contexto, custos, status do git ou qualquer outra coisa que você queira rastrear. As linhas de status são úteis quando você:
  • Quer monitorar o uso da janela de contexto enquanto trabalha
  • Precisa rastrear custos de sessão
  • Trabalha em várias sessões e precisa distingui-las
  • Quer que a ramificação git e o status estejam sempre visíveis
A linha de status é renderizada em sua própria linha acima dos crachás de rodapé integrados e não os substitui. Com uma linha de status personalizada configurada, Claude Code para de mostrar a maioria das dicas de teclado do rodapé, incluindo esc to interrupt, o fallback ? for shortcuts e a dica de ditado por voz hold space to speak. Para adicionar crachás de links clicáveis ao rodapé quando uma ID aparece na conversa, sem escrever um script, configure footerLinksRegexes em vez disso. Aqui está um exemplo de uma linha de status de múltiplas linhas que exibe informações do git na primeira linha e uma barra de contexto codificada por cores na segunda.
Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha
Esta página orienta você sobre configurar uma linha de status básica, explica como os dados fluem do Claude Code para seu script, lista todos os campos que você pode exibir e fornece exemplos prontos para usar para padrões comuns como status do git, rastreamento de custos e barras de progresso.

Configurar uma linha de status

Use o comando /statusline para fazer com que o Claude Code gere um script para você, ou crie manualmente um script e adicione-o às suas configurações.

Use o comando /statusline

O comando /statusline aceita instruções em linguagem natural descrevendo o que você quer exibir. O Claude Code gera um arquivo de script em ~/.claude/ e atualiza suas configurações automaticamente:
Aprove os prompts de edição de arquivo se o Claude Code solicitar permissão durante a configuração.

Configure manualmente uma linha de status

Adicione um campo statusLine às suas configurações de usuário (~/.claude/settings.json, onde ~ é seu diretório inicial) ou configurações de projeto. Defina type como "command" e aponte command para um caminho de script ou um comando de shell inline. Para um passo a passo completo de criação de um script, consulte Construir uma linha de status passo a passo.
O campo command é executado em um shell, então você também pode usar comandos inline em vez de um arquivo de script. Este exemplo usa jq para analisar a entrada JSON e exibir o nome do modelo e a porcentagem de contexto:
O campo padding opcional adiciona espaçamento horizontal extra (em caracteres) ao conteúdo da linha de status. O padrão é 0. Este preenchimento é além do espaçamento integrado da interface, então controla o recuo relativo em vez da distância absoluta da borda do terminal. O campo refreshInterval opcional executa novamente seu comando a cada N segundos além das atualizações orientadas por eventos. O mínimo é 1. Defina isto quando sua linha de status exibir dados baseados em tempo, como um relógio, ou quando subagentes em segundo plano alterarem o estado do git enquanto a sessão principal está ociosa. Deixe sem definir para executar apenas em eventos. O campo hideVimModeIndicator opcional suprime o texto integrado -- INSERT -- abaixo do prompt. Defina isto como true quando seu script renderizar vim.mode em si, para que o modo não seja exibido duas vezes.

Desabilitar a linha de status

Execute /statusline e peça para remover ou limpar sua linha de status (por exemplo, /statusline delete, /statusline clear, /statusline remove it). Você também pode excluir manualmente o campo statusLine do seu settings.json.

Construir uma linha de status passo a passo

Este passo a passo mostra o que /statusline configura para você criando manualmente uma linha de status que exibe o modelo atual, diretório de trabalho e porcentagem de uso da janela de contexto.
Executar /statusline com uma descrição do que você quer configura tudo isso automaticamente para você.
Estes exemplos usam scripts Bash, que funcionam no macOS e Linux. No Windows, consulte Configuração do Windows para exemplos de PowerShell e Git Bash.
Uma linha de status mostrando nome do modelo, diretório e porcentagem de contexto
1

Crie um script que leia JSON e imprima a saída

O Claude Code envia dados JSON para seu script via stdin. Este script usa jq, um analisador JSON de linha de comando que você pode precisar instalar, para extrair o nome do modelo, diretório e porcentagem de contexto, depois imprime uma linha formatada.Salve isto em ~/.claude/statusline.sh (onde ~ é seu diretório inicial, como /Users/username no macOS ou /home/username no Linux):
2

Torne-o executável

Marque o script como executável para que seu shell possa executá-lo:
3

Adicione às configurações

Diga ao Claude Code para executar seu script como a linha de status. Adicione esta configuração a ~/.claude/settings.json, que define type como "command" (significando “execute este comando de shell”) e aponta command para seu script:
Sua linha de status aparece na parte inferior da interface. O Claude Code recarrega as configurações automaticamente e executa seu script assim que você salva o arquivo.

Como as linhas de status funcionam

O Claude Code executa seu script com dados de sessão JSON na entrada padrão e exibe tudo o que o script imprime na saída padrão. Quando é atualizado Seu script é executado uma vez quando uma sessão inicia, incluindo quando você retoma uma. Depois disso, ele é executado novamente quando:
  • Uma nova mensagem do assistente chega
  • /compact termina
  • O modo de permissão muda
  • O modo Vim alterna
  • Você altera o command nas suas configurações de statusLine
  • Um temporizador refreshInterval decorre, se você definir um
  • Uma janela de limite de taxa nos dados que seu script recebeu por último atinge seu tempo resets_at
  • Um cache de prompt aquecido nos dados que seu script recebeu por último atinge seu tempo expires_at
O Claude Code debounce as atualizações em 300ms, portanto mudanças rápidas são agrupadas e seu script é executado uma vez após as mudanças pararem. Uma alteração no próprio command ignora o debounce: o Claude Code executa o novo comando imediatamente. Se uma nova atualização for acionada enquanto seu script ainda está em execução, o Claude Code cancela o script em andamento. Se você editar seu script, as alterações aparecem na próxima vez que um gatilho de atualização o re-executa. Os gatilhos acionados por eventos podem ficar silenciosos quando a sessão principal está ociosa, por exemplo enquanto um coordenador aguarda subagentes em segundo plano. Para manter segmentos baseados em tempo ou de origem externa atualizados durante períodos ociosos, defina refreshInterval para também re-executar o comando em um temporizador fixo. O que seu script pode exibir Dimensionando a saída para o terminal O Claude Code captura a saída do seu script em vez de conectá-la diretamente ao terminal, portanto tput cols e a detecção de largura em nível de linguagem não podem ler o tamanho do terminal de dentro do script. Leia as variáveis de ambiente COLUMNS e LINES em vez disso. O Claude Code define estas variáveis para as dimensões atuais do terminal antes de executar seu script.
A linha de status é executada localmente e não consome tokens de API. Ela se oculta temporariamente durante certas interações da interface, incluindo o menu de ajuda e prompts de permissão.

Dados disponíveis

O Claude Code envia os seguintes campos JSON para seu script via stdin:
Seu comando de linha de status recebe esta estrutura JSON via stdin:
Campos que podem estar ausentes (não presentes em JSON):
  • session_name: aparece quando um nome personalizado foi definido com --name ou /rename, ou uma vez que um título de sessão gerado por IA existe. O nome de exibição padrão, como my-app-3f, não popula este campo
  • prompt_id: aparece apenas após a primeira entrada do usuário
  • workspace.git_worktree: aparece apenas quando o diretório atual está dentro de uma git worktree vinculada
  • workspace.repo: aparece apenas dentro de um repositório git com um remote origin configurado
  • effort: aparece apenas quando o modelo atual suporta o parâmetro de esforço de raciocínio
  • vim: aparece apenas quando o modo vim está habilitado
  • agent: aparece apenas ao executar com a flag --agent ou configurações de agente configuradas
  • pr: aparece apenas enquanto um PR aberto ou solicitação de mesclagem GitLab é encontrado para o branch atual, e é removido uma vez que seja mesclado ou fechado. pr.review_state e pr.kind podem estar independentemente ausentes
  • worktree: aparece apenas enquanto a sessão está em uma sessão de worktree. Quando presente, branch e original_branch também podem estar ausentes para worktrees baseadas em hook
  • rate_limits: aparece apenas para assinantes Claude.ai Pro e Max, ou atrás de um gateway de aplicativos Claude que define um limite de gastos para você, e apenas após a primeira resposta de API na sessão. Cada janela (five_hour, seven_day, spend_limit) pode estar independentemente ausente, e o Claude Code remove uma janela uma vez que seu tempo resets_at passa. Use jq -r '.rate_limits.five_hour.used_percentage // empty' para lidar com ausência graciosamente.
  • prompt_cache: aparece após a primeira resposta de API da conversa principal. Consulte campos de cache de prompt
Campos que podem ser null:
  • context_window.current_usage: null antes da primeira chamada de API em uma sessão, e novamente após /compact até que a próxima chamada de API a repopule
  • context_window.used_percentage, context_window.remaining_percentage: podem ser null no início da sessão
Trate campos ausentes com acesso condicional e valores nulos com padrões de fallback em seus scripts.

Campos de janela de contexto

O objeto context_window descreve a janela de contexto em tempo real da resposta de API mais recente.
  • Totais combinados (total_input_tokens, total_output_tokens): tokens atualmente na janela de contexto. total_input_tokens é a soma de input_tokens, cache_creation_input_tokens e cache_read_input_tokens; total_output_tokens são os tokens de saída da resposta mais recente. Ambos são 0 antes da primeira resposta de API.
  • Uso por componente (current_usage): as mesmas contagens de tokens divididas por categoria. Use isto quando você precisar de acertos de cache separados da entrada fresca.
O objeto current_usage contém:
  • input_tokens: tokens de entrada no contexto atual
  • output_tokens: tokens de saída gerados
  • cache_creation_input_tokens: tokens escritos no cache
  • cache_read_input_tokens: tokens lidos do cache
Para o que os campos de cache significam e como são cobrados, consulte verificar desempenho do cache. O campo used_percentage é calculado apenas a partir de tokens de entrada: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Ele não inclui output_tokens. Se você calcular a porcentagem de contexto manualmente a partir de current_usage, use a mesma fórmula apenas de entrada para corresponder a used_percentage. O objeto current_usage é null antes da primeira chamada de API em uma sessão, e novamente imediatamente após /compact até que a próxima chamada de API a repopule.

Campos de cache de prompt

O objeto prompt_cache resume como a conversa principal da sessão está usando o cache de prompt. O Claude Code o calcula a partir das contagens de tokens de cache nas respostas da API, então funciona em todos os provedores. O objeto aparece após a primeira resposta de API da conversa principal. O Claude Code não conta solicitações de subagentos nessas estatísticas. Requer Claude Code v2.1.251 ou posterior. A tabela lista cada campo com seu significado. Os timestamps são segundos de época Unix, a mesma unidade que rate_limits.*.resets_at. Uma linha de status curta geralmente mostra um ou dois destes; warm e hit_ratio resumem o estado do cache mais diretamente. O Claude Code mostra as mesmas estatísticas no terminal, na linha /usage do comando Prompt cache (main).

Causa da última falha

O objeto last_miss_cause relata o que o Claude Code identificou como a provável causa da falha mais recente. Seu array causes contém um ou mais nomes de causa, como tools_changed, system_prompt_changed, ttl_expired_5m ou likely_server_side. O objeto é null até a primeira falha da sessão, e novamente sempre que o Claude Code não conseguir identificar uma causa para a falha mais recente. Requer Claude Code v2.1.260 ou posterior. Duas causas adicionam contagens ao objeto:
  • tools_added e tools_removed: com tools_changed, quantas ferramentas foram adicionadas ou removidas da solicitação
  • system_char_delta: com system_prompt_changed, a mudança no comprimento do prompt do sistema, em caracteres

Exemplos

Estes exemplos mostram padrões comuns de linha de status. Para usar qualquer exemplo:
  1. Salve o script em um arquivo como ~/.claude/statusline.sh (ou .py/.js)
  2. Torne-o executável: chmod +x ~/.claude/statusline.sh
  3. Adicione o caminho às suas configurações
Os exemplos de Bash usam jq para analisar JSON. Python e Node.js têm análise JSON integrada.

Uso da janela de contexto

Exiba o modelo atual e o uso da janela de contexto com uma barra de progresso visual. Cada script lê JSON de stdin, extrai o campo used_percentage e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:
Uma linha de status mostrando nome do modelo e uma barra de progresso com porcentagem

Status do git com cores

Mostre a ramificação git com indicadores codificados por cores para arquivos preparados e modificados. Este script usa códigos de escape ANSI para cores de terminal: \033[32m é verde, \033[33m é amarelo e \033[0m redefine para padrão.
Uma linha de status mostrando modelo, diretório, ramificação git e indicadores coloridos para arquivos preparados e modificados
Cada script verifica se o diretório atual é um repositório git, conta arquivos preparados e modificados e exibe indicadores codificados por cores:

Rastreamento de custo e duração

Rastreie os custos de API e o tempo decorrido da sua sessão. O campo cost.total_cost_usd acumula o custo estimado de todas as chamadas de API na sessão atual. O campo cost.total_duration_ms mede o tempo total decorrido desde o início da sessão, enquanto cost.total_api_duration_ms rastreia apenas o tempo gasto aguardando respostas de API. Cada script formata o custo como moeda e converte milissegundos em minutos e segundos:
Uma linha de status mostrando nome do modelo, custo da sessão e duração

Exibir múltiplas linhas

Seu script pode exibir múltiplas linhas para criar uma exibição mais rica.
Uma linha de status de múltiplas linhas mostrando nome do modelo, diretório, ramificação git na primeira linha, e uma barra de progresso de uso de contexto com custo e duração na segunda linha
Este exemplo combina várias técnicas: cores baseadas em limite (verde abaixo de 70%, amarelo 70-89%, vermelho 90%+), uma barra de progresso e informações de ramificação git. Cada instrução print ou echo cria uma linha separada:
Este exemplo cria um link clicável para seu repositório GitHub. Mantenha Cmd (macOS) ou Ctrl (Windows/Linux) pressionado e clique para abrir o link em seu navegador.
Uma linha de status mostrando um link clicável para um repositório GitHub
Cada script obtém a URL remota do git, converte o formato SSH para HTTPS e envolve o nome do repositório em códigos de escape OSC 8. A versão Bash usa printf '%b' que interpreta escapes de barra invertida de forma mais confiável que echo -e em diferentes shells:

Uso de limite de taxa

Exiba o uso do limite de taxa de assinatura Claude.ai na linha de status. O objeto rate_limits contém uma janela móvel five_hour e uma janela semanal seven_day. Cada janela fornece used_percentage, de 0 a 100, e resets_at, os segundos de época Unix quando a janela é redefinida. Atrás de um gateway de aplicativos Claude com limites de gastos, rate_limits carrega spend_limit com os mesmos dois campos para o limite de gastos que se aplica a você, exceto que seu used_percentage pode ultrapassar 100 uma vez que você exceda o limite. Requer Claude Code v2.1.251 ou posterior. O objeto rate_limits está presente apenas para assinantes Claude.ai Pro e Max, ou atrás de um gateway de aplicativos Claude com limites de gastos, e apenas após a primeira resposta de API. Cada script trata o campo ausente graciosamente:

Cache de operações caras

Seu script de linha de status é executado frequentemente durante sessões ativas. Comandos como git status ou git diff podem ser lentos, especialmente em repositórios grandes. Este exemplo armazena em cache informações do git em um arquivo temporário e apenas as atualiza a cada 5 segundos. O nome do arquivo de cache precisa ser estável em invocações de linha de status dentro de uma sessão, mas único em sessões para que sessões simultâneas em repositórios diferentes não leiam o estado git em cache uma da outra. Identificadores baseados em processo como $$, os.getpid() ou process.pid mudam a cada invocação e derrotam o cache. Use o session_id da entrada JSON em vez disso: é estável para a vida útil de uma sessão e único por sessão. Cada script verifica se o arquivo de cache está ausente ou mais antigo que 5 segundos antes de executar comandos git:

Configuração do Windows

No Windows, o Claude Code executa comandos de linha de status através do Git Bash quando o Git Bash está instalado, ou através do PowerShell quando o Git Bash está ausente. O Git Bash trata barras invertidas sem aspas como caracteres de escape, portanto um caminho no estilo Windows como C:\Users\username\script.mjs chega ao executor de script com seus separadores removidos e o comando falha sem um erro visível. Escreva caminhos de arquivo na string command com barras normais, conforme mostrado nos exemplos abaixo. O atalho ~ também funciona e se expande para seu diretório inicial do Windows. Para executar um script PowerShell como sua linha de status, invoque-o via powershell. Isso funciona se o Claude Code rotear o comando através do Git Bash ou PowerShell:
Ou execute um script Bash diretamente quando o Git Bash está instalado:

Linhas de status de subagente

A configuração subagentStatusLine renderiza um corpo de linha personalizado para cada subagente mostrado no painel de agente abaixo do prompt. Use-a para substituir a linha padrão name · description · token count pela sua própria formatação.
O comando é executado uma vez por tick de atualização com todas as linhas de subagente visíveis passadas como um único objeto JSON em stdin. A entrada inclui os campos de hook base, um campo columns com a largura de linha utilizável e um array tasks. Cada tarefa tem id, name, type, status, description, label, startTime, model, effort, contextWindowSize, tokenCount, tokenSamples e cwd. O campo model por tarefa é o ID do modelo resolvido em que a tarefa é executada. contextWindowSize é a janela de contexto desse modelo em tokens, calculada da mesma forma que a context_window.context_window_size da linha de status principal, para que você possa renderizar uma porcentagem por linha a partir de tokenCount. Ambos os campos exigem Claude Code v2.1.205 ou posterior e são omitidos para uma tarefa cujo modelo ainda não foi resolvido. O campo effort por tarefa é o esforço de raciocínio definido para esse subagente, em seu frontmatter de definição ou na invocação individual. O valor é um dos strings de nível de esforço low, medium, high, xhigh ou max, ou um orçamento de token numérico. O campo relata o valor configurado conforme escrito: se o modelo não suportar esse nível, o esforço que Claude Code realmente aplica pode ser diferente. O campo exige Claude Code v2.1.214 ou posterior e está ausente quando o subagente herda o nível de esforço da sessão. Escreva uma linha JSON para stdout por linha que você queira substituir, na forma {"id": "<task id>", "content": "<row body>"}. A string content é renderizada como está, incluindo cores ANSI e hiperlinks OSC 8. Omita o id de uma tarefa para manter a renderização padrão para essa linha; emita uma string content vazia para ocultá-la. Os mesmos portões de confiança, disableAllHooks e allowManagedHooksOnly que se aplicam a statusLine se aplicam aqui. Plugins podem enviar um subagentStatusLine padrão em seu settings.json, mas diferentemente de hooks, valores de plugin não são executados sob allowManagedHooksOnly mesmo quando o plugin é forçadamente ativado nas configurações gerenciadas enabledPlugins.

Dicas

  • Teste com entrada simulada: echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh
  • Mantenha a saída curta: a barra de status tem largura limitada, então saída longa pode ser truncada ou quebrada de forma estranha
  • Cache de operações lentas: seu script é executado frequentemente durante sessões ativas, então comandos como git status podem causar atraso. Consulte o exemplo de cache para saber como lidar com isso.
Projetos comunitários como ccstatusline e starship-claude fornecem configurações pré-construídas com temas e recursos adicionais.

Solução de problemas

Linha de status não aparecendo
  • Verifique se seu script é executável: chmod +x ~/.claude/statusline.sh
  • Verifique se seu script produz saída para stdout, não stderr
  • Execute seu script manualmente para verificar se produz saída
  • No Windows com Git Bash instalado, barras invertidas no caminho command provavelmente estão sendo consumidas como caracteres de escape antes do script ser executado. Use barras normais no caminho. Veja Configuração do Windows.
  • Se disableAllHooks estiver definido como true fora das configurações gerenciadas após a precedência de configurações ser aplicada, o Claude Code executa apenas um statusLine das configurações gerenciadas, e sem um statusLine gerenciado a linha de status fica desabilitada. Remova a configuração ou defina-a como false no arquivo que a define para reabilitar. Veja disableAllHooks.
  • Se sua organização define allowManagedHooksOnly nas configurações gerenciadas, sua linha de status personalizada desaparece sem aviso: você só pode obter uma linha de status de um valor statusLine nessas configurações gerenciadas. Veja o que é executado sob allowManagedHooksOnly para o comportamento completo, e pergunte ao seu administrador se essa configuração se aplica a você.
  • Execute claude --debug para registrar o stderr do seu script em cada invocação de linha de status e seu código de saída na primeira invocação em uma sessão
  • Peça ao Claude para ler seu arquivo de configurações e executar o comando statusLine diretamente para descobrir erros
Linha de status mostra -- ou valores vazios
  • Os campos podem ser null antes da primeira resposta de API ser concluída
  • Trate valores nulos em seu script com fallbacks como // 0 em jq
  • Reinicie o Claude Code se os valores permanecerem vazios após várias mensagens
Porcentagem de contexto mostra valores inesperados
  • Use used_percentage para o estado de contexto mais simples e preciso
  • A porcentagem de contexto pode diferir da saída /context devido a quando cada uma é calculada
Links OSC 8 não clicáveis
  • Verifique se seu terminal suporta hiperlinks OSC 8 (iTerm2, Kitty, WezTerm)
  • Terminal.app não suporta links clicáveis
  • Se o texto do link aparecer mas não for clicável, o Claude Code pode não ter detectado suporte a hiperlink em seu terminal. Defina a variável de ambiente FORCE_HYPERLINK para substituir a detecção antes de iniciar o Claude Code:
    No PowerShell, defina a variável na sessão atual primeiro:
  • Sessões SSH e tmux podem remover sequências OSC dependendo da configuração
  • Se sequências de escape aparecerem como texto literal como \e]8;;, use printf '%b' em vez de echo -e para manipulação de escape mais confiável
Falhas de exibição com sequências de escape
  • Sequências de escape complexas (cores ANSI, links OSC 8) podem ocasionalmente causar saída corrompida se se sobrepuserem com outras atualizações da interface
  • Se você vir texto corrompido, tente simplificar seu script para saída de texto simples
  • Linhas de status de múltiplas linhas com códigos de escape são mais propensas a problemas de renderização do que texto simples de linha única
Confiança do espaço de trabalho necessária
  • Como statusLine executa um comando de shell, o Claude Code o executa sob a mesma regra de confiança do espaço de trabalho que hooks em arquivos de configurações. Aceitar o diálogo para a pasta, ou para um diretório pai cuja confiança se estende a ela, é suficiente.
  • Até então, a linha de status permanece em branco, e claude --debug registra Status line command skipped: workspace trust not accepted. Reinicie o Claude Code e aceite o diálogo de confiança para habilitá-lo.
Erros de script ou travamentos
  • Scripts que saem com códigos diferentes de zero ou não produzem saída fazem a linha de status ficar em branco
  • Scripts lentos bloqueiam a linha de status de atualizar até que sejam concluídos. Mantenha scripts rápidos para evitar saída obsoleta.
  • Se uma nova atualização for acionada enquanto um script lento está em execução, o script em andamento é cancelado
  • Teste seu script independentemente com entrada simulada antes de configurá-lo
Notificações compartilham a linha de status Fora da renderização em tela cheia, o Claude Code mostra notificações na mesma linha que sua linha de status. Na renderização em tela cheia, o Claude Code oferece às notificações uma linha própria.
  • Notificações do sistema como erros de servidor MCP e atualizações automáticas são exibidas no lado direito da linha. Notificações transitórias como o aviso de contexto baixo também circulam por esta área.
  • Habilitar modo verbose adiciona um contador de tokens a esta área
  • Em terminais estreitos, essas notificações podem truncar sua saída de linha de status