Executar Claude Code programaticamente

Use o Agent SDK para executar Claude Code programaticamente a partir da CLI, Python ou TypeScript.

O Agent SDK oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code. Está disponível como uma CLI para scripts e CI/CD, ou como pacotes Python e TypeScript para controle programático completo.

Para executar Claude Code em modo não interativo, passe -p com seu prompt e qualquer opção de CLI:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Esta página aborda o uso do Agent SDK via CLI (claude -p). Para os pacotes SDK Python e TypeScript com saídas estruturadas, callbacks de aprovação de ferramentas e objetos de mensagem nativos, consulte a documentação completa do Agent SDK.

Uso básico

Adicione o sinalizador -p (ou --print) a qualquer comando claude para executá-lo de forma não interativa. Todas as opções de CLI funcionam com -p, incluindo:

• --continue para continuar conversas
• --allowedTools para aprovar ferramentas automaticamente
• --output-format para saída estruturada

Este exemplo faz uma pergunta ao Claude sobre sua base de código e imprime a resposta:

claude -p "What does the auth module do?"

Comece mais rápido com modo bare

Adicione --bare para reduzir o tempo de inicialização pulando a descoberta automática de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. Sem ele, claude -p carrega o mesmo contexto que uma sessão interativa carregaria, incluindo qualquer coisa configurada no diretório de trabalho ou ~/.claude.

O modo bare é útil para CI e scripts onde você precisa do mesmo resultado em cada máquina. Um hook no ~/.claude de um colega de trabalho ou um servidor MCP no .mcp.json do projeto não serão executados, porque o modo bare nunca os lê. Apenas os sinalizadores que você passa explicitamente têm efeito.

Este exemplo executa uma tarefa de resumo única em modo bare e pré-aprova a ferramenta Read para que a chamada seja concluída sem um prompt de permissão:

claude --bare -p "Summarize this file" --allowedTools "Read"

No modo bare, Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe qualquer contexto que você precise com um sinalizador:

O modo bare pula leituras de OAuth e keychain. A autenticação do Anthropic deve vir de ANTHROPIC_API_KEY ou um apiKeyHelper no JSON passado para --settings. Bedrock, Vertex e Foundry usam suas credenciais de provedor usuais.

Exemplos

Estes exemplos destacam padrões comuns de CLI. Para CI e outras chamadas com script, adicione --bare para que não captem o que quer que esteja configurado localmente.

Canalizar dados através do Claude

O modo não interativo lê stdin, então você pode canalizar dados e redirecionar a resposta como qualquer outra ferramenta de linha de comando.

Este exemplo canaliza um log de compilação para Claude e escreve a explicação em um arquivo:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Com --output-format json, a carga de resposta inclui total_cost_usd e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos por invocação sem consultar o painel de uso.

Adicionar Claude a um script de compilação

Você pode envolver uma chamada não interativa em um script para usar Claude como um linter ou revisor específico do projeto.

Este script package.json canaliza o diff contra main para Claude e pede que ele relate erros de digitação. Canalizar o diff significa que Claude não precisa de permissão Bash para lê-lo, e as aspas duplas escapadas mantêm o script portável para Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Obter saída estruturada

Use --output-format para controlar como as respostas são retornadas:

• text (padrão): saída de texto simples
• json: JSON estruturado com resultado, ID de sessão e metadados
• stream-json: JSON delimitado por quebra de linha para streaming em tempo real

Este exemplo retorna um resumo do projeto como JSON com metadados de sessão, com o resultado de texto no campo result:

claude -p "Summarize this project" --output-format json

Para obter saída em conformidade com um esquema específico, use --output-format json com --json-schema e uma definição de JSON Schema. A resposta inclui metadados sobre a solicitação (ID de sessão, uso, etc.) com a saída estruturada no campo structured_output.

Este exemplo extrai nomes de funções e os retorna como uma matriz de strings:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Respostas de stream

Use --output-format stream-json com --verbose e --include-partial-messages para receber tokens conforme são gerados. Cada linha é um objeto JSON representando um evento:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

O exemplo a seguir usa jq para filtrar deltas de texto e exibir apenas o texto de streaming. O sinalizador -r produz strings brutas (sem aspas) e -j une sem quebras de linha para que os tokens façam streaming continuamente:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Quando uma solicitação de API falha com um erro que pode ser repetido, Claude Code emite um evento system/api_retry antes de tentar novamente. Você pode usar isso para exibir o progresso de repetição ou implementar lógica de backoff personalizada.

O evento system/init relata metadados de sessão incluindo o modelo, ferramentas, servidores MCP e plugins carregados. É o primeiro evento no stream a menos que CLAUDE_CODE_SYNC_PLUGIN_INSTALL esteja definido, caso em que eventos plugin_install o precedem. Use os campos de plugin para falhar CI quando um plugin não foi carregado:

Quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está definido, Claude Code emite eventos system/plugin_install enquanto plugins do marketplace instalam antes da primeira volta. Use estes para exibir o progresso de instalação em sua própria UI.

Para streaming programático com callbacks e objetos de mensagem, consulte Stream responses in real-time na documentação do Agent SDK.

Aprovar ferramentas automaticamente

Use --allowedTools para permitir que Claude use certas ferramentas sem solicitar. Este exemplo executa um conjunto de testes e corrige falhas, permitindo que Claude execute comandos Bash e leia/edite arquivos sem pedir permissão:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Para definir uma linha de base para toda a sessão em vez de listar ferramentas individuais, passe um modo de permissão. dontAsk nega qualquer coisa não em suas regras permissions.allow ou no conjunto de comandos somente leitura, o que é útil para execuções de CI bloqueadas. acceptEdits permite que Claude escreva arquivos sem solicitar e também aprova automaticamente comandos comuns do sistema de arquivos, como mkdir, touch, mv e cp. Outros comandos de shell e solicitações de rede ainda precisam de uma entrada --allowedTools ou uma regra permissions.allow, caso contrário a execução é abortada quando uma é tentada:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Criar um commit

Este exemplo revisa as alterações preparadas e cria um commit com uma mensagem apropriada:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

O sinalizador --allowedTools usa sintaxe de regra de permissão. O * à direita habilita correspondência de prefixo, então Bash(git diff *) permite qualquer comando começando com git diff. O espaço antes de * é importante: sem ele, Bash(git diff*) também corresponderia a git diff-index.

Personalizar o prompt do sistema

Use --append-system-prompt para adicionar instruções mantendo o comportamento padrão do Claude Code. Este exemplo envia um diff de PR para Claude e o instrui a revisar vulnerabilidades de segurança:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Consulte system prompt flags para mais opções, incluindo --system-prompt para substituir completamente o prompt padrão.

Continuar conversas

Use --continue para continuar a conversa mais recente, ou --resume com um ID de sessão para continuar uma conversa específica. Este exemplo executa uma revisão e depois envia prompts de acompanhamento:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Se você estiver executando várias conversas, capture o ID da sessão para retomar uma específica:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Próximas etapas

• Agent SDK quickstart: construa seu primeiro agente com Python ou TypeScript
• CLI reference: todos os sinalizadores e opções de CLI
• GitHub Actions: use o Agent SDK em fluxos de trabalho do GitHub
• GitLab CI/CD: use o Agent SDK em pipelines do GitLab