DevPawDEVPAW · GROUND-UP DEV NOTES
Buscar
Menu
PT-BR
한국어English日本語繁體中文EspañolPortuguês简体中文
Programação e agentes de IA

[Claude Code #14] claude -p headless: colocando IA em pipes

O modo headless do claude -p permite usar o Claude Code como uma ferramenta Unix. Este guia reúne o uso em scripts com pipes de stdin, --output-format json e jq, permissões de --allowedTools e o modo --bare no CI.

4 min de leitura
Imagem de capa de [Claude Code #14] claude -p headless: colocando IA em pipes

Se você usa o Claude Code apenas pela janela de conversa, está usando metade do que ele oferece. Ao incluí-lo em um pipeline do terminal, ele funciona como ferramentas Unix, como grep ou jq.

O ponto central é a flag -p (ou --print). Ela processa um prompt sem tela interativa, imprime apenas o resultado e encerra.

claude -p "auth Explique o que este módulo faz"

Se Claude Code — Parte 13 tratava do que acontece dentro de uma sessão, desta vez veremos como usá-lo fora dela.

Inserindo por pipe e recebendo em arquivo

Com Documentação oficial, o modo -p lê a entrada padrão. Envie os dados por pipe e redirecione o resultado, exatamente como em qualquer outra ferramenta CLI.

cat build-error.txt | claude -p 'Explique de forma concisa a causa raiz deste erro de build' > output.txt

Com base em Documentação oficial, o sucesso termina com código de saída 0 e a falha com um código diferente de 0, permitindo ramificações no script. A entrada por pipe aceita até 10 MB; para algo maior, informe o caminho do arquivo no prompt.

Ao adicioná-lo aos scripts do package.json, você também pode criar um linter específico do projeto. Por exemplo, envie um diff por pipe e faça com que ele reporte apenas erros de digitação.

Recebendo JSON para consumo por programas

Ao adicionar --output-format json, o resultado é retornado de forma estruturada junto com metadados como ID da sessão e custo.

claude -p "Faça um resumo deste projeto" --output-format json | jq -r '.result'

Se precisar de uma saída compatível com um schema específico, adicione --json-schema a --output-format json. A resposta chega com uma estrutura validada no campo structured_output.

Para streaming em tempo real por token, use a combinação --output-format stream-json --verbose --include-partial-messages.

Diagrama do fluxo de entrada por pipe do claude -p, saída JSON e ramificações pelo código de saída
Envie por pipe, receba com jq e faça ramificações pelo código de saída

As permissões precisam ser abertas com antecedência

No modo -p, não há ninguém para clicar no botão de aprovação. Você precisa permitir as ferramentas necessárias previamente.

claude -p "Execute os testes e corrija as falhas" --allowedTools "Bash,Read,Edit"

--allowedTools usa a sintaxe das regras de permissão diretamente. É possível restringi-la, como em Bash(git diff *). O espaço antes do asterisco é importante. Sem ele, a correspondência inclui até git diff-index.

Ao fornecer --permission-mode acceptEdits, a escrita de arquivos e comandos comuns do sistema de arquivos, como mkdir e mv, são aprovados automaticamente. Os demais comandos de shell e solicitações de rede ainda exigem --allowedTools.

Continuando a conversa

Para tarefas que não terminam em uma única chamada, basta continuar a sessão.

claude -p "Revise os problemas de desempenho desta base de código"
claude -p "Agora DB concentre-se na query" --continue

Se você conduzir várias conversas em paralelo, salve o session_id da saída JSON e use --resume para retomar uma conversa específica.

No CI, –bare é o padrão

Para scripts e CI, é recomendável usar --bare também. Ele ignora o carregamento automático de hooks, skills, plugins, MCP e CLAUDE.md, acelera a inicialização e produz o mesmo resultado em qualquer máquina.

Há também um motivo de segurança. Uma sessão -p não consegue exibir a janela de confiança do workspace; sem --bare, ela executará até hooks e servidores MCP de um repositório desconhecido. A documentação oficial recomenda explicitamente --bare para chamadas em scripts e afirma que -p deverá se tornar o padrão no futuro.

No --bare, lembre-se de usar a variável de ambiente ANTHROPIC_API_KEY em vez do login por assinatura.

Ilustração contrastando as palavras GO BARE IN CI, um robô sem equipamentos em uma sala vazia e outro coberto de dispositivos
No CI, é mais seguro remover todos os equipamentos e executá-lo sem nada

Resumo

claude -p transforma o Claude Code em uma ferramenta Unix. Envie por pipe, receba em JSON e faça ramificações pelo código de saída.

Abra as permissões previamente com --allowedTools e execute de forma determinística e segura no CI com --bare.

Na próxima parte, voltaremos à tela interativa para revisar o modo shell ! e entradas e atalhos especiais, como Ctrl+O.

Fontes e critérios de verificação

Continue lendo

Série Claude Code

Tópicos relacionados