Modo headless

Execute Claude Code programaticamente sem interface de usuário interativa

Visão Geral

O modo headless permite executar Claude Code programaticamente a partir de scripts de linha de comando e ferramentas de automação sem qualquer interface de usuário interativa.

Uso Básico

A interface de linha de comando principal para Claude Code é o comando claude. Use a flag --print (ou -p) para executar em modo não interativo e imprimir o resultado final:

claude -p "Prepare minhas alterações e escreva um conjunto de commits para elas" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

Opções de Configuração

O SDK aproveita todas as opções de CLI disponíveis no Claude Code. Aqui estão as principais para uso do SDK:

Flag	Descrição	Exemplo
--print, -p	Executar em modo não interativo	claude -p "consulta"
--output-format	Especificar formato de saída (text, json, stream-json)	claude -p --output-format json
--resume, -r	Retomar uma conversa por ID de sessão	claude --resume abc123
--continue, -c	Continuar a conversa mais recente	claude --continue
--verbose	Habilitar log detalhado	claude --verbose
--append-system-prompt	Anexar ao prompt do sistema (apenas com --print)	claude --append-system-prompt "Instrução personalizada"
--allowedTools	Lista separada por espaços de ferramentas permitidas, ou string de lista separada por vírgulas de ferramentas permitidas	claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools	Lista separada por espaços de ferramentas negadas, ou string de lista separada por vírgulas de ferramentas negadas	claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-config	Carregar servidores MCP de um arquivo JSON	claude --mcp-config servers.json
--permission-prompt-tool	Ferramenta MCP para lidar com prompts de permissão (apenas com --print)	claude --permission-prompt-tool mcp__auth__prompt

Para uma lista completa de opções de CLI e recursos, consulte a documentação de referência da CLI.

Conversas Multi-turno

Para conversas multi-turno, você pode retomar conversas ou continuar da sessão mais recente:

# Continuar a conversa mais recente
claude --continue "Agora refatore isso para melhor desempenho"

# Retomar uma conversa específica por ID de sessão
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Atualize os testes"

# Retomar em modo não interativo
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Corrija todos os problemas de linting" --no-interactive

Formatos de Saída

Saída de Texto (Padrão)

claude -p "Explique o arquivo src/components/Header.tsx"
# Saída: Este é um componente React mostrando...

Saída JSON

Retorna dados estruturados incluindo metadados:

claude -p "Como funciona a camada de dados?" --output-format json

Formato de resposta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "O texto da resposta aqui...",
  "session_id": "abc123"
}

Saída JSON de Streaming

Transmite cada mensagem conforme é recebida:

claude -p "Construa uma aplicação" --output-format stream-json

Cada conversa começa com uma mensagem inicial do sistema init, seguida por uma lista de mensagens do usuário e assistente, seguida por uma mensagem final do sistema result com estatísticas. Cada mensagem é emitida como um objeto JSON separado.

Formatos de Entrada

Entrada de Texto (Padrão)

# Argumento direto
claude -p "Explique este código"

# Do stdin
echo "Explique este código" | claude -p

Entrada JSON de Streaming

Um fluxo de mensagens fornecido via stdin onde cada mensagem representa um turno do usuário. Isso permite múltiplos turnos de uma conversa sem relançar o binário claude e permite fornecer orientação ao modelo enquanto ele está processando uma solicitação.

Cada mensagem é um objeto JSON ‘Mensagem do usuário’, seguindo o mesmo formato que o esquema de mensagem de saída. As mensagens são formatadas usando o formato jsonl onde cada linha de entrada é um objeto JSON completo. A entrada JSON de streaming requer -p e --output-format stream-json.

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explique este código"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Exemplos de Integração de Agente

Bot de Resposta a Incidentes SRE

#!/bin/bash

# Agente automatizado de resposta a incidentes
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incidente: $incident_description (Severidade: $severity)" \
      --append-system-prompt "Você é um especialista em SRE. Diagnostique o problema, avalie o impacto e forneça itens de ação imediatos." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Uso
investigate_incident "API de pagamento retornando erros 500" "high"

Revisão de Segurança Automatizada

# Agente de auditoria de segurança para pull requests
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Você é um engenheiro de segurança. Revise este PR para vulnerabilidades, padrões inseguros e problemas de conformidade." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Uso e salvar em arquivo
audit_pr 123 > security-report.json

Assistente Jurídico Multi-turno

# Revisão de documento jurídico com persistência de sessão
session_id=$(claude -p "Iniciar sessão de revisão jurídica" --output-format json | jq -r '.session_id')

# Revisar contrato em múltiplas etapas
claude -p --resume "$session_id" "Revisar contract.pdf para cláusulas de responsabilidade"
claude -p --resume "$session_id" "Verificar conformidade com requisitos GDPR"
claude -p --resume "$session_id" "Gerar resumo executivo dos riscos"

Melhores Práticas

• Use formato de saída JSON para análise programática de respostas:

  # Analisar resposta JSON com jq
  result=$(claude -p "Gerar código" --output-format json)
  code=$(echo "$result" | jq -r '.result')
  cost=$(echo "$result" | jq -r '.cost_usd')
  

• Trate erros graciosamente - verifique códigos de saída e stderr:

  if ! claude -p "$prompt" 2>error.log; then
      echo "Erro ocorreu:" >&2
      cat error.log >&2
      exit 1
  fi
  

• Use gerenciamento de sessão para manter contexto em conversas multi-turno

• Considere timeouts para operações de longa duração:

  timeout 300 claude -p "$complex_prompt" || echo "Timeout após 5 minutos"
  

• Respeite limites de taxa ao fazer múltiplas solicitações adicionando atrasos entre chamadas

Recursos Relacionados

• Uso e controles da CLI - Documentação completa da CLI
• Fluxos de trabalho comuns - Guias passo a passo para casos de uso comuns