Claude Code SDK

O Claude Code SDK permite executar o Claude Code como um subprocesso, fornecendo uma maneira de construir assistentes de codificação e ferramentas alimentadas por IA que aproveitam as capacidades do Claude.

O SDK está disponível para uso em linha de comando, TypeScript e Python.

Autenticação

Para usar o Claude Code SDK, recomendamos criar uma chave de API dedicada:

Crie uma chave de API da Anthropic no Console da Anthropic
Em seguida, defina a variável de ambiente ANTHROPIC_API_KEY. Recomendamos armazenar esta chave de forma segura (ex. usando um segredo do Github)

Uso básico do SDK

O Claude Code SDK permite que você use o Claude Code em modo não interativo a partir de suas aplicações.

Linha de comando

Aqui estão alguns exemplos básicos para o SDK de linha de comando:

# Execute um único prompt e saia (modo de impressão)
$ claude -p "Escreva uma função para calcular números de Fibonacci"

# Usando um pipe para fornecer stdin
$ echo "Explique este código" | claude -p

# Saída em formato JSON com metadados
$ claude -p "Gere uma função hello world" --output-format json

# Transmita saída JSON conforme ela chega
$ claude -p "Construa um componente React" --output-format stream-json

TypeScript

O SDK TypeScript está incluído no pacote principal @anthropic-ai/claude-code no NPM:

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "Escreva um haiku sobre foo.py",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

O SDK TypeScript aceita todos os argumentos suportados pelo SDK de linha de comando, bem como:

Argumento	Descrição	Padrão
`abortController`	Controlador de aborto	`new AbortController()`
`cwd`	Diretório de trabalho atual	`process.cwd()`
`executable`	Qual runtime JavaScript usar	`node` quando executando com Node.js, `bun` quando executando com Bun
`executableArgs`	Argumentos para passar ao executável	`[]`
`pathToClaudeCodeExecutable`	Caminho para o executável Claude Code	Executável que vem com `@anthropic-ai/claude-code`

Python

O SDK Python está disponível como claude-code-sdk no PyPI:

pip install claude-code-sdk

Pré-requisitos:

Python 3.10+
Node.js
Claude Code CLI: npm install -g @anthropic-ai/claude-code

Uso básico:

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="Escreva um haiku sobre foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

O SDK Python aceita todos os argumentos suportados pelo SDK de linha de comando através da classe ClaudeCodeOptions:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="Você é um assistente útil",
    cwd=Path("/path/to/project"),  # Pode ser string ou Path
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="Olá", options=options):
    print(message)

Uso avançado

A documentação abaixo usa o SDK de linha de comando como exemplo, mas também pode ser usada com os SDKs TypeScript e Python.

Conversas de múltiplas rodadas

Para conversas de múltiplas rodadas, você pode retomar conversas ou continuar a partir da sessão mais recente:

# Continue a conversa mais recente
$ claude --continue

# Continue e forneça um novo prompt
$ claude --continue "Agora refatore isso para melhor desempenho"

# Retome uma conversa específica por ID de sessão
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Retome em modo de impressão (não interativo)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Atualize os testes"

# Continue em modo de impressão (não interativo)
$ claude -p --continue "Adicione tratamento de erros"

Prompts de sistema personalizados

Você pode fornecer prompts de sistema personalizados para orientar o comportamento do Claude:

# Substitua o prompt do sistema (funciona apenas com --print)
$ claude -p "Construa uma API REST" --system-prompt "Você é um engenheiro backend sênior. Foque em segurança, desempenho e manutenibilidade."

# Prompt de sistema com requisitos específicos
$ claude -p "Crie um esquema de banco de dados" --system-prompt "Você é um arquiteto de banco de dados. Use as melhores práticas do PostgreSQL e inclua indexação adequada."

Você também pode anexar instruções ao prompt de sistema padrão:

# Anexe prompt de sistema (funciona apenas com --print)
$ claude -p "Construa uma API REST" --append-system-prompt "Depois de escrever código, certifique-se de fazer uma revisão de código por conta própria."

Configuração MCP

O Model Context Protocol (MCP) permite que você estenda o Claude Code com ferramentas e recursos adicionais de servidores externos. Usando a flag --mcp-config, você pode carregar servidores MCP que fornecem capacidades especializadas como acesso a banco de dados, integrações de API ou ferramentas personalizadas.

Crie um arquivo de configuração JSON com seus servidores MCP:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Em seguida, use-o com o Claude Code:

# Carregue servidores MCP da configuração
$ claude -p "Liste todos os arquivos no projeto" --mcp-config mcp-servers.json

# Importante: Ferramentas MCP devem ser explicitamente permitidas usando --allowedTools
# Ferramentas MCP seguem o formato: mcp__$serverName__$toolName
$ claude -p "Procure por comentários TODO" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Use uma ferramenta MCP para lidar com prompts de permissão em modo não interativo
$ claude -p "Implante a aplicação" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

Ao usar ferramentas MCP, você deve explicitamente permiti-las usando a flag --allowedTools. Nomes de ferramentas MCP seguem o padrão mcp__<serverName>__<toolName> onde:

serverName é a chave do seu arquivo de configuração MCP
toolName é a ferramenta específica fornecida por esse servidor

Esta medida de segurança garante que ferramentas MCP sejam usadas apenas quando explicitamente permitidas.

Se você especificar apenas o nome do servidor (ou seja, mcp__<serverName>), todas as ferramentas desse servidor serão permitidas.

Padrões glob (ex., mcp__go*) não são suportados.

Ferramenta de prompt de permissão personalizada

Opcionalmente, use --permission-prompt-tool para passar uma ferramenta MCP que usaremos para verificar se o usuário concede ou não permissões ao modelo para invocar uma determinada ferramenta. Quando o modelo invoca uma ferramenta, o seguinte acontece:

Primeiro verificamos as configurações de permissão: todos os arquivos settings.json, bem como --allowedTools e --disallowedTools passados para o SDK; se uma dessas permite ou nega a chamada da ferramenta, prosseguimos com a chamada da ferramenta
Caso contrário, invocamos a ferramenta MCP que você forneceu em --permission-prompt-tool

A ferramenta MCP --permission-prompt-tool recebe o nome da ferramenta e entrada, e deve retornar um payload JSON-stringified com o resultado. O payload deve ser um dos seguintes:

// chamada de ferramenta é permitida
{
  "behavior": "allow",
  "updatedInput": {...}, // entrada atualizada, ou apenas retorne a entrada original
}

// chamada de ferramenta é negada
{
  "behavior": "deny",
  "message": "..." // string legível por humanos explicando por que a permissão foi negada
}

Por exemplo, uma implementação de ferramenta de prompt de permissão MCP em TypeScript pode parecer assim:

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simule uma verificação de permissão - aprove se a entrada contém "allow", caso contrário negue',
  {
    tool_name: z.string().describe("A ferramenta solicitando permissão"),
    input: z.object({}).passthrough().describe("A entrada para a ferramenta"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permissão negada pela ferramenta de teste approval_prompt",
                }
          ),
        },
      ],
    };
  }
);

Para usar esta ferramenta, adicione seu servidor MCP (ex. com --mcp-config), então invoque o SDK assim:

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

Notas de uso:

Use updatedInput para dizer ao modelo que o prompt de permissão mutou sua entrada; caso contrário, defina updatedInput para a entrada original, como no exemplo acima. Por exemplo, se a ferramenta mostra um diff de edição de arquivo para o usuário e permite que eles editem o diff manualmente, a ferramenta de prompt de permissão deve retornar essa edição atualizada.
O payload deve ser JSON-stringified

Opções CLI disponíveis

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

Flag	Descrição	Exemplo
`--print`, `-p`	Execute em modo não interativo	`claude -p "consulta"`
`--output-format`	Especifique formato de saída (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Retome uma conversa por ID de sessão	`claude --resume abc123`
`--continue`, `-c`	Continue a conversa mais recente	`claude --continue`
`--verbose`	Habilite log detalhado	`claude --verbose`
`--max-turns`	Limite rodadas agênticas em modo não interativo	`claude --max-turns 3`
`--system-prompt`	Substitua prompt de sistema (apenas com `--print`)	`claude --system-prompt "Instrução personalizada"`
`--append-system-prompt`	Anexe ao prompt de 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`	Carregue 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 CLI e recursos, veja a documentação de referência CLI.

Formatos de saída

O SDK suporta múltiplos formatos de saída:

Saída de texto (padrão)

Retorna apenas o texto de resposta:

$ 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 de 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 de sistema init inicial, seguida por uma lista de mensagens de usuário e assistente, seguida por uma mensagem de sistema result final com estatísticas. Cada mensagem é emitida como um objeto JSON separado.

Esquema de mensagem

Mensagens retornadas da API JSON são estritamente tipadas de acordo com o seguinte esquema:

type SDKMessage =
  // Uma mensagem do assistente
  | {
      type: "assistant";
      message: Message; // do SDK da Anthropic
      session_id: string;
    }

  // Uma mensagem do usuário
  | {
      type: "user";
      message: MessageParam; // do SDK da Anthropic
      session_id: string;
    }

  // Emitida como a última mensagem
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitida como a última mensagem, quando atingimos o número máximo de rodadas
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitida como a primeira mensagem no início de uma conversa
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Em breve publicaremos esses tipos em um formato compatível com JSONSchema. Usamos versionamento semântico para o pacote principal Claude Code para comunicar mudanças que quebram compatibilidade neste formato.

Os tipos Message e MessageParam estão disponíveis nos SDKs da Anthropic. Por exemplo, veja os SDKs TypeScript e Python da Anthropic.

Formatos de entrada

O SDK suporta múltiplos formatos de entrada:

Entrada de texto (padrão)

Texto de entrada pode ser fornecido como um argumento:

$ claude -p "Explique este código"

Ou texto de entrada pode ser canalizado via stdin:

$ echo "Explique este código" | claude -p

Entrada JSON de streaming

Um fluxo de mensagens fornecido via stdin onde cada mensagem representa uma rodada do usuário. Isso permite múltiplas rodadas 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. Mensagens são formatadas usando o formato jsonl onde cada linha de entrada é um objeto JSON completo. Entrada JSON de streaming requer -p e --output-format stream-json.

Atualmente isso é limitado a mensagens de usuário apenas de texto.

$ 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

Integração de script simples

#!/bin/bash

# Função simples para executar Claude e verificar código de saída
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Sucesso!"
    else
        echo "Erro: Claude falhou com código de saída $?" >&2
        return 1
    fi
}

# Exemplos de uso
run_claude "Escreva uma função Python para ler arquivos CSV"
run_claude "Otimize esta consulta de banco de dados" "json"

Processando arquivos com Claude

# Processe um arquivo através do Claude
$ cat mycode.py | claude -p "Revise este código para bugs"

# Processe múltiplos arquivos
$ for file in *.js; do
    echo "Processando $file..."
    claude -p "Adicione comentários JSDoc a este arquivo:" < "$file" > "${file}.documented"
done

# Use Claude em um pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Corrija todos os itens TODO neste arquivo" < "$file"
done

Gerenciamento de sessão

# Inicie uma sessão e capture o ID da sessão
$ claude -p "Inicialize um novo projeto" --output-format json | jq -r '.session_id' > session.txt

# Continue com a mesma sessão
$ claude -p --resume "$(cat session.txt)" "Adicione testes unitários"

Melhores práticas

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

# Analise resposta JSON com jq
result=$(claude -p "Gere 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 de múltiplas rodadas

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

Aplicações do mundo real

O Claude Code SDK permite integrações poderosas com seu fluxo de trabalho de desenvolvimento. Um exemplo notável são as GitHub Actions do Claude Code, que usa o SDK para fornecer revisão de código automatizada, criação de PR e capacidades de triagem de issues diretamente no seu fluxo de trabalho do GitHub.

Recursos relacionados

Uso e controles CLI - Documentação completa da CLI
Integração GitHub Actions - Automatize seu fluxo de trabalho GitHub com Claude
Fluxos de trabalho comuns - Guias passo a passo para casos de uso comuns

Primeiros passos

Construir com Claude

Implantação

Administração

Referência

Recursos

Autenticação

Uso básico do SDK

Linha de comando

TypeScript

Python

Uso avançado

Conversas de múltiplas rodadas

Prompts de sistema personalizados

Configuração MCP

Ferramenta de prompt de permissão personalizada

Opções CLI disponíveis

Formatos de saída

Saída de texto (padrão)

Saída JSON

Saída JSON de streaming

Esquema de mensagem

Formatos de entrada

Entrada de texto (padrão)

Entrada JSON de streaming

Exemplos

Integração de script simples

Processando arquivos com Claude

Gerenciamento de sessão

Melhores práticas

Aplicações do mundo real

Recursos relacionados

Primeiros passos

Construir com Claude

Implantação

Administração

Referência

Recursos

​Autenticação

​Uso básico do SDK

​Linha de comando

​TypeScript

​Python

​Uso avançado

​Conversas de múltiplas rodadas

​Prompts de sistema personalizados

​Configuração MCP

​Ferramenta de prompt de permissão personalizada

​Opções CLI disponíveis

​Formatos de saída

​Saída de texto (padrão)

​Saída JSON

​Saída JSON de streaming

​Esquema de mensagem

​Formatos de entrada

​Entrada de texto (padrão)

​Entrada JSON de streaming

​Exemplos

​Integração de script simples

​Processando arquivos com Claude

​Gerenciamento de sessão

​Melhores práticas

​Aplicações do mundo real

​Recursos relacionados

Autenticação

Uso básico do SDK

Linha de comando

TypeScript

Python

Uso avançado

Conversas de múltiplas rodadas

Prompts de sistema personalizados

Configuração MCP

Ferramenta de prompt de permissão personalizada

Opções CLI disponíveis

Formatos de saída

Saída de texto (padrão)

Saída JSON

Saída JSON de streaming

Esquema de mensagem

Formatos de entrada

Entrada de texto (padrão)

Entrada JSON de streaming

Exemplos

Integração de script simples

Processando arquivos com Claude

Gerenciamento de sessão

Melhores práticas

Aplicações do mundo real

Recursos relacionados