Modulo 1.8 - Modo Headless e Automacao CLI

🖥️ O que e modo headless

O modo headless (ou nao-interativo) permite que voce use o Claude Code sem abrir uma sessao interativa. Em vez de digitar prompts manualmente, voce envia um comando unico via terminal e recebe a resposta diretamente no stdout. Isso e fundamental para automacao, CI/CD e integracao com scripts.

🎯 Conceito Principal

No modo headless, o Claude Code funciona como qualquer outra ferramenta de linha de comando Unix: recebe input, processa e retorna output. Nao ha interface interativa, nao ha prompts de confirmacao (quando configurado corretamente), e o processo termina automaticamente apos a resposta.

• Non-interactive: O Claude processa o prompt e retorna o resultado sem esperar input adicional do usuario. Ideal para scripts que rodam sem supervisao
• CI/CD ready: Pode ser integrado em pipelines do GitHub Actions, GitLab CI, Jenkins e qualquer sistema que execute comandos shell
• Pipe-friendly: A saida pode ser redirecionada com |, > e combinada com outras ferramentas Unix
• Sem confirmacoes: Com as flags certas, o Claude executa sem pedir permissao, essencial para automacao desassistida

💻 Exemplo no Terminal

# Modo headless basico com -p (print)

$ claude -p "Explique o que faz o arquivo main.py"

# Pipe de entrada

$ cat error.log | claude -p "Analise este log e identifique o erro"

# Redirecionando saida para arquivo

$ claude -p "Gere um README para este projeto" > README.md

💡 Dica Pratica

Sempre teste seus comandos headless manualmente antes de coloca-los em scripts automatizados. A flag -p e o ponto de partida - ela transforma o Claude em uma ferramenta de linha de comando pura.

Lembre-se: no modo headless, o Claude ainda le o CLAUDE.md do projeto. Isso significa que suas instrucoes de projeto continuam valendo mesmo em automacao.

⚡ claude -p basico (one-shot prompts)

A flag -p (ou --print) e a forma mais direta de usar o Claude Code em modo headless. Voce passa um prompt como argumento, o Claude processa e imprime a resposta no stdout. Simples, rapido e composavel com outras ferramentas.

🎯 Conceito Principal

O claude -p funciona como um "one-shot": envia um unico prompt, recebe uma unica resposta e o processo encerra. Nao ha sessao persistente, nao ha historico, nao ha interacao. E o equivalente a um curl para IA.

• Sintaxe basica: claude -p "seu prompt aqui" - o prompt vai entre aspas para preservar espacos e caracteres especiais
• Stdin como contexto: Voce pode combinar stdin com o prompt: cat arquivo | claude -p "Analise este codigo"
• Exit code: O Claude retorna exit code 0 em sucesso e diferente de zero em erro, permitindo uso em condicionais bash
• Composavel: A saida e texto puro, podendo ser processada com grep, sed, awk, jq ou qualquer outra ferramenta Unix

💻 Exemplo no Terminal

# Prompt simples

$ claude -p "Liste os 5 maiores arquivos deste projeto"

# Com pipe de entrada

$ git diff HEAD~1 | claude -p "Resuma as mudancas deste diff"

# Usando em condicional

$ if claude -p "Este codigo tem bugs? Responda apenas SIM ou NAO" | grep -q "SIM"; then

echo "Bugs encontrados!"

💡 Dica Pratica

Para prompts longos, use heredocs do bash em vez de aspas simples. Isso evita problemas com caracteres especiais e permite prompts multi-linha:

$ claude -p <<'EOF'

Analise o arquivo src/main.py e sugira

melhorias de performance focando em:

1. Loops desnecessarios

2. Alocacoes de memoria

EOF

📊 --output-format json (saida estruturada)

A flag --output-format json transforma a saida do Claude em JSON estruturado, permitindo parsing programatico com ferramentas como jq. Isso e essencial para automacoes que precisam extrair dados especificos da resposta do Claude.

🎯 Conceito Principal

No formato JSON, a resposta do Claude vem em um objeto estruturado contendo o texto da resposta, metadados da sessao, custo de tokens e informacoes sobre ferramentas utilizadas. Isso permite que scripts automatizados processem a resposta de forma confiavel.

• Estrutura JSON: O output inclui campos como result, cost_usd, session_id e is_error
• Parsing com jq: Use jq '.result' para extrair apenas o texto da resposta, ou jq '.cost_usd' para o custo
• Stream JSON: Com --output-format stream-json, cada evento e emitido como uma linha JSON separada (JSONL), ideal para streaming em tempo real
• Erro tratavel: Em caso de erro, o campo is_error sera true, permitindo tratamento automatizado de falhas

💻 Exemplo no Terminal

# Saida JSON completa

$ claude -p "Quantos arquivos .py existem?" --output-format json

# Extraindo apenas o resultado com jq

$ claude -p "Liste bugs neste arquivo" --output-format json | jq -r '.result'

# Verificando custo

$ claude -p "Refatore esta funcao" --output-format json | jq '.cost_usd'

# Checando se houve erro

$ claude -p "..." --output-format json | jq '.is_error'

💡 Dica Pratica

Combine --output-format json com jq para criar pipelines robustas. Por exemplo, voce pode extrair o resultado, verificar se houve erro e salvar o custo em um log - tudo em uma unica linha de comando.

Para scripts de producao, sempre use JSON em vez de texto puro. Texto puro pode mudar de formato entre versoes do Claude, mas a estrutura JSON e estavel e documentada.

🔒 --allowedTools em automacao

Quando o Claude roda sem supervisao, e critico limitar quais ferramentas ele pode usar. A flag --allowedTools define uma whitelist de ferramentas permitidas, garantindo que o Claude nao execute acoes perigosas em modo automatizado.

🎯 Conceito Principal

Em automacao, o principio de menor privilegio e fundamental. Se o Claude so precisa ler arquivos, nao de permissao para escrever. Se so precisa analisar codigo, nao de acesso ao terminal. A flag --allowedTools implementa isso de forma granular.

• Whitelist explicita: Somente as ferramentas listadas ficam disponiveis. Qualquer tentativa de usar outra ferramenta sera bloqueada automaticamente
• Ferramentas comuns: Read (ler arquivos), Write (escrever), Edit (editar), Bash (executar comandos)
• Safety first: Em CI/CD, nunca permita Bash sem restricoes. Prefira Read + analise para tarefas de review
• Combinacao com --dangerouslySkipPermissions: Esta flag pula TODAS as confirmacoes. Use APENAS em ambientes isolados (containers, CI) e SEMPRE com --allowedTools restrito

💻 Exemplo no Terminal

# Somente leitura - seguro para review

$ claude -p "Revise este PR" --allowedTools Read,Glob,Grep

# Leitura + escrita - para fixes automaticos

$ claude -p "Corrija os tipos" --allowedTools Read,Write,Edit

# CI/CD com permissoes puladas (CUIDADO!)

$ claude -p "Review de seguranca" \

--allowedTools Read,Glob,Grep \

--dangerouslySkipPermissions

💡 Dica Pratica

Crie aliases no seu .bashrc para diferentes niveis de permissao:

# Em ~/.bashrc

alias claude-review='claude -p --allowedTools Read,Glob,Grep'

alias claude-fix='claude -p --allowedTools Read,Write,Edit'

alias claude-full='claude -p --allowedTools Read,Write,Edit,Bash'

🔄 Loop bash com Claude (batch processing)

Uma das aplicacoes mais poderosas do modo headless e usar o Claude dentro de loops bash para processar multiplos arquivos, repositorios ou tarefas em lote. Combinando for/while com claude -p, voce cria pipelines de processamento em massa.

🎯 Conceito Principal

O batch processing com Claude funciona como qualquer pipeline Unix: voce itera sobre uma lista de itens (arquivos, URLs, erros) e para cada item, executa uma chamada ao Claude. A chave e estruturar o output para que os resultados sejam coletaveis e processaveis.

• For loop basico: for f in *.py; do claude -p "Revise $f"; done - processa cada arquivo Python do diretorio
• While + read: Leia uma lista de tarefas de um arquivo e processe cada uma com o Claude sequencialmente
• Paralelismo com xargs: Use xargs -P 4 para processar ate 4 arquivos simultaneamente, acelerando o batch
• Controle de custo: Cada iteracao do loop e uma chamada separada ao Claude. Monitore o custo total e adicione limites se necessario

💻 Exemplo no Terminal

# Revisar todos os arquivos Python

$ for f in src/*.py; do

echo "=== Revisando: $f ==="

cat "$f" | claude -p "Revise este codigo Python. Liste problemas encontrados."

echo ""

done > review_completo.txt

# Processar lista de tarefas

$ while IFS= read -r tarefa; do

claude -p "$tarefa" --output-format json | jq -r '.result'

done < tarefas.txt

# Paralelo com xargs (4 de cada vez)

$ find . -name "*.ts" | xargs -P 4 -I {} \

sh -c 'claude -p "Adicione tipagem ao arquivo {}" --allowedTools Read,Edit'

💡 Dica Pratica

Sempre adicione um sleep 1 entre iteracoes para evitar rate limiting. Para lotes grandes (50+ arquivos), use --output-format json e salve cada resultado em um arquivo separado para facilitar a analise posterior.

Dica avancada: crie um script wrapper que registra o custo de cada iteracao e para automaticamente quando atingir um limite predefinido (ex: $5.00).

🚀 Introducao a CI/CD com Claude

O Claude Code pode ser integrado diretamente em pipelines de GitHub Actions, GitLab CI e outros sistemas de CI/CD para realizar code review automatizado, gerar documentacao, verificar seguranca e muito mais - tudo de forma automatica a cada push ou pull request.

🎯 Conceito Principal

A integracao com CI/CD transforma o Claude de uma ferramenta pessoal em um membro automatizado do time. Ele pode revisar PRs, sugerir melhorias, gerar changelogs e ate criar testes - tudo disparado automaticamente por eventos do repositorio.

• GitHub Actions: Use a action oficial anthropics/claude-code-action para integrar o Claude como revisor automatico de PRs
• Automated review: A cada PR aberto, o Claude analisa o diff, identifica problemas potenciais e comenta diretamente no PR com sugestoes
• API key segura: Armazene a chave da API como secret do repositorio (ANTHROPIC_API_KEY) - nunca em codigo
• Custo controlado: Configure max_tokens e use --allowedTools restrito para manter o custo por execucao previsivel

💻 Exemplo: GitHub Actions

# .github/workflows/claude-review.yml

name: Claude Code Review

on: pull_request

jobs:

review:

runs-on: ubuntu-latest

steps:

- uses: anthropics/claude-code-action@v1

with:

anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

prompt: "Revise este PR focando em bugs, seguranca e performance"

allowed_tools: "Read,Glob,Grep"

💡 Dica Pratica

Comece com review automatizado somente para leitura (Read, Glob, Grep). Depois de validar que funciona bem, evolua para acoes mais complexas como sugestao de fixes e geracao automatica de testes.

Monitore o custo por PR nas primeiras semanas. Um review tipico custa entre $0.05 e $0.50 dependendo do tamanho do diff. Configure alertas para PRs que custem mais que $1.00.

🏋️ Exercicio Pratico

Criar script bash que usa claude -p em loop para processar multiplos arquivos

Criar o script base

Crie um arquivo chamado batch-review.sh com a estrutura basica:

#!/bin/bash

OUTPUT_DIR="reviews"

mkdir -p "$OUTPUT_DIR"

echo "Iniciando batch review..."

Adicionar o loop de processamento

Adicione um for loop que itera sobre arquivos e chama claude -p para cada um:

for f in src/*.py; do

echo "Revisando: $f"

cat "$f" | claude -p "Revise este codigo. Liste bugs e melhorias." \

--output-format json | jq -r '.result' > "$OUTPUT_DIR/$(basename $f).review.md"

sleep 1

done

Adicionar controle de custo

Registre o custo de cada iteracao e calcule o total:

TOTAL_COST=0

COST=$(claude -p "..." --output-format json | jq '.cost_usd')

TOTAL_COST=$(echo "$TOTAL_COST + $COST" | bc)

echo "Custo acumulado: \$$TOTAL_COST"

Executar e validar

Torne o script executavel e rode-o:

$ chmod +x batch-review.sh

$ ./batch-review.sh

$ ls reviews/

Verifique que cada arquivo .py gerou um .review.md correspondente no diretorio reviews/.

Gerar relatorio consolidado

Combine todos os reviews em um unico relatorio:

$ cat reviews/*.review.md | claude -p "Consolide estes reviews em um relatorio unico com prioridades" > relatorio-final.md

O relatorio final deve conter uma visao geral dos problemas encontrados, ordenados por severidade.

✅ Criterios de Sucesso

☐ Executou claude -p com prompt simples

☐ Usou --output-format json com jq

☐ Criou script com loop bash funcional

☐ Aplicou --allowedTools para seguranca

☐ Processou multiplos arquivos em batch

☐ Gerou relatorio consolidado

📋 Resumo do Modulo

✓

Modo headless e non-interactive - Claude Code funciona como ferramenta CLI pura, sem interface interativa.

✓

claude -p para one-shot prompts - Envia prompt, recebe resposta, processo encerra. Composavel com Unix pipes.

✓

JSON output para parsing programatico - Use --output-format json + jq para extrair dados estruturados da resposta.

✓

--allowedTools garante seguranca - Whitelist de ferramentas e essencial em automacao sem supervisao.

✓

Loops bash para batch processing - Processe dezenas de arquivos automaticamente com for/while + claude -p.

✓

CI/CD com GitHub Actions - Integre o Claude como revisor automatico de PRs no seu pipeline.

Proximo Passo:

Trilha 2 - CLAUDE.md: Configuracao e Contexto de Projeto

← Modulo Anterior Voltar para Trilha Proxima Trilha →