Mantenha Seu Mac Ativo Durante Execuções Noturnas de Agentes com caffeinate

caffeinate é uma ferramenta de linha de comando integrada ao macOS que impede que o seu Mac entre em modo de suspensão enquanto uma tarefa é executada — e a forma mais útil é caffeinate -i <seu comando>, que encapsula um processo, mantém o sistema ativo pelo tempo que ele estiver em execução e libera automaticamente no momento em que ele encerra. Se você fechou a tampa do notebook ou se afastou e voltou para encontrar um job noturno do Claude Code, Codex ou uma build longa morta, esta é a solução nativa, sem necessidade de instalação. Este artigo cobre as flags relevantes, a receita durável para execuções noturnas, como verificar se a asserção está realmente ativa e o único limite que o caffeinate não consegue superar.

O que é o caffeinate no Mac (a resposta em 10 segundos)

caffeinate é uma ferramenta de linha de comando oficial do macOS que cria asserções de gerenciamento de energia para alterar o comportamento de suspensão; ela está disponível em /usr/bin/caffeinate desde o OS X 10.8 (2012), não requer instalação nem privilégios de administrador. Internamente, ela utiliza a API de asserções de energia do IOKit — um mecanismo que solicita dinamicamente um comportamento do sistema ao gerenciador de energia — via IOPMAssertionCreateWithName, o mesmo caminho oficial que os aplicativos utilizam para manter o Mac ativo durante o trabalho.

O comportamento que importa para um job de longa duração é o encapsulamento. Se um utilitário for especificado, o caffeinate cria as asserções em nome desse utilitário, e essas asserções persistem durante toda a execução do utilitário; caso contrário, o caffeinate cria as asserções diretamente, e elas persistem até que o caffeinate seja encerrado. O exemplo canônico da página de manual é caffeinate -i make: o caffeinate cria um processo filho, executa “make” nele e mantém uma asserção que impede a suspensão por inatividade enquanto esse processo estiver em execução.

As flags do caffeinate que importam

Em um notebook, a única flag que importa é caffeinate -i: ela impede que o sistema entre em suspensão por inatividade, permitindo que a tela apague, o que é exatamente o que um agente em segundo plano ou uma build precisa. O conjunto completo de flags documentadas é maior do que a maioria dos guias admite:

Dois detalhes que outros guias costumam errar. Primeiro, a asserção -s só é válida quando o sistema está funcionando com o carregador conectado — na bateria, ela é silenciosamente ignorada, portanto não é o padrão correto para um notebook desconectado. Segundo, se a tela estiver apagada, -u a acende e impede a suspensão por inatividade; se nenhum timeout for especificado com -t, essa asserção assume por padrão um timeout de 5 segundos. Encapsular uma tarefa é mais seguro do que uma asserção simples porque ela não pode sobreviver ao job: caffeinate -i npm run build impede a suspensão durante a build e libera a asserção instantaneamente ao término.

A receita para execuções noturnas de agentes

Para manter o Claude Code, o Codex CLI ou o Aider ativos durante a noite, encapsule o comando de inicialização do agente diretamente e execute-o dentro de um multiplexador de terminal para que nada dependa da janela do Terminal permanecer aberta. Como a asserção reside dentro do processo caffeinate, ela é encerrada se o Terminal fechar ou travar — o tmux oferece durabilidade real:

# Inicia uma sessão tmux em segundo plano que mantém a asserção durante toda a execução
tmux new-session -d -s agent 'caffeinate -i claude'

Se o agente já estiver em execução em outro painel, não o reinicie — vincule uma nova asserção ao ID de processo existente com -w:

# Encontre o PID e mantenha a asserção até que o processo encerre
pgrep -f claude
caffeinate -i -w <pid>

Antes de se afastar de uma execução de 8 horas, verifique se a asserção está realmente ativa. Em um segundo painel, execute:

pmset -g assertions

Uma entrada PreventUserIdleSystemSleep nessa saída confirma que o macOS não entrará em suspensão por inatividade enquanto o job estiver em execução; quando o comando encapsulado encerrar, a linha desaparece. Esse diagnóstico é a diferença entre torcer para que a execução noturna esteja protegida e ter a certeza de que está.

O caffeinate consegue manter um MacBook ativo com a tampa fechada?

caffeinate por si só não manterá um MacBook ativo com a tampa fechada. Fechar a tampa aciona o modo de suspensão de clamshell, e uma asserção de energia por software não consegue sobrepô-lo quando o Mac está na bateria — ponto final. Este é o limite que nenhuma ferramenta de linha de comando para manter o sistema ativo consegue superar, e é por isso que um job morre no momento em que você fecha o notebook e desconecta o carregador.

A operação com a tampa fechada funciona em exatamente dois casos suportados. O primeiro é o modo clamshell da Apple: a Apple suporta o uso de um MacBook com a tampa fechada ao conectar um monitor externo, teclado e mouse, mas a configuração tem requisitos rigorosos — não funciona sem um monitor externo e pode introduzir desvantagens térmicas. A configuração recomendada pela Apple conecta um monitor externo, um adaptador de energia e um teclado e mouse ou trackpad externos. O segundo é o botão de alternância em Configurações do Sistema → Bateria → Opções, “Impedir suspensão automática quando a tela estiver desligada” — mas isso requer que o computador esteja conectado a uma fonte de energia, não funcionando na bateria, para funcionar como esperado.

Se você genuinamente precisar de bateria e tampa fechada — um notebook em uma bolsa executando um agente — o caffeinate não é a ferramenta certa. O Amphetamine foi desenvolvido para esse caso: sua documentação afirma que com o Amphetamine, o seu Mac não precisa de monitor, teclado, mouse ou adaptador de energia para usar o Modo de Tampa Fechada, pois ele utiliza uma API de acesso público para desabilitar os requisitos da Apple.

Aqui está o panorama completo em uma tabela de verdade:

Como encerrar e os pontos de atenção

Encerre o caffeinate com Ctrl+C em primeiro plano, ou deixe-o encerrar por conta própria quando o comando encapsulado finalizar — o padrão de encapsulamento foi projetado para ser difícil de deixar em execução por engano. Vale nomear os modos de falha. Um caffeinate simples sem utilitário encapsulado e sem -t é executado até que você o encerre manualmente; deixar qualquer Mac ativo continuamente aumenta o consumo da bateria, eleva a temperatura dos componentes e adiciona escritas no SSD ao longo do tempo, portanto limite a asserção ao escopo do job. E como a asserção está vinculada ao processo, fechar ou travar o Terminal a encerra instantaneamente — o que é o argumento central para encapsular o agente no tmux em vez de digitar caffeinate e torcer para que a janela permaneça aberta a noite toda.

Quando recorrer a mais recursos

caffeinate é a ferramenta certa quando o seu Mac está com o carregador conectado, ou com a tampa aberta, e você quer proteger um job noturno específico com limpeza automática. Quando você precisar de bateria com a tampa fechada, passe para o Amphetamine e seus controles baseados em sessão. E quando uma build ou execução de agente for pesada o suficiente para durar dias, a resposta mais limpa muitas vezes é parar de gerenciar o estado de energia de um notebook e executar a carga de trabalho em uma máquina remota sempre ativa — uma máquina que nunca suspende porque nunca foi projetada para isso. Para o caso de execução noturna no seu próprio Mac, encapsule o comando, verifique a asserção com pmset -g assertions e vá dormir.

Perguntas Frequentes

Qual é a diferença entre caffeinate -i e caffeinate -d?

A flag -i impede a suspensão do sistema por inatividade, ainda permitindo que a tela apague, o que é o necessário para um agente em segundo plano ou uma build, e o padrão correto em um notebook. A flag -d impede a suspensão da tela, mantendo-a acesa e desperdiçando energia em um job sem interface. Use -i para trabalho noturno no terminal e reserve -d apenas quando a tela em si precisar permanecer acesa, como em um painel de monitoramento.

O caffeinate precisa de sudo ou privilégios de administrador para ser executado?

Não. O caffeinate não requer instalação nem privilégios de administrador porque utiliza a API pública de asserções de energia do IOKit, o mesmo mecanismo oficial que aplicativos como o Xcode usam para manter o Mac ativo. Qualquer usuário pode executá-lo diretamente pelo Terminal. Ele já vem integrado ao macOS em /usr/bin/caffeinate desde o OS X 10.8, portanto não há nada para instalar nem permissões elevadas a conceder.

O que acontece com o caffeinate se eu fechar a janela do Terminal?

A asserção é encerrada instantaneamente. Como a asserção de gerenciamento de energia reside dentro do processo caffeinate, fechar ou travar a janela do Terminal encerra esse processo e derruba a asserção, permitindo que o Mac entre em suspensão por inatividade. Para sobreviver ao fechamento ou travamento de uma janela, execute o job dentro do tmux com o caffeinate encapsulando o comando dentro da sessão, para que a asserção esteja vinculada a um processo em segundo plano que sobrevive ao seu Terminal.

Como faço para manter o caffeinate em execução por apenas um número definido de horas?

Use a flag -t com um timeout em segundos. Por exemplo, caffeinate -i -t 28800 impede a suspensão por inatividade por exatamente oito horas e então encerra automaticamente, liberando a asserção. Isso é útil quando você quer uma janela de tempo fixa em vez de vincular a asserção ao tempo de vida de um comando específico. Sem -t ou um utilitário encapsulado, um caffeinate simples é executado até que você o encerre manualmente com Ctrl+C.