O SDK do Claude Code permite que desenvolvedores integrem programaticamente o Claude Code em suas aplicações. Ele possibilita executar o Claude Code como um subprocesso, fornecendo uma maneira de construir assistentes de codificação e ferramentas com 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 SDK do Claude Code, recomendamos criar uma chave de API dedicada:

  1. Crie uma chave de API Anthropic no Console Anthropic
  2. Em seguida, defina a variável de ambiente ANTHROPIC_API_KEY. Recomendamos armazenar esta chave de forma segura (por exemplo, usando um secret do Github)

Uso básico do SDK

O SDK do Claude Code permite que você use o Claude Code no 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 a 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:

ArgumentoDescriçãoPadrão
abortControllerControlador de abortonew AbortController()
cwdDiretório de trabalho atualprocess.cwd()
executableQual runtime JavaScript usarnode quando executando com Node.js, bun quando executando com Bun
executableArgsArgumentos para passar ao executável[]
pathToClaudeCodeExecutableCaminho para o executável Claude CodeExecutá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
  • CLI do Claude Code: 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últiplos turnos

Para conversas de múltiplos turnos, 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 pelo ID da sessão
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

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

# Continue no 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. Concentre-se 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 ao prompt do sistema (funciona apenas com --print)
$ claude -p "Construa uma API REST" --append-system-prompt "Depois de escrever o código, certifique-se de revisar seu próprio código."

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: as ferramentas MCP devem ser explicitamente permitidas usando --allowedTools
# As 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 no 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 permitir explicitamente seu uso com a flag --allowedTools. Os nomes das 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 as 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 (por exemplo, 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 ao modelo permissões para invocar uma determinada ferramenta. Quando o modelo invoca uma ferramenta, o seguinte acontece:

  1. 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 configurações permitir ou negar a chamada da ferramenta, prosseguimos com a chamada da ferramenta
  2. 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 a entrada, e deve retornar uma carga útil JSON-stringified com o resultado. A carga útil deve ser uma das 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 ser 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 contiver "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 (por exemplo, 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 informar ao modelo que o prompt de permissão modificou sua entrada; caso contrário, defina updatedInput para a entrada original, como no exemplo acima. Por exemplo, se a ferramenta mostrar um diff de edição de arquivo ao usuário e permitir que eles editem o diff manualmente, a ferramenta de prompt de permissão deve retornar essa edição atualizada.
  • A carga útil deve ser JSON-stringified

Opções de CLI disponíveis

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

FlagDescriçãoExemplo
--print, -pExecutar em modo não interativoclaude -p "consulta"
--output-formatEspecificar formato de saída (text, json, stream-json)claude -p --output-format json
--resume, -rRetomar uma conversa pelo ID da sessãoclaude --resume abc123
--continue, -cContinuar a conversa mais recenteclaude --continue
--verboseAtivar registro detalhadoclaude --verbose
--max-turnsLimitar turnos agênticos no modo não interativoclaude --max-turns 3
--system-promptSubstituir o prompt do sistema (apenas com --print)claude --system-prompt "Instrução personalizada"
--append-system-promptAnexar ao prompt do sistema (apenas com --print)claude --append-system-prompt "Instrução personalizada"
--allowedToolsLista 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"
--disallowedToolsLista 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-configCarregar servidores MCP de um arquivo JSONclaude --mcp-config servers.json
--permission-prompt-toolFerramenta 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 e recursos da CLI, consulte a documentação Uso da CLI.

Formatos de saída

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

Saída de texto (padrão)

Retorna apenas o texto da 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 da resposta aqui...",
  "session_id": "abc123"
}

Saída JSON em 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 do assistente, seguida por uma mensagem final do sistema result com estatísticas. Cada mensagem é emitida como um objeto JSON separado.

Esquema de mensagem

As mensagens retornadas pela API JSON são estritamente tipadas de acordo com o seguinte esquema:

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

  // Uma mensagem do usuário
  | {
      type: "user";
      message: MessageParam; // do SDK 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 turnos
  | {
      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 do Claude Code para comunicar mudanças significativas neste formato.

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

Exemplos

Integração simples de script

#!/bin/bash

# Função simples para executar o Claude e verificar o 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 em busca de 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 o 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

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

    # Analise a 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')
    
  2. Trate erros com elegância - verifique códigos de saída e stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Ocorreu um erro:" >&2
        cat error.log >&2
        exit 1
    fi
    
  3. Use gerenciamento de sessão para manter o contexto em conversas de múltiplos turnos

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

    timeout 300 claude -p "$complex_prompt" || echo "Tempo esgotado após 5 minutos"
    
  5. Respeite os limites de taxa ao fazer múltiplas solicitações, adicionando atrasos entre as chamadas

Aplicações do mundo real

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

Recursos relacionados