Modo headless do Claude Code: -p, CI e a GitHub Action
Scripte o Claude Code como uma ferramenta Unix: prompts one-shot com claude -p, arquivos via pipe, JSON de saída para parsear, sessões retomadas por id, --bare para CI, e a @claude GitHub Action construindo features a partir de uma issue — direto do walkthrough do próprio Anthropic.
A versão curta
- claude -p "prompt" roda uma vez e imprime o resultado — sem sessão interativa. Compõe como qualquer ferramenta Unix: pipe pra dentro, pipe pra fora, encadeado em scripts e etapas de CI.
- --output-format json devolve o resultado mais session_id, custos e metadados; stream-json emite eventos delimitados por linha para consumidores em tempo real. Parseie com jq e construa por cima.
- O headless roda sem permissões de edição ou destruição por padrão. Conceda exatamente o necessário com --allowedTools "Bash(git diff *),Edit" — sintaxe de regra de permissão, casamento por prefixo.
- A @claude GitHub Action é o modo headless com frontend: marque @claude numa issue ou PR e ela lê código, cria PRs e commits, responde perguntas e revisa código — nos seus próprios runners do GitHub.
Building headless automation with Claude Code | Code w/ Claude
Canal: Anthropic20:59
Headless mode — official documentation
Documentação oficial: code.claude.com/docs
Claude Code GitHub Action — official docs
Documentação oficial: code.claude.com/docs
Flags, limites e comportamentos desta página foram verificados contra a documentação oficial do headless; a palestra acima é o walkthrough do próprio Anthropic e a fonte visual das capturas.
As capturas de tela pertencem aos seus criadores, com links diretos para os timestamps exatos. Imagens de palestrante e plateia não são usadas.
Rodar o Claude Code headless, passo a passo
Parte 1 — O básico do headless
- 1
O que é o modo headless
Modo headless é o Claude Code sem a UI interativa: o mesmo agente, acionado por programação. O Anthropic o apresenta como um bloco de construção simples para aplicações agênticas — use como uma ferramenta Unix em scripts e pipelines, para automação de CI, ambientes remotos, ou como o motor por trás de uma interface de chat web.
O enquadramento do próprio Anthropic: o SDK é acesso programático ao Claude Code em ambientes headless.Ver em 2:10 - 2
Prompts one-shot com claude -p
A flag -p (ou --print) executa um único prompt e sai: claude -p "Write me a function that calculates the Fibonacci sequence". Nada fica aberto — você recebe a saída no stdout e um código de saída que seus scripts podem checar. Combine com --allowedTools para conceder acesso de escrita de antemão.
Um pedido one-shot: claude -p gera a função de Fibonacci e sai — sem TUI, sem perguntas de acompanhamento.Ver em 3:30 - 3
Pipeie arquivos direto para o Claude
O stdin funciona como o de qualquer ferramenta CLI: cat app.log | claude -p "summarize the most common error logs". Na demo do Anthropic, 2000 linhas de log entram e sai um resumo dos erros em inglês plano — o mesmo truque serve para falhas de build, stack traces e exports. O stdin via pipe tem teto de 10MB.
cat mais o símbolo de pipe mais claude -p: duas mil linhas de log viram um diagnóstico de três frases.Ver em 3:55 - 4
Decifre saídas que você odeia ler
O mesmo padrão transforma saída hostil em respostas: ifconfig | claude -p "what interfaces do I have configured? don't include lo". Qualquer coisa que um comando imprima — estado de rede, erros de compilador, plans do terraform — pode passar pelo Claude para virar um resumo humano.
ifconfig pipeado pelo claude -p: cada interface explicada, loopback excluído a pedido.Ver em 4:15 - 5
Receba JSON estruturado
Adicione --output-format json e a resposta vira um objeto parseável: o texto do resultado, o session_id, duração e total_cost_usd. Para consumidores ao vivo, --output-format stream-json emite eventos delimitados por linha conforme acontecem — a última linha é o resultado final.
Modo JSON: um bloco só com o resultado, um id de sessão para retomar depois, e o custo da execução.Ver em 4:35
Parte 2 — Scriptar como engenheiro
- 6
Conceda ferramentas deliberadamente
O headless começa sem permissões de edição ou destruição. --allowedTools pré-aprova o que a tarefa precisa, usando sintaxe de regra de permissão: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". Ferramentas MCP podem entrar na allow list do mesmo jeito — conceda o conjunto mais estreito que resolve o trabalho.
O deep dive do SDK: permissões de ferramentas, modos de saída estruturada e system prompts customizados num slide.Ver em 11:00 - 7
Mantenha contexto entre execuções
O modo JSON devolve um session_id — passe-o de volta com --resume "$session_id" para continuar o mesmo estado de conversa numa execução posterior ou noutro processo. É assim que se constroem produtos interativos por cima: o usuário fala, o Claude responde, você preserva a sessão para o próximo turno.
- 8
Trate permissões sem humano na sala
Se você não consegue prever quais ferramentas o Claude vai precisar, --permission-prompt-tool transfere as decisões de aprovação para um servidor MCP em tempo de execução — a ferramenta pergunta ao seu serviço (ou ao seu usuário, via seu app) se cada ação pode passar, em vez de você pré-listar tudo.
- 9
Vá de --bare para CI
--bare pula a autodescoberta de hooks, skills, comandos customizados, subagentes, plugins, servidores MCP e CLAUDE.md para o startup mais rápido possível — recomendado para scripts e CI, e deve virar o padrão do -p. Exige ANTHROPIC_API_KEY e recebe contexto explicitamente via flags.
Parte 3 — A @claude GitHub Action
- 10
Conheça a @claude GitHub Action
A GitHub Action é o modo headless com um frontend construído sobre o SDK. Marque @claude em qualquer PR ou issue e ela pode ler seu código, criar PRs, adicionar commits aos existentes, responder perguntas e revisar mudanças — rodando nos runners do GitHub que você já tem, então não há infraestrutura para cuidar.
O contrato da Action: marque @claude, descreva o que precisa, e ela trabalha o repositório nos seus próprios runners.Ver em 17:10 - 11
Atribua uma issue ao Claude
Na demo ao vivo do Anthropic, um comentário de "@claude please implement this feature and comment on it" fez o bot responder com um plano com escopo — tópicos do que construiria — antes de criar o branch, os commits e o pull request, tudo rastreável nos logs da Action.
O comentário @claude numa issue real: o Claude responde com um plano com escopo antes de tocar em qualquer código.Ver em 7:50 - 12
Instale no seu repositório
O resultado é um resumo de implementação com caixinhas marcadas na issue — features adicionadas, todos fechados. Para chegar lá, abra o Claude Code no seu repositório e rode /install-github-action: um fluxo interativo abre um PR com o workflow YAML, depois configure as chaves de API como secrets do repo e faça merge.
A execução concluída: um resumo de implementação com cada feature que a Action adicionou ao app de demo.Ver em 13:30
Headless vs interativo vs SDK vs a GitHub Action
Quatro maneiras de acionar o mesmo agente — escolha por quem (ou o quê) está perguntando:
- 1CLI interativo — a sessão TUI: prompts de permissão, plan mode, /comandos. Melhor para humanos conduzindo uma tarefa agora.
- 2Headless claude -p — um tiro programático: stdin e stdout, códigos de saída, sem UI. Melhor para scripts, tarefas cron e perguntas rápidas de outras ferramentas.
- 3O Agent SDK — o mesmo poder headless como biblioteca tipada: sessões multi-turno, ferramentas customizadas, streaming. Melhor quando o Claude é um componente dentro da sua aplicação.
- 4A @claude GitHub Action — headless rodando no modelo de eventos do GitHub: issues, PRs e reviews nos seus próprios runners. Melhor para automação com escopo de repositório que o time inteiro pode disparar.
- 5--bare headless — um startup enxuto para CI: sem CLAUDE.md, hooks, skills, plugins ou autodescoberta MCP, contexto explícito via flags, cold start mais rápido.
Eles compartilham o mesmo acesso de modelo e sistema de permissões — uma regra concedida ao headless vale em todo lugar, e é por isso que a disciplina com --allowedTools importa.
O headless está se comportando mal? Primeiros socorros
Cinco pegadinhas específicas do headless, e a correção de cada uma:
- 1O script sai antes de o Claude terminar. Cheque o código de saída: 0 é sucesso, qualquer outro falhou. SIGTERM sai com 143 e deixa o turno inacabado — termine execuções com SIGINT ou o interrupt() do SDK se precisar parar no meio do turno.
- 2Entrada pipeada truncada em silêncio. O stdin tem teto de 10MB — escreva payloads maiores num arquivo e referencie o caminho no prompt.
- 3"--bg rejected" ou um erro de --cloud. Flags exclusivas do modo interativo não valem para -p: --bg é rejeitado de cara, e --cloud precisa de um session id para enfileirar uma mensagem, em vez de uma descrição de tarefa.
- 4A execução de CI ignora seu CLAUDE.md e hooks. É o --bare fazendo o trabalho dele: ele pula a autodescoberta. Passe contexto explicitamente com --settings, --mcp-config, --agents ou --plugin-dir.
- 5Tarefas bash em background morrem no meio. Shells em segundo plano são mortos cerca de 5 segundos depois que o resultado chega; subagentes e workflows mantêm o processo vivo até o teto de 10 minutos de inatividade. Espere por eles explicitamente no CI.
Para todo o resto, adicione --verbose e leia os eventos stream-json — o system/init nomeia o modelo, as ferramentas e os servidores MCP que realmente carregaram.