Executando Código Claude em um Loop: O Script que o Torna um Agente Persistente

Claude Code é construído para sessões interativas. Você digita, ele age, a conversa termina. Essa é a forma certa para um desenvolvedor em um teclado. É a forma errada para um agente que precisa ficar de olho em algo. Uma fila. Uma caixa de entrada. Um arquivo. Um webhook. Um serviço remoto.

Para transformar Claude Code em um trabalhador persistente, você o envolve em um loop. Este post é o wrapper.

Começarei com a versão de shell de quinze linhas que faz você rodar em um minuto, depois passarei pela versão persistente stream-json que você realmente deseja para qualquer coisa além de uma demonstração. O script completo está no final.

Por que não apenas iniciar claude -p a cada tick?

A forma ingênua de um agente de polling é iniciar um novo processo claude -p a cada tick, enviar um prompt, ler a saída e sair. Funciona em um quadro branco. Na prática, o custo de cold-start é brutal:

• Os servidores MCP fazem handshake ao iniciar. Um custo de vários segundos a cada tick, toda vez.
• CLAUDE.md e o catálogo de habilidades precisam ser relidos e recacheados.
• Transcrições de sessão se fragmentam em arquivos pequenos que são difíceis de entender.
• Um intervalo de polling de 20 segundos se torna 30 segundos com o imposto de cold-start.

Uma sessão persistente mantém tudo quente. Um processo claude por agente, stdin aberto, ticks se tornam eventos de envio de prompt do usuário contra uma sessão já carregada.

A versão de quinze linhas

Quando você só quer ver o loop funcionar:

#!/usr/bin/env bash
# agent-loop.sh
set -euo pipefail

INTERVAL="${INTERVAL:-60}"
TICK_PROMPT="Chame list_dms. Para cada mensagem não lida, leia_dm, faça o trabalho e depois responda com send_dm. Caixa de entrada vazia? Saia silenciosamente."

while true; do
  echo "[$(date +%H:%M:%S)] tick"
  claude -p \
    --mcp-config .mcp.json --strict-mcp-config \
    --dangerously-skip-permissions \
    "$TICK_PROMPT"
  sleep "${INTERVAL}"
done

Faça-o executável, execute-o. Esse é um agente funcionando.

Algumas coisas que vale a pena destacar antes de prosseguirmos, porque se aplicam tanto à versão simples quanto à persistente:

O TICK_PROMPT é o coração do script. Faça-o imperativo e nomeie as ferramentas que você deseja chamar. Não escreva "siga seu CLAUDE.md". Escreva "chame list_dms" ou "remova um trabalho da fila com queue_pop". CLAUDE.md é para contexto. O prompt do tick é para a ação que você deseja que este tick execute.

O reset entre os ticks é o que torna o loop confiável. Cada tick da versão simples é um processo novo, então a rodada anterior está em outro universo. O que o novo prompt nomeia é o que o agente faz. Sem esse reset, um agente que termina uma tarefa simplesmente fica lá esperando.

Escopo através de .mcp.json. --dangerously-skip-permissions é aceitável porque não há humano neste terminal, mas o agente ainda tem apenas as ferramentas que você lhe dá através do MCP. Escolha-as com cuidado.

A versão simples custa vários segundos de cold-start por tick e re-estabelece handshake com cada servidor MCP. Para polling de um minuto, está tudo bem. Para responsividade de sub-segundo, você quer a versão persistente.

A versão persistente: stream-json em stdin e stdout

A CLI do Claude suporta um modo stream-json onde cada mensagem do usuário é uma linha JSON em stdin e cada evento é uma linha JSON em stdout. O wrapper inicia claude uma vez e alimenta prompts para sempre.

A invocação:

claude --print --verbose \
       --input-format stream-json --output-format stream-json \
       --include-partial-messages \
       --dangerously-skip-permissions \
       --mcp-config .mcp.json --strict-mcp-config

Flags que importam:

• --print: não interativo, sem TTY.
• --input-format stream-json: cada mensagem do usuário é uma linha JSON em stdin.
• --output-format stream-json: cada evento (inicialização do sistema, delta do assistente, uso de ferramenta, resultado) é uma linha JSON em stdout.
• --include-partial-messages: mantenha deltas consultáveis caso você queira elas depois.
• --dangerously-skip-permissions: sem humano para aprovar. Escopo através de .mcp.json em vez disso.
• --strict-mcp-config: falhe ruidosamente quando .mcp.json estiver malformado.

Framing de stdin e stdout

Entrada. Uma linha JSON por mensagem do usuário:

{"type": "user", "message": {"role": "user", "content": "<prompt>"}}

Saída. Três tipos de eventos são importantes para o loop:

• {"type": "system", "subtype": "init", "session_id": "<uuid>"} capturado uma vez por spawn. Usado para --resume <uuid> na recuperação de falhas.
• {"type": "result", ...} a rodada está completa. O wrapper para de esperar e o tick retorna.
• {"type": "__eof__"} sentinela que o wrapper enfileira quando stdout fecha. Aciona um respawn.

Todos os outros tipos de eventos (uso de ferramenta, mensagens parciais, deltas de conteúdo) são drenados ou apresentados conforme necessário.

/clear entre tarefas concluídas

A história da conversa se acumula dentro da sessão persistente. Se deixada sem controle, isso incha a cada tick e custa tokens. A solução é o comando de barra /clear. Envie-o como uma mensagem do usuário entre unidades de trabalho concluídas. Ele descarta a conversa, mas mantém os servidores MCP, habilidades e o CLAUDE.md analisado carregados.

O padrão: o agente toca um arquivo de controle (.orchestrator/clear-session) quando termina uma tarefa. O wrapper verifica esse arquivo antes de cada tick. Se presente, ele envia /clear primeiro, e depois desvincula o arquivo. O mesmo efeito do reset de cold-start na versão simples.