Claude Code: limite de 30 minutos para comandos em segundo plano

O Claude Code para um comando em segundo plano após 30 minutos quando este é executado sem supervisão: uma execução com a flag -p, uma aplicação Agent SDK, uma tarefa de CI ou uma sessão na cloud. Se o Claude definir um tempo para o próprio comando, este será executado durante, no máximo, 2 horas; já o terminal normal, a aplicação de ambiente de trabalho e o VS Code não têm qualquer limite desde a versão 2.1.288.

Antes, passava o dia todo em frente ao ecrã: dava uma etapa ao agente, verificava, fazia uma correção e pedia-lhe que continuasse. Fase após fase. A máquina podia estar a escrever o código, mas era eu que a conduzia. Agora escrevo um plano, divido-o em fases, entrego a implementação a subagentes durante a noite e vou-me embora. Em 8 horas sem mim, o Claude segue o plano: estuda, constrói e aperfeiçoa. De manhã, passo mais tempo a aceitar o trabalho do que a refazê-lo.

Mas, se uma execução noturna usar -p, correr segundo um horário num servidor, em CI ou na cloud, um servidor de desenvolvimento e uma compilação executados em segundo plano durarão 30 minutos. Depois, o Claude Code irá pará-los, e o trabalho noturno ficará a meio. Vou explicar quem é afetado pelo limite, como aumentá-lo e o que fazer se um comando já tiver parado. Vamos a isso.

Para obter ajuda sobre a utilização do serviço, consulte a documentação da Ailoot.

Quem é afetado pelo limite#

Um comando em segundo plano é algo que o Claude inicia e deixa a correr enquanto trata de outra coisa. Por exemplo, um servidor de desenvolvimento iniciado com npm run dev ou uma compilação que monitoriza as alterações aos ficheiros.

A documentação do Claude Code diz:

Por outras palavras, o limite aplica-se quando não está presente: numa execução com -p, numa aplicação Agent SDK, numa tarefa de CI ou numa sessão na cloud. Não há limite no terminal, na aplicação de ambiente de trabalho nem no VS Code quando trabalha na própria sessão. Foi introduzido na versão 2.1.285 e, antes da versão 2.1.288, aplicava-se em todo o lado.

Como perceber se isto se aplica ao seu caso:

• Abriu o Claude Code no terminal ou no VS Code, deu-lhe uma tarefa e foi dormir. Não há limite se a versão for a 2.1.288 ou posterior. Nas versões 2.1.285 a 2.1.287, também se aplica aqui. Expliquei como atualizar para a versão mais recente num artigo separado.
• O Claude Code é iniciado com claude -p "task" segundo um horário, a partir da sua própria aplicação Agent SDK ou em CI. O limite aplica-se.
• A tarefa é executada numa sessão na cloud. O limite aplica-se.

Quando ponho agentes a trabalhar de forma autónoma, escrevo no prompt: «Regista estas condições e os motivos para parar no plano de trabalho. Confirma que o processo não depende de uma janela que eu vá fechar nem do próprio computador.» O limite de 30 minutos é um desses motivos.

Durante quanto tempo é executado um comando em segundo plano#

A contagem decrescente começa quando o comando passa para segundo plano. Há 2 casos.

O Claude inicia imediatamente o comando em segundo plano. Tem 30 minutos. Se o Claude especificar um tempo ao iniciá-lo (o parâmetro timeout), tem esse tempo, mas no máximo 2 horas.

O comando não termina enquanto o Claude espera por ele. O Claude espera 2 minutos por um comando normal. Se este não tiver terminado, o Claude Code não o para; transfere-o para segundo plano. A partir desse momento, tem 30 minutos.

Quando o tempo termina, o Claude Code para o comando e diz ao Claude:

Background command "<description>" was stopped after reaching its background time limit

Se o trabalho não estiver concluído, o Claude pode voltar a executar o comando com um tempo mais longo.

Mais um ponto sobre -p. Neste tipo de execução, os comandos em segundo plano terminam aproximadamente 5 segundos após a resposta final do Claude. Um servidor iniciado numa execução noturna com -p só durará enquanto a própria execução estiver ativa. O limite de 30 minutos é relevante quando a execução dura mais tempo: o Claude inicia um servidor no início e passa uma hora a executar verificações contra ele.

Como organizar trabalho noturno no Claude Code#

Cansei-me de conduzir o agente durante todo o dia, por isso substituí isso por um único prompt para o orquestrador. Inicio-o à noite, e o Claude trabalha a noite toda, percorrendo as fases por ordem: escreve, verifica, corrige e faz commits por conta própria.

Grupos de subagentes escrevem o código, cada um com os seus próprios ficheiros para não se atrapalharem. Outro grupo, acabado de formar, aceita o trabalho: revisão de código, verificações de segurança e verificações em ambiente real. Se encontrarem um problema, este é corrigido imediatamente e as verificações são executadas novamente. O prompt inclui a frase: «Se ficares sem contexto, regista o estado; a próxima execução continuará.»

No exemplo descrito, ao longo de 3 dias, foram concluídas 8 das 14 fases desta forma.

Há apenas 2 pontos a ter em conta. O orquestrador não pensa por si: primeiro, escreva um plano detalhado com fases e, depois, inicie o turno noturno. Além disso, consome uma grande parte da sua quota de subscrição, por isso não vale a pena configurar isto para uma tarefa pequena. Limite sempre o número de tentativas, caso contrário o agente esgotará toda a sua quota de subscrição durante a noite. Expliquei como definir estes limites de consumo num artigo separado.

Como aumentar o limite#

Opção 1: pedir ao Claude. O Claude escolhe o tempo para um comando específico; não é o utilizador que o define. Mas pode escrever na tarefa: «Mantém o servidor de desenvolvimento em segundo plano durante 2 horas.» Não pode obter mais de 2 horas desta forma.

Opção 2: variáveis no ficheiro de definições. Os valores são expressos em milissegundos. Não pode reduzir os limites para menos de 30 minutos e 2 horas; só pode aumentá-los.

• BASH_DEFAULT_TIMEOUT_MS definido acima de 1800000 (30 minutos) altera o valor predefinido de 30 minutos. Aplica-se tanto aos comandos que o Claude inicia em segundo plano sem especificar um tempo como aos comandos transferidos para segundo plano após um tempo limite. Se o definir acima de 7200000 (2 horas), o limite máximo também aumenta.
• BASH_MAX_TIMEOUT_MS definido acima de 7200000 aumenta o limite máximo de 2 horas. Não altera o valor predefinido de 30 minutos: um comando sem um tempo especificado continua a parar após 30 minutos.

BASH_DEFAULT_TIMEOUT_MS tem um efeito secundário. A mesma variável define durante quanto tempo o Claude espera por um comando normal antes de o transferir para segundo plano. Defina-a para 1 hora, e o Claude esperará 1 hora em vez de 2 minutos. Isso não atrapalha durante a noite. Durante o dia, terá de esperar mais tempo por uma resposta quando os comandos demoram muito.

Se não quiser analisar os detalhes: se precisar de 3 horas tanto para comandos normais como para o limite máximo, defina BASH_DEFAULT_TIMEOUT_MS como 10800000. É suficiente; não precisa da segunda variável.

O ficheiro de definições encontra-se na pasta .claude do seu diretório pessoal: ~/.claude/settings.json no macOS e no Linux, e %USERPROFILE%\.claude\settings.json no Windows. Se o ficheiro não existir, crie-o. Um limite de 1 hora é configurado assim:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

Se o ficheiro já tiver um bloco env, adicione-lhe a linha. Uma sessão em execução recebe os novos valores quando guarda o ficheiro. A remoção de uma variável só produz efeito na próxima vez que iniciar claude.

O ficheiro tem de estar na máquina onde o agente está a ser executado. Para o agente trabalhar durante a noite, o computador não pode entrar em suspensão. Em alternativa, execute o Claude Code num servidor remoto e coloque lá as definições.

Se o comando já tiver parado#

Não precisa de fazer nada manualmente. O Claude Code informa o Claude do motivo pelo qual um comando parou, por isso comece simplesmente por lhe perguntar o que aconteceu.

Depois, avance passo a passo:

1. Uma execução longa pontual, até 2 horas. Peça ao Claude que volte a executar o comando com um tempo mais longo.
2. Os comandos precisam regularmente de mais de 30 minutos. Defina BASH_DEFAULT_TIMEOUT_MS acima de 1800000 no ficheiro de definições, como no exemplo acima. Se precisar de mais de 2 horas, defina também BASH_MAX_TIMEOUT_MS acima de 7200000 nesse ficheiro.
3. Volte a executar o comando. A documentação não faz promessas sobre um comando que já estava a ser executado em segundo plano antes da alteração.
4. Verifique o resultado da execução seguinte. Se o relatório do Claude voltar a conter a frase «parado após atingir o limite de tempo em segundo plano», a definição não se aplicou a esse comando.

Os subagentes e as rotinas são o que mantém o agente a trabalhar enquanto está ausente.

Expliquei como pôr um agente a funcionar em ciclo durante toda a noite num artigo separado. E explico aqui como configurar o Claude Code para que não danifique o projeto durante a noite.

Verifique em que etapa a sua execução noturna para e compare o motivo com os limites acima.

Conheça a Ailoot.