Executar Claude Code programaticamente

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 a flag -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 tomar decisões com base no status de saída. Se você passar uma flag inválida, 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, subagentes, plugins instalados, servidores MCP, memória automática e CLAUDE.md. Sem ele, claude -p descobre e carrega esses itens como uma sessão interativa faria, 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 .claude/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 uma flag:

Para carregar	Use
Adições ao system prompt	`--append-system-prompt`, `--append-system-prompt-file`
Configurações	`--settings <file-or-json>`
Servidores MCP	`--mcp-config <file-or-json>`
Agentes personalizados	`--agents <file-or-json>`
Um plugin	`--plugin-dir <path>`, `--plugin-url <url>`

O modo bare também limita o que acontece enquanto a sessão é executada:

Servidores MCP: apenas os servidores fornecidos na linha de comando se conectam, por exemplo com --mcp-config. Em uma sessão interativa, Claude Code também pula a conexão automática com o IDE, a menos que você passe --ide.
Lembretes do sistema: Claude recebe seus prompts e os resultados das ferramentas sem os lembretes do sistema que Claude Code adicionaria junto com eles. Por exemplo, Claude não é informado quando um arquivo que leu anteriormente muda no disco, e não recebe a lista de skills disponíveis, incluindo skills de uma pasta --add-dir.
Tarefas em segundo plano: nenhuma é executada. Um comando que atinge seu timeout para em vez de ir para o segundo plano.

Antes da v2.1.286, esses limites valiam apenas parcialmente: uma sessão interativa --bare conectava os servidores MCP que uma sessão normal conectaria, toda sessão --bare enviava lembretes do sistema e as tarefas em segundo plano continuavam disponíveis.

--bare é o modo recomendado para chamadas com script e SDK, e se tornará o padrão para -p em uma versão futura.

Tarefas em segundo plano ao sair

Depois que Claude termina seu turno e stdin é fechado, uma execução de claude -p pode permanecer aberta para aguardar o trabalho em segundo plano que Claude iniciou. A menos que um comando em segundo plano iniciado pela conversa principal ainda esteja em execução, Claude Code, por padrão, para o que ainda estiver em execução após 10 minutos de espera contínua inativa e descarta seu resultado parcial. Para alterar o limite de 10 minutos, defina CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou defina-o como 0 para aguardar sem um. A execução aguarda trabalho em segundo plano, como comandos em segundo plano, subagentes e fluxos de trabalho, observações do Monitor e despertares pendentes do /loop:

Comandos em segundo plano: para um comando que a conversa principal iniciou, por exemplo um servidor de desenvolvimento ou um build em modo de observação, a execução aguarda até que o comando saia ou atinja seu limite de tempo. Claude então faz mais um turno com o resultado. Enquanto o comando é executado, o limite de 10 minutos não encerra a espera.
Subagentes e fluxos de trabalho em segundo plano: a execução permanece aberta até que esse trabalho seja concluído, porque seu resultado faz parte da saída final.
Observações do Monitor: a execução aguarda até que a observação atinja o timeout ou o limite de 10 minutos encerre a espera, o que vier primeiro. Enquanto aguarda, Claude continua respondendo ao que a observação relata. Por padrão, uma observação atinge o timeout cinco minutos após Claude iniciá-la.
Despertares pendentes: em uma execução cujo prompt você passou como texto em vez de com --input-format stream-json, quando Claude agendou um despertar de /loop com ritmo próprio, a execução aguarda cada despertar disparar e executa sua iteração até que o loop termine, mesmo além do limite de 10 minutos.

Quando stderr é um terminal e a execução já aguardou cinco segundos, Claude Code imprime uma linha em stderr que começa com Waiting for background work to finish e nomeia o trabalho. Com saída json ou stream-json, a linha é impressa apenas quando stdout não é um terminal, para que o JSON que seu script lê nunca a contenha. Se a execução atingir seu limite de --max-budget-usd, Claude Code para o trabalho em segundo plano restante em vez de aguardar. Quando o trabalho em segundo plano inicia outro turno, a execução imprime o resultado de cada turno com a saída text padrão e o resultado do último turno com a saída json. Antes da v2.1.295, a execução imprimia apenas o resultado do último turno também com a saída text.

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 o turno que estava em progresso inacabado e não registra nenhum resultado para ele. Para encerrar o turno 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 requisição ao modelo e não executa nenhum hook além de SessionEnd. Se a execução estava no meio de um comando ou aguardando 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 deixa o turno interrompido como está, e seu próximo prompt conduz a conversa. Para fazer com que Claude Code continue o turno interrompido ao retomar, defina CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Se o diretório de trabalho for excluído

Se o diretório de trabalho de uma sessão claude -p ou Agent SDK for excluído durante a sessão, a sessão continua em execução. Quando um turno começa enquanto o diretório está faltando, Claude Code emite uma mensagem de aviso na saída stream-json, e os comandos shell falham até que o diretório exista novamente.

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, o payload da resposta inclui total_cost_usd e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos sem consultar o painel de uso. Quando você continua uma conversa anterior com --continue ou --resume, a execução relata o total da conversa, gastos de execuções anteriores inclusos. Ambas as figuras são estimativas do lado do cliente e podem diferir da sua fatura real.

Stdin canalizado é limitado a 10MB. Se você exceder o limite, Claude Code sai com um erro claro e um status diferente de zero. Para trabalhar com entradas maiores, escreva o conteúdo em um arquivo e faça referência ao caminho do arquivo em seu prompt em vez de canalizá-lo.

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 requisiçã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.

Use uma ferramenta como jq para analisar a resposta e extrair campos específicos:

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

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

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. A flag -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 e de skills que executam em um subagente aparecem no stream como mensagens assistant e user. O campo parent_tool_use_id delas indica a qual execução cada uma pertence. Mensagens da conversa principal carregam null nesse campo. A primeira mensagem de uma skill bifurcada, ou de um subagente em execução em primeiro plano, é uma mensagem user carregando o prompt ou o conteúdo da skill que a conduz. Após essa primeira mensagem, Claude Code emite:

Por padrão: os blocos tool_use e tool_result da execução.
Com --forward-subagent-text ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: os blocos de texto e pensamento da execução também, para que você possa reconstruir a transcrição de cada execução.

Quando você habilita uma das opções, Claude Code encaminha mensagens de subagentes em cada profundidade de aninhamento, independentemente de cada um ter sido gerado com a ferramenta Agent ou iniciado como uma skill bifurcada. Em parent_tool_use_id, as mensagens do subagente aninhado carregam o ID da chamada de ferramenta Agent ou Skill que o iniciou, para que você possa reconstruir a árvore de aninhamento completa seguindo esses IDs. Uma execução que Claude inicia com uma chamada de ferramenta carrega o ID dessa chamada de ferramenta. Uma skill bifurcada que você inicia passando /<skill-name> como o prompt não tem chamada de ferramenta, então suas mensagens carregam um valor forked-command- e chegam depois que ela termina. Encontre como a execução começou na primeira coluna:

Como a execução começa	`parent_tool_use_id`	Quando suas mensagens chegam
Claude chama a ferramenta Agent a partir da conversa principal	O ID desse bloco `tool_use` do Agent	Enquanto o subagente trabalha
Claude chama a ferramenta Skill para uma skill bifurcada a partir da conversa principal	O ID desse bloco `tool_use` da Skill	Enquanto a skill bifurcada trabalha
Você passa `/<skill-name>` como o prompt	Um valor que começa com `forked-command-`	Juntas e em ordem depois que a skill bifurcada termina

Para uma skill bifurcada iniciada a partir do prompt, faça a correspondência de parent_tool_use_id pelo prefixo forked-command-, porque o nome após ele pode diferir daquele que você digitou. Se algumas dessas mensagens estiverem faltando no seu stream, verifique sua versão do Claude Code em relação a estes mínimos:

--forward-subagent-text e CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: v2.1.211 ou posterior
Encaminhamento em cada profundidade de aninhamento: v2.1.219 ou posterior
Uma skill bifurcada que Claude inicia com a ferramenta Skill a partir da conversa principal: v2.1.86 ou posterior para seus blocos tool_use e tool_result, e v2.1.265 ou posterior para sua primeira mensagem user e seus blocos de texto e pensamento
Mensagens de subagentes que uma skill bifurcada gera, e de skills bifurcadas iniciadas dentro de um subagente ou de outra skill bifurcada: v2.1.275 ou posterior
Mensagens de uma skill bifurcada que você inicia passando /<skill-name> como o prompt: v2.1.287 ou posterior

Lidar com tentativas de API

Quando uma requisiçã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.

Campo	Tipo	Descrição
`type`	`"system"`	tipo de mensagem
`subtype`	`"api_retry"`	identifica isso como um evento de repetição
`attempt`	inteiro	número da tentativa atual, começando em 1
`max_retries`	inteiro	total de novas tentativas permitidas para a causa dessa falha
`retry_delay_ms`	inteiro	milissegundos até a próxima tentativa
`error_status`	inteiro ou nulo	código de status HTTP da tentativa falhada, ou `null` quando a tentativa não obteve resposta HTTP da API
`no_response`	objeto, opcional	presente apenas quando a tentativa falhada obteve nenhum cabeçalho de resposta a tempo. `waited_ms` é quanto tempo essa tentativa aguardou e `retry_wait_ms` é quanto tempo a repetição aguardará. Requer Claude Code v2.1.261 ou posterior
`error`	string	categoria de erro: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, ou `unknown`
`uuid`	string	identificador único do evento
`session_id`	string	sessão à qual o evento pertence

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.

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. 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:

Campo	Tipo	Descrição
`plugins`	array	plugins que foram carregados com sucesso, cada um com `name` e `path`
`plugin_errors`	array	erros de tempo de carregamento de plugin, cada um com `plugin`, `type` e `message`. Inclui versões de dependência insatisfeitas e falhas de carregamento de `--plugin-dir` como um caminho ausente ou arquivo inválido. Um plugin que não foi carregado está ausente de `plugins`. A chave é omitida quando não há erros

Quando um diretório ou arquivo --plugin-dir em si falha ao carregar, sua entrada plugin_errors inclui o caminho absoluto resolvido como path. Use-o para dizer qual de vários valores --plugin-dir falhou. O campo path requer Claude Code v2.1.283 ou posterior. 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 o primeiro turno, até o timeout 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. Em um ambiente auto-hospedado, aplica-se uma espera mais curta. 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:

Campo	Tipo	Descrição
`mcp_servers`	array	servidores MCP na sessão, cada um com `name` e `status`
`mcp_server_errors`	array	entradas `--mcp-config` puladas pela validação de config, cada uma com `name`, `type` e `message`. `type` é uma categoria de pulo como `unknown_type`, `url_missing_type`, `invalid_config` ou `reserved_name`; trate valores que você não reconheça como um pulo genérico. Os servidores afetados estão ausentes de `mcp_servers`. A chave é omitida quando não há erros, então um portão de CI pode falhar em uma matriz não vazia. Requer Claude Code v2.1.219 ou posterior

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 do primeiro turno. Use estes para exibir o progresso de instalação em sua própria UI.

Campo	Tipo	Descrição
`type`	`"system"`	tipo de mensagem
`subtype`	`"plugin_install"`	identifica isso como um evento de instalação de plugin
`status`	`"started"`, `"installed"`, `"failed"`, ou `"completed"`	`started` e `completed` envolvem a instalação geral; `installed` e `failed` relatam marketplaces individuais
`name`	string, opcional	nome do marketplace, presente em `installed` e `failed`
`error`	string, opcional	mensagem de falha, presente em `failed`
`uuid`	string	identificador único do evento
`session_id`	string	sessão à qual o evento pertence

Aprovar ferramentas automaticamente

Use --allowedTools para permitir que Claude use certas ferramentas sem solicitar. Listar Read e Edit permite que Claude leia e edite arquivos sem pedir permissão, exceto leituras de caminhos de rede. Listar Bash faz o mesmo para comandos de shell, exceto em uma execução que começa em modo auto, onde Claude Code descarta uma entrada Bash simples como uma regra de permissão ampla e o modo auto avalia cada comando em vez disso. Este exemplo executa um conjunto de testes e corrige falhas com essas três ferramentas listadas:

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. Uma execução onde nada define um modo de permissão toma o modo de permissão inicial integrado, que pode ser auto, então passe 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, ferramentas MCP marcadas requiresUserInteraction e leituras de caminhos de rede 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 requisiçõ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. A flag é 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 a flag, sua execução aguarda que esse host responda cada solicitação de permissão. Com a flag, 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 a flag 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.

A flag --permission-prompts requer Claude Code v2.1.259 ou posterior. Versões anteriores a rejeitam com um erro de opção desconhecida.

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 *)"

A flag --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.

O suporte a comandos difere no modo -p:

Skills invocadas pelo usuário e comandos personalizados funcionam. Inclua /skill-name na string de prompt e Claude Code o expande antes de executar.
Comandos integrados que só são executados na interface do terminal, como /login, não estão disponíveis.
/model, /effort, /fast, /color e /rename aceitam o valor como um argumento, por exemplo /model sonnet, e /mcp sem argumento imprime um resumo de texto do status do servidor. Essas formas seguem as notas de disponibilidade de cada comando.
Para alterar uma configuração, passe key=value para /config, por exemplo /config thinking=false.
/output-style <style> alterna estilos de saída e /output-style sozinho os lista. Requer Claude Code v2.1.269 ou posterior.

Personalizar o system prompt

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 flags de system prompt para mais opções, incluindo --system-prompt para substituir completamente o prompt padrão. Se você o substituir, a execução também começa sem o snapshot do status do git.

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. 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

Agentes e trabalho paralelo

MCP

Skills

Artefatos

Automação

Guias

Solução de problemas

Executar Claude Code programaticamente

Uso básico

Comece mais rápido com modo bare

Tarefas em segundo plano ao sair

Parar uma execução com SIGTERM

Se o diretório de trabalho for excluído

Exemplos

Canalizar dados através do Claude

Adicionar Claude a um script de compilação

Obter saída estruturada

Respostas de stream

Seguir mensagens de subagentes

Lidar com tentativas de API

Ler metadados de sessão

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

Rastrear instalações de plugin

Aprovar ferramentas automaticamente

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

Criar um commit

Personalizar o system prompt

Continuar conversas

Próximas etapas

​Uso básico

​Comece mais rápido com modo bare

​Tarefas em segundo plano ao sair

​Parar uma execução com SIGTERM

​Se o diretório de trabalho for excluído

​Exemplos

​Canalizar dados através do Claude

​Adicionar Claude a um script de compilação

​Obter saída estruturada

​Respostas de stream

​Seguir mensagens de subagentes

​Lidar com tentativas de API

​Ler metadados de sessão

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

​Rastrear instalações de plugin

​Aprovar ferramentas automaticamente

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

​Criar um commit

​Personalizar o system prompt

​Continuar conversas

​Próximas etapas

Uso básico

Comece mais rápido com modo bare

Tarefas em segundo plano ao sair

Parar uma execução com SIGTERM

Se o diretório de trabalho for excluído

Exemplos

Canalizar dados através do Claude

Adicionar Claude a um script de compilação

Obter saída estruturada

Respostas de stream

Seguir mensagens de subagentes

Lidar com tentativas de API

Ler metadados de sessão

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

Rastrear instalações de plugin

Aprovar ferramentas automaticamente

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

Criar um commit

Personalizar o system prompt

Continuar conversas

Próximas etapas