O modo headless

Rodar sem interação

Todo o curso até aqui tratou do Claude Code interativo: você conversa, ele responde, você aprova, num vai e volta em tempo real. Mas há um segundo jeito de usar o agente, feito para automação: o modo headless. Nele, não há conversa. Você passa uma tarefa de uma vez, o Claude Code a executa por conta própria e devolve o resultado, sem parar para perguntar nem esperar a sua aprovação interativa. É como a diferença entre conversar com um assistente e deixar uma tarefa numa lista para ele fazer sozinho. O modo headless é essa lista de tarefas automática, que roda sem você na tela.

Por que isso importa? Porque abre um mundo novo de usos. Sem interação, o Claude Code pode ser encaixado dentro de programas maiores que rodam sozinhos. Você pode chamá-lo num script, aquele pequeno programa que executa uma sequência de passos, como parte de um fluxo automático. Você pode ligá-lo a outros programas, mandando a saída de um para ele e a resposta dele para outro. Você pode agendá-lo para rodar em horários certos. Tudo isso exige que o agente funcione sem um humano por perto, e é exatamente o que o modo headless entrega: o poder do Claude Code disponível para a automação.

Entrada e saída para automação

O modo headless foi pensado para se encaixar em fluxos automáticos, e por isso cuida bem da entrada e da saída. Na entrada, você passa a tarefa direto, como um pedido único e completo. Você pode até alimentar o agente com dados de outro programa, mandando, por exemplo, o texto de um erro para ele analisar. Na saída, o resultado pode vir em formatos estruturados que outros programas conseguem ler e usar, não só como texto para um humano. Isso é o que permite encadear o Claude Code com outras ferramentas: a saída dele vira a entrada de outro passo do fluxo. Entrada clara e saída legível por máquina são o que fazem o modo headless brincar bem com o resto do seu sistema.

claude -p "resuma o que este projeto faz"

A ideia do modo headless: passar uma tarefa direto e receber o resultado, sem conversa.

Vale marcar que o modo headless é um recurso avançado, voltado a quem quer automatizar, e nem todo mundo vai precisar dele. Para o uso do dia a dia, conversando com o agente, o modo interativo é o certo. O headless entra quando você quer que o Claude Code seja parte de um processo automático: um passo de uma verificação que roda sozinha, uma tarefa disparada por um evento, um agente que trabalha enquanto você dorme. Se você nunca automatizou nada, tudo bem ignorar este módulo por ora; ele fica guardado para quando a necessidade de automação aparecer, e aí você saberá que o Claude Code atende.

O que o modo headless destrava

Pensar no que o modo headless destrava ajuda a enxergar o seu valor. Ele é a base de tudo que vem neste módulo. A automação em CI, quando o agente age sozinho a cada mudança de código, usa o headless por baixo. As tarefas agendadas, que rodam em horários certos, também. Os agentes construídos com o SDK, que veremos, se apoiam na mesma capacidade de rodar sem interação. Em outras palavras, o modo headless é a porta que transforma o Claude Code de um assistente que você usa numa peça que trabalha por conta própria dentro dos seus sistemas. As próximas aulas mostram cada um desses usos, e todos partem daqui.

Com o modo headless entendido, você tem a chave da automação com o Claude Code. A próxima aula mostra um dos usos mais poderosos: rodar o agente em CI e no GitHub, onde ele age automaticamente sobre o seu código, revisando mudanças, respondendo a pedidos e ajudando o time sem ninguém precisar chamá-lo na hora. É onde o Claude Code deixa de ser uma ferramenta que você abre e vira uma presença constante no fluxo de trabalho, trabalhando nos bastidores. Tudo isso apoiado na capacidade simples e poderosa que você acabou de conhecer: rodar sem interação.