- 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
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.

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:
Configure manualmente uma linha de status
Adicione um campostatusLine à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.
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:
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ê.
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 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.
~/.claude/settings.json, que define type como "command" (significando “execute este comando de shell”) e aponta command para seu script: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
/compacttermina- O modo de permissão muda
- O modo Vim alterna
- Você altera o
commandnas suas configurações destatusLine - Um temporizador
refreshIntervaldecorre, 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
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
- Múltiplas linhas: cada instrução
echoouprinté exibida como uma linha separada. Consulte o exemplo de múltiplas linhas. - Cores: use códigos de escape ANSI como
\033[32mpara verde (o terminal deve suportá-los). Consulte o exemplo de status do git. - Links: use sequências de escape OSC 8 para tornar o texto clicável (Cmd+clique no macOS, Ctrl+clique no Windows/Linux). Requer um terminal que suporte hiperlinks como iTerm2, Kitty ou WezTerm. Consulte o exemplo de links clicáveis.
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:Esquema JSON completo
Esquema JSON completo
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--nameou/rename, ou uma vez que um título de sessão gerado por IA existe. O nome de exibição padrão, comomy-app-3f, não popula este campoprompt_id: aparece apenas após a primeira entrada do usuárioworkspace.git_worktree: aparece apenas quando o diretório atual está dentro de uma git worktree vinculadaworkspace.repo: aparece apenas dentro de um repositório git com um remoteoriginconfiguradoeffort: aparece apenas quando o modelo atual suporta o parâmetro de esforço de raciocíniovim: aparece apenas quando o modo vim está habilitadoagent: aparece apenas ao executar com a flag--agentou configurações de agente configuradaspr: 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_stateepr.kindpodem estar independentemente ausentesworktree: aparece apenas enquanto a sessão está em uma sessão de worktree. Quando presente,brancheoriginal_branchtambém podem estar ausentes para worktrees baseadas em hookrate_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 temporesets_atpassa. Usejq -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
null:context_window.current_usage:nullantes da primeira chamada de API em uma sessão, e novamente após/compactaté que a próxima chamada de API a repopulecontext_window.used_percentage,context_window.remaining_percentage: podem sernullno início da sessão
Campos de janela de contexto
O objetocontext_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 deinput_tokens,cache_creation_input_tokensecache_read_input_tokens;total_output_tokenssão os tokens de saída da resposta mais recente. Ambos são0antes 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.
current_usage contém:
input_tokens: tokens de entrada no contexto atualoutput_tokens: tokens de saída geradoscache_creation_input_tokens: tokens escritos no cachecache_read_input_tokens: tokens lidos do cache
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 objetoprompt_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 objetolast_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_addedetools_removed: comtools_changed, quantas ferramentas foram adicionadas ou removidas da solicitaçãosystem_char_delta: comsystem_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:- Salve o script em um arquivo como
~/.claude/statusline.sh(ou.py/.js) - Torne-o executável:
chmod +x ~/.claude/statusline.sh - Adicione o caminho às suas configurações
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 campoused_percentage e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:

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.

Rastreamento de custo e duração
Rastreie os custos de API e o tempo decorrido da sua sessão. O campocost.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:

Exibir múltiplas linhas
Seu script pode exibir múltiplas linhas para criar uma exibição mais rica.
print ou echo cria uma linha separada:
Links clicáveis
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.
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 objetorate_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 comogit 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 comoC:\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:
Linhas de status de subagente
A configuraçãosubagentStatusLine 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.
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 statuspodem causar atraso. Consulte o exemplo de cache para saber como lidar com isso.
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
commandprovavelmente estão sendo consumidas como caracteres de escape antes do script ser executado. Use barras normais no caminho. Veja Configuração do Windows. - Se
disableAllHooksestiver definido comotruefora das configurações gerenciadas após a precedência de configurações ser aplicada, o Claude Code executa apenas umstatusLinedas configurações gerenciadas, e sem umstatusLinegerenciado a linha de status fica desabilitada. Remova a configuração ou defina-a comofalseno arquivo que a define para reabilitar. VejadisableAllHooks. - Se sua organização define
allowManagedHooksOnlynas configurações gerenciadas, sua linha de status personalizada desaparece sem aviso: você só pode obter uma linha de status de um valorstatusLinenessas configurações gerenciadas. Veja o que é executado soballowManagedHooksOnlypara o comportamento completo, e pergunte ao seu administrador se essa configuração se aplica a você. - Execute
claude --debugpara 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
statusLinediretamente para descobrir erros
-- ou valores vazios
- Os campos podem ser
nullantes da primeira resposta de API ser concluída - Trate valores nulos em seu script com fallbacks como
// 0em jq - Reinicie o Claude Code se os valores permanecerem vazios após várias mensagens
- Use
used_percentagepara o estado de contexto mais simples e preciso - A porcentagem de contexto pode diferir da saída
/contextdevido a quando cada uma é calculada
- 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_HYPERLINKpara 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;;, useprintf '%b'em vez deecho -epara manipulação de escape mais confiável
- 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
- Como
statusLineexecuta 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 --debugregistraStatus line command skipped: workspace trust not accepted. Reinicie o Claude Code e aceite o diálogo de confiança para habilitá-lo.
- 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 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