Como acompanhar uma orquestração de agentes que roda por horas sem ficar de babá?

Fala aí, beleza? Você dispara uma orquestração que vai levar horas, olha o relógio, olha o terminal, e percebe que acabou de virar vigia noturno da própria máquina

O problema não é a run demorar

O problema é que execução longa não precisa de vigia, precisa de três coisas em ordem: rastro durante o processo, sinal de vida que dá pra verificar e aviso no fim que chega até você, sem você ir buscar

Aqui a gente monta esse acompanhamento dentro do Claude Code usando só o que já existe na ferramenta: sessão em segundo plano, transcripts em disco, hooks, monitores, tarefas agendadas e push no celular

Bora ver na prática?

O que você precisa antes de começar

Lista curta, tudo verificável antes de você disparar qualquer coisa:

• Claude Code atualizado: workflows dinâmicos exigem a versão v2.1.154 ou posterior, e estão disponíveis em todos os planos pagos, com acesso à API da Anthropic, e também no Amazon Bedrock, Google Cloud Agent Platform e Microsoft Foundry
• Acesso ao ~/.claude/settings.json, que é onde moram os hooks e a status line (se você usa CLAUDE_CONFIG_DIR, a raiz muda pra onde a variável apontar)
• App Claude no celular, iOS ou Android, com a MESMA conta e organização que você usa no terminal, caso queira notificação push
• Agent teams é experimental e vem desligado por padrão, só liga com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 no settings.json ou no ambiente

Passo a passo: colocando a orquestração para rodar em segundo plano

1. Manda a conversa atual pro fundo com /bg

O comando (forma completa /background) joga a sessão atual pra uma sessão em segundo plano e libera o teu terminal na hora. Se o Claude estiver no meio de uma resposta, ela continua rodando lá na sessão de fundo

   /bg
   /bg run the test suite and fix any failures

Repara que ele aceita instrução extra no mesmo comando, então dá pra mandar pro fundo JÁ dizendo o que fazer

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O erro comum deste passo: achar que sair do terminal mata tudo. Quando ainda existe trabalho rodando em segundo plano (subagentes, comandos de shell, workflows ou monitores), o Claude Code mostra o diálogo "Background work is running" em vez de encerrar na hora

2. Já começa em segundo plano pelo shell, e dá nome

   claude --bg "<prompt>"
   claude --bg --name "flaky-test-fix" "<prompt>"

O --name define o nome de exibição da sessão no agent view no lugar do nome gerado automaticamente

O erro comum deste passo: disparar três runs longas sem nomear nenhuma, e depois tentar adivinhar qual é qual numa lista de nomes automáticos

3. Ctrl+B pra mandar uma execução de Bash específica pro fundo

Não é a sessão inteira, é aquele comando que trava tudo. A saída vai pra arquivo, cada tarefa recebe um ID único e o Claude recupera esse conteúdo depois com a ferramenta Read

Tá no tmux? Aperta duas vezes, por causa da prefix key

O erro comum deste passo: esquecer que tarefa em segundo plano é encerrada se a saída passar de 5GB (ele deixa uma nota no stderr explicando) e que elas são limpas automaticamente quando o Claude Code encerra. Se por algum motivo você não quiser o recurso, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 desativa

4. Workflows dinâmicos quando a orquestração é grande de verdade

Aqui muda o jeito de pensar: em vez de o modelo segurar tudo na cabeça, você tem um script JavaScript que orquestra subagentes em escala, executado por um runtime em segundo plano enquanto a sessão continua responsiva

O script guarda o loop, a ramificação e os resultados intermediários, então o contexto do Claude fica só com a resposta final. O progresso você acompanha em /workflows

O erro comum deste passo: tentar isso numa instalação antiga. Confere a versão, porque abaixo da v2.1.154 o recurso não existe

O que registrar durante o processo (para não depender da tela)

A regra é simples: se o único lugar onde a informação existe é a tela que você está olhando, você virou o log da operação

1. Os transcripts já estão em disco, no formato JSONL

Uma linha por evento, cada linha é um objeto JSON de mensagem, chamada de ferramenta ou resultado:

   ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl

E o encoded-cwd? É o diretório absoluto com todo caractere não alfanumérico trocado por hífen, então /Users/me/proj vira -Users-me-proj

Cada subagente tem transcript próprio, em arquivo separado:

   ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

Se você usa CLAUDE_CONFIG_DIR, a raiz troca junto

2. Sabe qual arquivo ler quando o hook disparar

Nos hooks, transcript_path aponta pro transcript da sessão PRINCIPAL, enquanto agent_transcript_path aponta pro transcript do próprio subagente, aquele que fica na pasta subagents/ aninhada

O erro comum deste passo: logar o caminho errado e depois ficar procurando a etapa do subagente dentro do transcript do agente principal

3. Status line personalizada como painel ao vivo

O script recebe um JSON pelo stdin e devolve a linha que você quiser ver. O JSON traz model.display_name, workspace.current_dir, context_window.used_percentage e session_id

   #!/bin/bash
   input=$(cat)
   model=$(echo "$input" | jq -r '.model.display_name')
   dir=$(echo "$input" | jq -r '.workspace.current_dir')
   ctx=$(echo "$input" | jq -r '.context_window.used_percentage')
   echo "$model | $dir | contexto ${ctx}%"

Salva (por exemplo em ~/.claude/statusline.sh), dá permissão e aponta o caminho no ~/.claude/settings.json com type command:

   chmod +x ~/.claude/statusline.sh

Tome cuidado com a leitura do número: o used_percentage é calculado só com tokens de ENTRADA (input_tokens + cache_creation_input_tokens + cache_read_input_tokens). O session_id é estável durante a sessão e único por sessão, o que faz dele uma chave ótima pra amarrar log com transcript

4. Telemetria por OpenTelemetry pra quem quer histórico de verdade

   export CLAUDE_CODE_ENABLE_TELEMETRY=1
   export OTEL_METRICS_EXPORTER=otlp
   export OTEL_LOGS_EXPORTER=otlp

Os exportadores aceitam opções como otlp, prometheus ou console, e o endpoint OTLP é configurável

E como saber se está exportando mesmo? Procura no teu backend a métrica claude_code.session.count, que é emitida no início de cada sessão com o atributo start_type valendo fresh, resume, continue ou agents_view. Pra logs, procura o evento claude_code.user_prompt

Quer ler consumo? claude_code.token.usage pode ser quebrada por type (input/output), usuário, time, modelo, skill.name, plugin.name ou agent.name

O erro comum deste passo: ligar registro só no fim da run. Aí quando ela quebra no meio, você não tem NADA pra reconstituir o que aconteceu

Por que estado salvo não prova que o processo ainda está vivo

Essa é a parte que mais engana gente experiente, então vamos por partes

O sintoma:

O transcript tem linhas, o workflow mostra uma etapa "em curso", a sessão aparece bonitinha na lista

E nada avança há uma hora

A causa:

Arquivo e registro são fotografia do último evento gravado, não batimento cardíaco

Se o processo morreu, ele morreu sem escrever mais nada. O último estado salvo continua lá, intacto, dizendo "em curso" pra sempre. Estado no disco responde "o que aconteceu por último", nunca "está rodando agora"

A solução, com o que a ferramenta já dá:

• Lê o agent view: ele mostra todas as sessões e agrupa por estado, colocando no topo as que precisam de você. "Ready for review" e "Needs input" ficam acima de "Working" e "Completed". A sessão vai pra Ready for review quando tem pull request aberto, e o Completed junta concluídas, falhas e paradas (repara: falha e sucesso moram no mesmo grupo, então "Completed" NÃO quer dizer "deu certo")
• Ctrl+O abre o modo transcript quando você está anexado a uma sessão, uma visão rolável da conversa. É ali que dá pra ver movimento real, não estado congelado
• Ctrl+T fixa a sessão no topo e mantém o processo rodando enquanto ela está ociosa
• Ctrl+S agrupa por diretório, ótimo quando você tem run de três projetos ao mesmo tempo
• Ctrl+X para a sessão, e Ctrl+X de novo em até dois segundos apaga. Cuidado com o dedo rápido aí 😅

Como prevenir:

Prefira sinal que CHEGA até você (hook, push, monitor) em vez de sinal que você precisa ir buscar

E tem um detalhe de ambiente que explica muito "sumiço" misterioso: no macOS e no Linux, o Claude Code encerra tarefas em segundo plano quando o sistema operacional sinaliza pressão de memória, desde que a sessão esteja ociosa há pelo menos 30 minutos e nada esteja rodando (nenhum turno, nenhum subagente)

Ou seja, a tua máquina participa da equação. É o mesmo raciocínio de quem quer deixar o n8n rodando 24 horas sem depender do PC ligado: processo longo em máquina pessoal é sempre um acordo, não uma garantia

Como ser avisado quando terminar (ou quando travar pedindo input)

Agora a parte que devolve a tua tarde 😀

1. Hook Stop para o fim do turno do agente principal

Ele roda quando o agente principal termina de responder, e recebe campos próprios no input: stop_hook_active e last_assistant_message, além dos campos comuns

Esse last_assistant_message é ouro pra notificação: dá pra mandar pro teu canal preferido já com o resumo do que o agente falou por último

2. Hook SubagentStop pra logar etapa por etapa

Dispara quando um subagente termina e devolve o controle ao agente principal. O input inclui hook_event_name valendo SubagentStop, mais agent_id, agent_transcript_path, agent_type e stop_hook_active

Numa orquestração longa esse é o teu registro de progresso REAL: cada subagente que fecha vira uma linha no teu log, com o caminho do transcript dele junto

3. Hook Notification pro caso que mais trava run de horas

Ele dispara quando o Claude Code está esperando input ou permissão, e é configurado no ~/.claude/settings.json. Com o matcher vazio, ele dispara em todos os tipos de notificação

Pensa na cena clássica: você sai pra almoçar achando que a run está avançando, e ela está parada há 40 minutos esperando você aprovar uma permissão. Esse hook mata exatamente esse desperdício

O erro comum deste passo: escrever um hook que responde ao Stop e reinicia trabalho sem checar o stop_hook_active. Esse campo é verdadeiro quando o Claude Code já está continuando por causa de um stop hook, e existe justamente pra você não entrar em execução indefinida. Checa ele (ou processa o transcript) antes de mandar continuar

4. Push no celular com Remote Control

Com o Remote Control ativo, o Claude envia notificação push pro teu celular, tipicamente quando uma tarefa longa termina ou quando ele precisa de uma decisão

O caminho é esse:

– instala o app Claude para iOS ou Android com a mesma conta e organização que você usa no terminal – aceita a permissão de notificação do sistema – roda /config e habilita "Push when Claude decides" e/ou "Push when actions required"

Também dá pra pedir direto no prompt, tipo "notify me when the tests finish"

Caso apareça "No mobile registered" no /config: abre o app no celular pra atualizar o token, é isso mesmo

Vigia automático: monitores, tarefas agendadas e eventos que chegam sozinhos

Aviso é bom, mas às vezes você quer REAÇÃO, não recado

1. Ferramenta Monitor

Ela deixa o Claude observar algo em segundo plano e reagir quando muda, sem pausar a conversa

Na maioria dos casos ele escreve um script pequeno, roda em segundo plano e recebe cada linha de saída conforme ela chega. Se o servidor já empurra eventos, ele pode abrir um WebSocket em vez disso. Encerra quando você pede cancelamento ou quando a sessão termina

Detalhe importante de segurança: o Monitor usa as MESMAS regras de permissão do Bash, então nada de comando mágico passando por fora do teu controle

2. Monitores de fundo declarados por plugin

Plugins podem declarar background monitors que o Claude Code inicia sozinho quando o plugin está ativo. Eles observam logs, arquivos ou status externo e avisam o Claude conforme os eventos chegam

A diferença pro item anterior: aqui você não precisa mandar o Claude começar a observar, já sobe junto

3. Tarefas agendadas com /loop e as ferramentas de cron

Servem pra repetir um prompt automaticamente em intervalo: monitorar deploy, acompanhar PR, checar build longo

O CronCreate aceita expressão cron de 5 campos (minuto, hora, dia do mês, mês, dia da semana), com curinga , valor único, passo /15, intervalo 1-5 e lista separada por vírgula. O CronList mostra ID, agenda e prompt, e o CronDelete cancela por ID

Agora a ressalva que evita frustração: essas tarefas têm escopo de sessão. Elas vivem na conversa atual e param quando você começa outra. Pra trazer de volta as que não expiraram, retoma com --resume ou --continue

E se você não informar intervalo, o Claude escolhe sozinho um atraso entre um minuto e uma hora a cada iteração

4. Channels, quando o evento vem de fora

Channels são um servidor MCP que empurra eventos pra dentro de uma sessão em execução, permitindo que o Claude reaja a coisas que acontecem enquanto você nem está no terminal

Podem ser de mão dupla, ou seja, o Claude lê o evento e responde pelo mesmo canal. Os usos citados na documentação são ponte de chat via Telegram, Discord ou iMessage, e recebimento de webhooks de CI, rastreador de erros ou pipeline de deploy

Só lembrando o estado: research preview, exige autenticação Anthropic via claude.ai ou chave de API do Console, e não está no Amazon Bedrock, Google Cloud Agent Platform nem Microsoft Foundry

Três cenários de execução longa e o arranjo certo para cada um

Não existe arranjo único, existe arranjo que combina com o formato da tua run

(a) A run que só precisa avisar no fim

Dispara com claude --bg --name "<nome>" "<prompt>", liga o hook Stop e deixa o push do Remote Control ativo

Você fecha a aba mental do assunto e o celular te chama quando acabou. Simples assim

(b) A orquestração com muitas etapas

Aqui o valor não é o aviso final, é ver o progresso e poder retomar

Cada execução de workflow grava o script em arquivo (sob o diretório da sessão em ~/.claude/projects/) e o runtime rastreia o resultado de cada agente, o que torna a run retomável dentro da mesma sessão. Ao retomar, os agentes já concluídos costumam devolver resultado em cache e o restante roda ao vivo

Junta com o hook SubagentStop e você ganha log etapa por etapa, com agent_type e agent_transcript_path de cada um. O acompanhamento visual fica no /workflows

(c) O trabalho que espera evento externo

CI, deploy, rastreador de erro, aquele pipeline que decide o teu dia

Aqui é Monitor (se você quer observar e reagir), tarefa agendada com cron (se é uma checagem repetida) ou Channels (se o sistema lá fora consegue empurrar webhook pra dentro da sessão)

Se a tua orquestração vive fora do terminal, o raciocínio é o mesmo que aparece na orquestração de agentes no n8n: quem dispara, quem observa e quem avisa precisam ser papéis separados

E os agent teams?

É um caminho diferente, vale citar: agent teams coordenam várias instâncias do Claude Code, com uma sessão como líder e teammates que têm contexto próprio e conversam entre si

Eles compartilham uma lista de tarefas, reivindicam trabalho e se comunicam diretamente, o que é bem diferente de subagentes, que só reportam ao agente principal. A exibição pode ser in-process (todos no mesmo terminal) ou split panes (um painel por teammate)

Só não esquece: é experimental e vem desligado por padrão, liga com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Conclusão

Acompanhar orquestração de agentes que roda por horas não é ficar de babá, é montar três camadas na ordem certa: rastro durante o processo, sinal de vida que dá pra verificar e aviso que chega até você

E a lição que mais economiza tempo é aquela do meio do post: estado salvo é fotografia do último evento, nunca prova de processo vivo

Próximo passo pequeno pra fazer hoje: bota a tua próxima tarefa longa em /bg com --name, liga o hook Notification e o hook Stop no settings.json, e confere o agent view uma vez por hora em vez de encarar o terminal

Aí me conta nos comentários qual sinal funcionou melhor no teu fluxo: hook, push ou monitor?

Até o próximo post! 😀