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 as opções de CLI que você precisa:

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. Nem todas as opções de CLI se combinam com -p. Claude Code rejeita --bg e rejeita --cloud com uma descrição de tarefa, com um erro nomeando o conflito; --cloud com um ID de sessão e -p em vez disso enfileira uma mensagem nessa sessão na nuvem e sai. As opções que você combinará com -p geralmente incluem:

• --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?"

Claude Code sai com código 0 em caso de sucesso e com um código diferente de zero quando a execução falha, para que seus scripts possam ramificar no status de saída. Se você passar um sinalizador inválido, Claude Code relata o erro para stderr antes do início da execução. Quando uma falha ocorre dentro da execução, como autenticação ausente, Claude Code imprime a falha como resultado em stdout.

Comece mais rápido com modo bare

Adicione --bare para reduzir o tempo de inicialização pulando a descoberta automática de hooks, skills, comandos personalizados, subagentos, 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ê. Um diretório que você nomeia com --add-dir é uma exceção parcial: o modo bare carrega skills de sua pasta .claude/skills/, mas ainda pula suas pastas .claude/commands/ e .claude/agents/. Skills de diretórios adicionais cobre o que carrega e o que não carrega.

Sem --bare, uma sessão -p executa os hooks no settings.json de um projeto e conecta os servidores em seu .mcp.json, mesmo em uma pasta que você nunca confiou. Uma sessão -p não mostra nenhum diálogo de confiança de workspace e nenhum prompt de aprovação por servidor. O que é executado antes de você confiar em uma pasta cobre cada tipo de conteúdo de repositório sob -p e como mantê-lo fora.

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. Defina ANTHROPIC_API_KEY antes de executá-lo, porque o modo bare não usa seu login de assinatura:

claude --bare -p "Summarize README.md" --allowedTools "Read"

No modo bare, Claude Code nunca lê credenciais OAuth ou o keychain do sistema. Para a API Anthropic, defina ANTHROPIC_API_KEY no ambiente, com uma chave criada no Claude Console, ou forneça um apiKeyHelper no JSON --settings. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuam a ler suas próprias credenciais de provedor como de costume.

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:

Tarefas em segundo plano ao sair

Se Claude iniciar uma tarefa Bash em segundo plano durante uma execução de claude -p, por exemplo um servidor de desenvolvimento ou uma compilação de observação, esse shell será encerrado cerca de cinco segundos após Claude retornar seu resultado final e stdin ter sido fechado. O período de carência permite que uma tarefa que termina logo após o resultado ainda entregue sua saída.

Se Claude iniciar um subagentos em segundo plano ou fluxo de trabalho, claude -p em vez disso permanece aberto até que esse trabalho seja concluído, porque seu resultado faz parte da saída final.

Por padrão, a espera termina após 10 minutos de espera contínua inativa, para que um subagentos ou fluxo de trabalho travado não possa manter o processo aberto indefinidamente. Nesse ponto, Claude Code para o que ainda está em execução e descarta seu resultado parcial. Para alterar o limite, defina CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou defina-o como 0 para aguardar sem um.

Se Claude iniciar uma observação Monitor durante uma execução de claude -p, Claude Code aguarda a observação até que ela expire ou o limite de dez minutos termine a espera, o que vier primeiro. Enquanto aguarda, Claude continua respondendo ao que a observação relata. Por padrão, uma observação expira cinco minutos após Claude iniciá-la.

Parar uma execução com SIGTERM

Se você parar uma execução de claude -p com SIGTERM, por exemplo com kill ou de um supervisor de processo, Claude Code sai com código 143. Claude Code deixa a volta que estava em progresso inacabada e não registra nenhum resultado para ela. Para encerrar a volta em vez disso, envie SIGINT ou chame interrupt() do Agent SDK, antes de parar o processo.

No SIGTERM, Claude Code encerra a árvore de processos de qualquer comando Bash que ainda está em execução. Claude Code então executa hooks SessionEnd e sai. Ao sair, Claude Code não inicia nenhuma nova chamada de ferramenta, não envia nenhuma nova solicitação de modelo e não executa nenhum hook além de SessionEnd. Se a execução estava no meio de um comando ou aguardando uma resposta a um prompt de permissão quando o sinal chegou, Claude Code trata essa etapa da seguinte forma:

• Executando um comando: Claude Code registra o comando como eliminado na sessão.
• Aguardando uma resposta a um prompt de permissão: se você enviar SIGTERM para o processo, Claude Code deixa o prompt sem resposta. Se seu programa fechar a sessão através do Agent SDK, o SDK encerra a entrada de Claude Code antes de enviar qualquer sinal, e Claude Code cancela o prompt assim que a entrada termina.

Quando você retoma a sessão, Claude Code continua a volta que SIGTERM deixou inacabada.

Exemplos

Estes exemplos destacam padrões comuns de CLI. Quando um comando nomeia um arquivo como auth.py ou build-error.txt, substitua por um arquivo do seu próprio projeto. Em CI ou outros ambientes com script, adicione --bare para que Claude Code inicie sem carregar os hooks, plugins, memória automática ou CLAUDE.md do host.

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. Ambas as figuras são estimativas do lado do cliente e podem diferir da sua fatura real.

Se Claude Code não conseguir ler stdin, por exemplo porque o processo que o iniciou desconectou sua extremidade, Claude Code imprime um aviso para stderr e continua com o prompt da linha de comando. Antes da v2.1.211, um stdin ilegível no Windows causava falha na sessão ou a fazia sair silenciosamente sem saída.

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.\""
  }
}

Execute com npm run lint:claude.

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"]}'

Se o valor não for um JSON Schema válido, claude sai com Error: --json-schema is not a valid JSON Schema seguido pelo diagnóstico do validador. Claude Code aceita esquemas que usam a palavra-chave format, como "format": "email", mas trata format como uma anotação e não a impõe. Antes da v2.1.205, Claude Code ignorava silenciosamente um esquema inválido e retornava texto não estruturado, e tratava qualquer esquema contendo format como inválido.

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

A última linha do stream é uma mensagem result com o texto de resposta final, custo e metadados de sessão.

Se seu consumidor ler o stream lentamente, Claude Code aguarda a fila de saída drenar antes de sair, dimensionando a espera com o quanto ainda está na fila, limitado a 30 segundos. Antes da v2.1.214, a espera de saída era limitada a cerca de dois segundos, o que poderia cortar o final de uma resposta grande.

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'

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

Seguir mensagens de subagentes

Mensagens de subagentes aparecem no stream como mensagens assistant e user cujo campo parent_tool_use_id é o ID da chamada de ferramenta que gerou o subagente. Mensagens da conversa principal carregam null nesse campo.

A primeira mensagem de um subagente em execução em primeiro plano é uma mensagem user carregando o prompt que o conduz. Após essa primeira mensagem, Claude Code emite:

• Por padrão: os blocos tool_use e tool_result do subagente.
• Com --forward-subagent-text ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: os blocos de texto e pensamento do subagente também, para que você possa reconstruir a transcrição de cada subagente. Isso requer Claude Code v2.1.211 ou posterior.

Quando você habilita uma das opções, Claude Code encaminha mensagens de subagentes em cada profundidade de aninhamento: quando um subagente gera seu próprio subagente, as mensagens do subagente aninhado carregam o ID da chamada de ferramenta Agent que o gerou em parent_tool_use_id, para que você possa reconstruir a árvore de aninhamento completa seguindo esses IDs. Antes da v2.1.219, mensagens de subagentes aninhados não apareciam no stream.

Skills que executam em um subagente aparecem no stream da mesma forma: a primeira mensagem da skill bifurcada é uma mensagem user carregando o conteúdo da skill que conduz a execução. Se você habilitar uma das opções, o stream também carrega os blocos de texto e pensamento da skill bifurcada. Antes da v2.1.265, apenas os blocos tool_use e tool_result de uma skill bifurcada apareciam no stream.

Lidar com tentativas de API

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. Na v2.1.246 ou posterior, quando um 401 ou 403 rejeita uma credencial apiKeyHelper, Claude Code faz as duas primeiras tentativas silenciosamente sem evento, depois emite o evento como usual a partir da terceira tentativa consecutiva em diante. As tentativas silenciosas ainda contam para attempt. Você pode usar o evento para mostrar progresso de repetição em sua própria interface.

Ler metadados de sessão

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 eventos de inicialização o precedam:

• eventos plugin_install, quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está definido.
• eventos hook_started, hook_progress e hook_response, enquanto um hook SessionStart ou Setup configurado é executado. Estes fazem stream conforme o hook os produz. Claude Code v2.1.169 através v2.1.203 os entregou em um lote após o hook ser concluído, ainda à frente de system/init; v2.1.204 restaurou a entrega ao vivo.

O evento também carrega uma matriz capabilities opcional de strings nomeando os comportamentos do protocolo que esta versão do Claude Code implementa, como interrupt_receipt_v1 ou interrupt_cancel_queued_v1. Verifique-a para detectar recursos em vez de comparar strings de versão, e ignore valores que você não reconheça. O campo requer Claude Code v2.1.205 ou posterior e está ausente em versões anteriores. Consulte SDKSystemMessage para a lista de capacidades.

Falhar CI quando um plugin ou servidor MCP não carrega

Use os campos de plugin no evento system/init para capturar um plugin que não foi carregado:

Use os campos de servidor MCP da mesma forma. Quando você passa --mcp-config com -p, Claude Code aguarda servidores ainda pendentes antes de executar a primeira volta, até o tempo limite de inicialização MCP_TIMEOUT, 30 segundos por padrão. Um servidor remoto com uma lista de ferramentas em cache pula a espera, mostra pending em system/init e se conecta em sua primeira chamada de ferramenta. A espera requer Claude Code v2.1.221 ou posterior.

Claude Code valida cada entrada --mcp-config na inicialização e pula entradas que falham na validação, por exemplo uma entrada url sem type. A execução continua e sai limpa, então verifique esses campos para capturar um servidor que nunca foi carregado:

Quando você executa o comando manualmente em um terminal, Claude Code também imprime um aviso de inicialização para stderr, como Warning: 1 MCP server skipped due to invalid config:, seguido pela razão de cada entrada pulada. Quando você redireciona stderr, ou quando um programa como um executor de CI ou um host SDK o captura, Claude Code não imprime aviso e relata as entradas puladas apenas no campo mcp_server_errors. O aviso requer Claude Code v2.1.219 ou posterior.

Rastrear instalações de plugin

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.

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. Para -p, o modo de permissão inicial integrado é Manual em todos os planos, então passe o modo de permissão que você deseja:

• auto: passe --permission-mode auto para ter um classificador revisar a maioria das ações em vez de você
• dontAsk: Claude Code nega qualquer chamada que de outra forma solicitaria, o que é útil para execuções de CI bloqueadas. Ações que não precisam de aprovação no modo Manual ainda são executadas, como leituras de arquivo em seus diretórios de trabalho e o conjunto de comandos somente leitura, e também ações que suas entradas --allowedTools ou regras permissions.allow cobrem. AskUserQuestion, ferramentas de conector que sua organização definiu como ask, e ferramentas MCP marcadas requiresUserInteraction são negadas mesmo quando uma regra de permissão corresponde
• acceptEdits: Claude escreve arquivos sem solicitar, e Claude Code aprova automaticamente comandos comuns do sistema de arquivos como mkdir, touch, mv e cp. As ações que nenhum modo aprova automaticamente ainda se aplicam. Além do conjunto de comandos somente leitura, outros comandos de shell e solicitações de rede ainda precisam de uma entrada --allowedTools ou uma regra permissions.allow. Consulte o que acceptEdits aprova automaticamente para a lista completa

Este exemplo aplica correções de lint com acceptEdits como a linha de base:

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

Desativar prompts de permissão em execuções autônomas

Passe --permission-prompts none quando ninguém estiver disponível para responder prompts de permissão, por exemplo em um trabalho agendado. O sinalizador é mais importante quando sua execução tem um host de permissão: um aplicativo Agent SDK com um callback canUseTool, ou uma ferramenta MCP que você passa com --permission-prompt-tool. Sem o sinalizador, sua execução aguarda que esse host responda cada solicitação de permissão.

Com o sinalizador, sua execução não consulta o host ou aguarda por ele. Qualquer coisa que solicitaria é negada a menos que um hook PermissionRequest a permita, Claude é informado que ninguém pode aprovar a solicitação e não deve tentar novamente, e a execução continua. Em uma execução -p sem host, essas solicitações são negadas de qualquer forma, e o sinalizador também diz a Claude não tentar novamente. Regras de permissão, hooks PermissionRequest e o modo de permissão que você definir ainda decidem cada chamada primeiro; Claude Code nega apenas as solicitações que nada mais resolve.

Este exemplo executa uma tarefa autônoma em modo auto. O classificador revisa cada ação como usual, e Claude Code nega qualquer coisa que teria caído de volta para um prompt:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Com --permission-prompts none, Claude Code remove as ferramentas que precisam de uma resposta de uma pessoa, como AskUserQuestion, para que Claude não possa chamá-las. Qualquer solicitação de elicitação MCP que nenhum hook Elicitation responde é cancelada.

Com --output-format stream-json, negações aparecem como mensagens de sistema permission_denied, e a mensagem de resultado final as lista em permission_denials.

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. Salve como um script de shell, por exemplo review.sh:

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

No script, "$1" representa o primeiro argumento que você passa na linha de comando. Execute bash review.sh 123 e o shell substitui "$1" por 123, então o script busca o diff para PR 123. Claude Code imprime a revisão como JSON, com o texto no campo result.

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. Na Claude Code v2.1.257 ou posterior, quando você passa --continue, Claude Code abre uma sessão em background que terminou, mas não uma que ainda está em execução. 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"

Você pode executar os dois comandos de diretórios diferentes: Claude Code encontra a sessão por seu ID em qualquer projeto nesta máquina. Antes da v2.1.223, Claude Code procurava o ID apenas no diretório do projeto atual e seus git worktrees, então você tinha que executar ambos os comandos do mesmo diretório.

No lugar do ID da sessão, você pode passar para --resume o caminho absoluto para o arquivo de transcrição .jsonl de uma sessão, e Claude Code continua a conversa armazenada nesse arquivo.

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