Ferramenta Monitor do Claude Code

Problema: Até este mês, tudo o que corria em segundo plano era opaco para o Claude Code. Um comando lançado com run_in_background devolvia exatamente uma notificação no final. Nada pelo caminho. A solução era /loop ou uma tarefa agendada, o que significava disparar um novo prompt a cada poucos minutos e pagar por uma chamada completa à API só para perguntar se algo tinha realmente mudado.

Ganho Rápido: Aponta o Claude para o teu servidor de dev e deixa-o ouvir. Uma frase chega:

Start my dev server and monitor it for errors

O Claude arranca o servidor, envolve a sua saída num observador em segundo plano, e fica em silêncio até algo realmente quebrar. Sem tokens gastos enquanto nada acontece.

O Que Mudou

A Anthropic lançou a ferramenta Monitor a 9 de abril de 2026. O PM do Claude Code Noah Zweben anunciou assim: "O Claude consegue agora seguir logs para erros, fazer polling de PRs via script, e mais. Grande poupança de tokens e ótima forma de deixar de fazer polling no loop do agente."

A mudança fundamental é de um gatilho de relógio para um gatilho de evento. O modelo antigo tinha o Claude a espreitar o estado num temporizador. O novo modelo tem o Claude a acompanhar a saída, reagindo quando algo aparece. Pensa nisso como o mesmo salto que fazes quando deixas de bater numa base de dados a cada poucos segundos e começas a subscrever o seu stream de mudanças. O modelo de temporizador gasta compute no nada. O modelo de stream reage instantaneamente quando uma mudança chega.

Mecanicamente, a ferramenta é simples. O Claude corre um comando de shell e trata o seu stdout como um fluxo de eventos. Cada linha acorda a sessão principal. Um comando silencioso não custa nada. Assim que o teu filtro corresponde a uma linha, essa linha entra na conversa e o Claude começa a trabalhar nela. O processo subjacente continua a correr em paralelo.

Como Funciona

Cada monitor tem quatro parâmetros:

command é onde vive a lógica. Uma linha de stdout equivale a uma notificação. Se várias linhas saírem dentro de uma janela de 200 milissegundos, são agrupadas num único alerta, para que a saída multi-linha de um evento real ainda seja lida como uma coisa. O stderr é redirecionado para um ficheiro que podes ler depois e não acorda o Claude.

Usa persistent: true quando o monitor deve viver tanto quanto a tua sessão. Observadores de servidor de dev, tailers de log, monitores de PR. Para qualquer coisa limitada, como um único deploy ou uma execução de testes, passa timeout_ms e o monitor morre quando a janela fecha.

Duas Formas de Monitores

Filtros de stream observam saída contínua e mostram as linhas correspondentes:

# Watch application logs for errors
tail -f /var/log/app.log | grep --line-buffered "ERROR"
 
# Watch file system changes
inotifywait -m --format '%e %f' /watched/dir
 
# Node script that emits events from a WebSocket
node watch-for-events.js

Filtros de poll-and-if verificam uma fonte num intervalo e emitem quando as condições mudam:

# Poll GitHub PR for new comments every 30 seconds
last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  gh api "repos/owner/repo/issues/123/comments?since=$last" \
    --jq '.[] | "\(.user.login): \(.body)"'
  last=$now; sleep 30
done

Ambas as formas seguem o mesmo contrato. Stdout é um stream de eventos. Silêncio significa nada a reportar. O Claude continua a trabalhar no que pediste a seguir enquanto o monitor fica ativo em segundo plano.

A Matemática dos Tokens

Imagina /loop a verificar uma suite de testes a cada 2 minutos durante uma execução de 10 minutos. Isso dá 5 chamadas completas à API. Recarregamento de contexto, processamento de prompt, geração de resposta, cada vez. Pagas por 5 idas e voltas e 4 delas não devolvem nada útil.

Um monitor inverte essa equação. O Claude segue a saída filtrada do test runner. Quando o teste #23 falha ao minuto 4, a linha de falha chega à sessão imediatamente. O Claude pode começar a trabalhar na correção enquanto os testes 24 a 47 ainda estão a correr. Nada desperdiçado. Nada atrasado. Quanto mais longo o fluxo de trabalho, maior a poupança. Qualquer coisa de longa duração ganha aqui, incluindo execuções de CI que demoram horas, trabalhos de deploy, e builds noturnas.

Casos de Uso Práticos

Captura de erros do servidor de dev. Observa um servidor de dev Next.js ou Vite e recebe uma notificação no instante em que aparece um erro de build ou um loop de crash. Percorrer a saída antiga do terminal à procura do ponto de quebra desaparece.

Triagem de suite de testes. Um teste falhado aparece no instante em que falha. O Claude pode abrir uma correção enquanto o resto da suite ainda está a correr.

Observação de pipeline de deploy. Anexa um filtro ao teu stream de CI/CD e acorda o Claude em falhas, em avisos, ou quando uma determinada fase de deployment termina.

Polling de revisão de PR. Senta-se num pull request do GitHub e reage a novos comentários, pedidos de revisão, ou verificações de estado assim que chegam. Cada novo comentário torna-se algo com que o Claude pode trabalhar imediatamente.

Monitorização de logs. Aponta um filtro para os teus logs de produção ou staging. Sempre que uma linha corresponde ao padrão, chega à sessão como um evento e o Claude pode responder de imediato.

Três Regras para Bons Monitores

1. Nunca pipes através de grep sem --line-buffered. Sem essa flag, o buffering de pipe pode reter eventos durante minutos. De longe o tropeção mais frequente.

2. Engole falhas transitórias dentro de loops de poll. Acrescenta || true a cada chamada de API para que uma má volta de rede não deite abaixo o monitor inteiro.

3. Mantém o stdout conciso. Cada linha que emites torna-se uma mensagem dentro da conversa. Um observador que emite demasiados eventos é parado automaticamente pelo Claude Code. Filtra sempre os logs brutos antes de os pipar. Nunca despejas um stream completo sem filtrar.

# Good: selective filter
tail -f app.log | grep --line-buffered "ERROR\|WARN\|FATAL"
 
# Bad: firehose that will auto-stop
tail -f app.log

Os intervalos de poll também importam. 30 segundos ou mais para qualquer coisa remota, porque os limites de taxa se aplicam. 0,5 a 1 segundo funciona bem para verificações locais.

Monitor vs. Hooks vs. Tarefas Agendadas

Existem agora três camadas de automação dentro do Claude Code, e cada uma ouve um tipo diferente de gatilho.

Os hooks acordam com as próprias ações do Claude, coisas como uma edição de ficheiro ou um commit. As tarefas agendadas acordam com o relógio. O Monitor acorda com o mundo exterior. As configurações mais fortes têm todas as três em camadas. As guardrails ficam nos hooks, a manutenção periódica fica nas tarefas agendadas, e a observabilidade ao vivo de tudo o resto fica no monitor.

Monitor vs. run_in_background

As pessoas misturam estes dois. Ambos executam coisas em segundo plano. A diferença é o modelo de feedback.

run_in_background é disparar e esquecer. Recebes exatamente uma notificação quando o comando termina. Nada pelo meio. Bom para "corre este build e diz-me quando terminar."

Um monitor é um stream ao vivo em vez disso. Uma notificação dispara para cada evento correspondente pelo caminho. Bom para "corre este build e diz-me no instante em que algo corre mal." O Claude mantém-se reativo enquanto o processo ainda está a correr, não apenas depois de terminar.

Próximos Passos

• Aprende como os hooks complementam os monitores ao validar as próprias ações do Claude
• Explora loops de agentes autónomos onde os monitores fornecem o sinal de feedback
• Lê sobre gestão de contexto para manter eficientes as sessões monitorizadas de longa duração
• Vê as tarefas agendadas para automação baseada em tempo que se combina com monitorização orientada a eventos
• Experimenta loops de feedback para apertar o ciclo entre escrever código e apanhar problemas

A ferramenta Monitor ocupa o slot em falta entre "o Claude executa coisas" e "o Claude observa coisas." O trabalho em segundo plano costumava ser uma caixa selada que só se abria no final. Hoje o Claude senta-se ao lado do processo, reagindo ao que merece atenção e mantendo as mãos afastadas do que não merece. Programação a pares de uma forma genuinamente diferente.