Como rodar agentes do Claude Code em segundo plano

Cinco jeitos de rodar o Claude Code em segundo plano

Eles diferem no que precisa continuar rodando e em quem inicia o trabalho.

Tarefas em background dentro de uma sessão

Pressione Ctrl+B enquanto o Claude está rodando um comando Bash ou um subagente para mandá-lo para o background (duas vezes no tmux) e continue conversando com o Claude. O Claude também pode iniciar um comando em background por conta própria. Os subagentes que o Claude cria rodam em background por padrão.

Digite /tasks para listar os shells e subagentes em execução e acompanhá-los. Em uma sessão no terminal local, um comando em background não tem limite de tempo, mas para quando o Claude Code é encerrado. Para rodar vários agentes lado a lado, veja como rodar vários agentes do Claude Code.

Agent view: sessões que sobrevivem ao terminal

claude --bg "<prompt>" inicia uma sessão em background e retorna na hora; /bg manda para o background a sessão em que você está. Um processo supervisor as executa, então fechar o terminal não as interrompe, mas desligar ou reiniciar o computador, sim, e uma sessão ociosa e desanexada é encerrada depois de cerca de uma hora.

claude agents abre o agent view; claude attach <id>, claude logs <id> e claude stop <id> gerenciam uma sessão. O agent view é um research preview, então os comandos podem mudar.

Rode o Claude Code em modo headless com claude -p

1. Rode um prompt e saia

   -p (ou --print) roda o Claude Code sem a interface interativa e sai quando termina, com código de saída 0 em caso de sucesso. Você também pode enviar a entrada por pipe.

   claude -p "List the failing tests and why they fail"
   cat error.log | claude -p "Explain this error"

2. Obtenha uma saída que um script consiga ler

   --output-format json retorna o resultado com o ID da sessão e metadados, incluindo total_cost_usd, uma estimativa calculada na sua máquina. stream-json (com --verbose) transmite os eventos à medida que acontecem.

   claude -p "Summarize this repo" --output-format json | jq -r '.result'

3. Libere só as ferramentas de que ele precisa

   No modo headless, não há ninguém para aprovar um pedido de permissão. Desde a v2.1.302, uma execução sem modo definido começa em Manual e nega tudo o que precisaria de aprovação. Use --allowedTools para o que ele pode fazer e --permission-mode dontAsk para negar o resto em vez de ficar esperando.

   claude -p "Run the test suite and summarize failures" \
     --permission-mode dontAsk --allowedTools "Read,Bash(npm test)"

4. Limite a execução

   --max-turns para depois de um número de turnos do agente, e --max-budget-usd, ao atingir um custo estimado (pode passar um pouco). Os dois só funcionam com -p.

   claude -p "Fix the lint errors" --max-turns 15 --max-budget-usd 3

5. Continue a mesma conversa depois

   Guarde o ID da sessão da saída JSON e passe-o para --resume, ou use --continue para a sessão mais recente no diretório.

   id=$(claude -p "Start a code review of src/" --output-format json | jq -r '.session_id')
   claude -p "Now check the tests too" --resume "$id"

6. Agende com o cron

   A documentação da Anthropic não traz um exemplo de cron; este usa só flags documentadas. O cron tem um PATH mínimo, então use o caminho completo que which claude mostra e crie antes a pasta de logs. Não acrescente --bare aqui: ele ignora o login da sua assinatura e exige uma chave de API.

   # crontab -e: dias úteis às 9:00
   0 9 * * 1-5  cd /path/to/repo && /path/to/claude -p "Summarize yesterday's commits and list new TODO comments. Do not edit files." --permission-mode dontAsk --allowedTools "Read,Bash(git log *),Bash(git diff *)" --max-turns 10 --output-format json >> "$HOME/logs/claude-daily.log" 2>&1

Fonte: documentação da Anthropic sobre o modo headless

Permissões para execuções sem supervisão

• dontAsk mais uma lista em --allowedTools é a opção mais restrita: nega tudo o que não estiver na lista.
• auto deixa um classificador revisar cada ação no seu lugar. A Anthropic avisa que isso não garante segurança.
• acceptEdits aprova edições de arquivos e comandos simples de arquivo, mas não outros comandos de shell.
• bypassPermissions pula os pedidos de permissão e as verificações de segurança. A Anthropic recomenda usá-lo só em containers ou VMs isolados e sem acesso à internet, porque ele não oferece proteção contra prompt injection.
• Para regras que valem para todas as execuções de um projeto, coloque permissions.allow e permissions.deny em .claude/settings.json. As regras de negação sempre prevalecem.

Opções na nuvem: quando seu computador está desligado

• Sessões na nuvem: claude --cloud "<task>" roda na infraestrutura da Anthropic a partir da sua branch no GitHub e continua com o notebook fechado. Envie complementos com claude -p "..." --cloud <session-id>.
• Tarefas agendadas na nuvem: criadas com /schedule ou em claude.ai/code, rodam em horários definidos (no máximo uma vez por hora), a partir de uma chamada de API ou de eventos do GitHub. Planos Pro, Max, Ultra, Team e Enterprise; research preview.
• GitHub Actions: anthropics/claude-code-action@v1 com um gatilho schedule. Um token OAuth gerado com claude setup-token usa sua assinatura; uma chave de API é cobrada por token.

Dê um trabalho fixo a um agente em segundo plano

Tarefas em background, agent view e cron iniciam um trabalho que você já decidiu. O Crewmark dá a uma sessão do Claude Code um cargo contínuo: ela acorda com um heartbeat durante o horário de trabalho, pega a próxima tarefa de um quadro e manda mensagem para você quando trava.

1. Transforme uma sessão em funcionário

   Escolha um cargo e uma meta em números e rode no Claude Code o comando de configuração que o Crewmark fornece. Essa conversa vira o funcionário.

2. Deixe o heartbeat iniciar o trabalho

   O daemon do Crewmark acorda a sessão a cada 15, 30 ou 60 minutos durante o horário de trabalho, na assinatura que você já paga, e não mexe nela fora desse horário.

3. Atribua tarefas e responda às mensagens

   Adicione trabalho como tarefas no quadro; o funcionário as pega, comenta enquanto avança e pergunta a você quando precisa de uma revisão. Veja o que é um funcionário de IA.

Perguntas sobre agentes do Claude Code em segundo plano