El SDK de Claude Code permite a los desarrolladores integrar Claude Code programáticamente en sus aplicaciones. Permite ejecutar Claude Code como un subproceso, proporcionando una forma de crear asistentes y herramientas de codificación potenciados por IA que aprovechan las capacidades de Claude.

El SDK está disponible para uso en línea de comandos, TypeScript y Python.

Autenticación

Para usar el SDK de Claude Code, recomendamos crear una clave API dedicada:

  1. Crea una clave API de Anthropic en la Consola de Anthropic
  2. Luego, establece la variable de entorno ANTHROPIC_API_KEY. Recomendamos almacenar esta clave de forma segura (por ejemplo, usando un secreto de Github)

Uso básico del SDK

El SDK de Claude Code te permite usar Claude Code en modo no interactivo desde tus aplicaciones.

Línea de comandos

Aquí hay algunos ejemplos básicos para el SDK de línea de comandos:

# Ejecuta un solo prompt y sale (modo impresión)
$ claude -p "Escribe una función para calcular números de Fibonacci"

# Usando una tubería para proporcionar stdin
$ echo "Explica este código" | claude -p

# Salida en formato JSON con metadatos
$ claude -p "Genera una función de hola mundo" --output-format json

# Transmite la salida JSON a medida que llega
$ claude -p "Construye un componente React" --output-format stream-json

TypeScript

El SDK de TypeScript está incluido en el paquete principal @anthropic-ai/claude-code en NPM:

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

const messages: SDKMessage[] = [];

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

console.log(messages);

El SDK de TypeScript acepta todos los argumentos compatibles con el SDK de línea de comandos, así como:

ArgumentoDescripciónValor predeterminado
abortControllerControlador de abortonew AbortController()
cwdDirectorio de trabajo actualprocess.cwd()
executableQué entorno de ejecución JavaScript usarnode cuando se ejecuta con Node.js, bun cuando se ejecuta con Bun
executableArgsArgumentos para pasar al ejecutable[]
pathToClaudeCodeExecutableRuta al ejecutable de Claude CodeEjecutable que viene con @anthropic-ai/claude-code

Python

El SDK de Python está disponible como claude-code-sdk en PyPI:

pip install claude-code-sdk

Requisitos previos:

  • Python 3.10+
  • Node.js
  • CLI de 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="Escribe un haiku sobre foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

El SDK de Python acepta todos los argumentos compatibles con el SDK de línea de comandos a través de la clase ClaudeCodeOptions:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="Eres un asistente útil",
    cwd=Path("/path/to/project"),  # Puede ser string o Path
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

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

Uso avanzado

La documentación a continuación utiliza el SDK de línea de comandos como ejemplo, pero también se puede usar con los SDK de TypeScript y Python.

Conversaciones de múltiples turnos

Para conversaciones de múltiples turnos, puedes reanudar conversaciones o continuar desde la sesión más reciente:

# Continuar la conversación más reciente
$ claude --continue

# Continuar y proporcionar un nuevo prompt
$ claude --continue "Ahora refactoriza esto para un mejor rendimiento"

# Reanudar una conversación específica por ID de sesión
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Reanudar en modo impresión (no interactivo)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Actualiza las pruebas"

# Continuar en modo impresión (no interactivo)
$ claude -p --continue "Añade manejo de errores"

Prompts de sistema personalizados

Puedes proporcionar prompts de sistema personalizados para guiar el comportamiento de Claude:

# Anular el prompt de sistema (solo funciona con --print)
$ claude -p "Construye una API REST" --system-prompt "Eres un ingeniero backend senior. Concéntrate en la seguridad, el rendimiento y la mantenibilidad."

# Prompt de sistema con requisitos específicos
$ claude -p "Crea un esquema de base de datos" --system-prompt "Eres un arquitecto de bases de datos. Utiliza las mejores prácticas de PostgreSQL e incluye indexación adecuada."

También puedes añadir instrucciones al prompt de sistema predeterminado:

# Añadir al prompt de sistema (solo funciona con --print)
$ claude -p "Construye una API REST" --append-system-prompt "Después de escribir código, asegúrate de revisarlo tú mismo."

Configuración MCP

El Protocolo de Contexto del Modelo (MCP) te permite extender Claude Code con herramientas y recursos adicionales de servidores externos. Usando la bandera --mcp-config, puedes cargar servidores MCP que proporcionan capacidades especializadas como acceso a bases de datos, integraciones de API o herramientas personalizadas.

Crea un archivo de configuración JSON con tus 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"
      }
    }
  }
}

Luego úsalo con Claude Code:

# Cargar servidores MCP desde la configuración
$ claude -p "Lista todos los archivos en el proyecto" --mcp-config mcp-servers.json

# Importante: las herramientas MCP deben estar explícitamente permitidas usando --allowedTools
# Las herramientas MCP siguen el formato: mcp__$serverName__$toolName
$ claude -p "Busca comentarios TODO" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Usar una herramienta MCP para manejar solicitudes de permisos en modo no interactivo
$ claude -p "Despliega la aplicación" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

Al usar herramientas MCP, debes permitirlas explícitamente usando la bandera --allowedTools. Los nombres de las herramientas MCP siguen el patrón mcp__<serverName>__<toolName> donde:

  • serverName es la clave de tu archivo de configuración MCP
  • toolName es la herramienta específica proporcionada por ese servidor

Esta medida de seguridad garantiza que las herramientas MCP solo se utilicen cuando estén explícitamente permitidas.

Si especificas solo el nombre del servidor (es decir, mcp__<serverName>), se permitirán todas las herramientas de ese servidor.

No se admiten patrones glob (por ejemplo, mcp__go*).

Herramienta personalizada de solicitud de permisos

Opcionalmente, usa --permission-prompt-tool para pasar una herramienta MCP que usaremos para verificar si el usuario otorga al modelo permisos para invocar una herramienta determinada. Cuando el modelo invoca una herramienta, ocurre lo siguiente:

  1. Primero verificamos la configuración de permisos: todos los archivos settings.json, así como --allowedTools y --disallowedTools pasados al SDK; si uno de estos permite o deniega la llamada a la herramienta, procedemos con la llamada a la herramienta
  2. De lo contrario, invocamos la herramienta MCP que proporcionaste en --permission-prompt-tool

La herramienta MCP --permission-prompt-tool recibe el nombre de la herramienta y la entrada, y debe devolver una carga útil JSON-stringified con el resultado. La carga útil debe ser una de las siguientes:

// la llamada a la herramienta está permitida
{
  "behavior": "allow",
  "updatedInput": {...}, // entrada actualizada, o simplemente devuelve la entrada original
}

// la llamada a la herramienta está denegada
{
  "behavior": "deny",
  "message": "..." // cadena legible por humanos que explica por qué se denegó el permiso
}

Por ejemplo, una implementación de herramienta MCP de solicitud de permisos en TypeScript podría verse así:

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

server.tool(
  "approval_prompt",
  'Simula una verificación de permisos - aprueba si la entrada contiene "allow", de lo contrario deniega',
  {
    tool_name: z.string().describe("La herramienta que solicita permiso"),
    input: z.object({}).passthrough().describe("La entrada para la herramienta"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permiso denegado por la herramienta de prueba approval_prompt",
                }
          ),
        },
      ],
    };
  }
);

Para usar esta herramienta, agrega tu servidor MCP (por ejemplo, con --mcp-config), luego invoca el SDK así:

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

Notas de uso:

  • Usa updatedInput para indicar al modelo que la solicitud de permiso modificó su entrada; de lo contrario, establece updatedInput a la entrada original, como en el ejemplo anterior. Por ejemplo, si la herramienta muestra un diff de edición de archivo al usuario y les permite editar el diff manualmente, la herramienta de solicitud de permiso debe devolver esa edición actualizada.
  • La carga útil debe estar en formato JSON-stringified

Opciones CLI disponibles

El SDK aprovecha todas las opciones CLI disponibles en Claude Code. Aquí están las principales para el uso del SDK:

BanderaDescripciónEjemplo
--print, -pEjecutar en modo no interactivoclaude -p "consulta"
--output-formatEspecificar formato de salida (text, json, stream-json)claude -p --output-format json
--resume, -rReanudar una conversación por ID de sesiónclaude --resume abc123
--continue, -cContinuar la conversación más recienteclaude --continue
--verboseHabilitar registro detalladoclaude --verbose
--max-turnsLimitar turnos agénticos en modo no interactivoclaude --max-turns 3
--system-promptAnular prompt de sistema (solo con --print)claude --system-prompt "Instrucción personalizada"
--append-system-promptAñadir al prompt de sistema (solo con --print)claude --append-system-prompt "Instrucción personalizada"
--allowedToolsLista separada por espacios de herramientas permitidas, o

cadena de lista separada por comas de herramientas permitidas
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLista separada por espacios de herramientas denegadas, o

cadena de lista separada por comas de herramientas denegadas
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configCargar servidores MCP desde un archivo JSONclaude --mcp-config servers.json
--permission-prompt-toolHerramienta MCP para manejar solicitudes de permisos (solo con --print)claude --permission-prompt-tool mcp__auth__prompt

Para una lista completa de opciones y características CLI, consulta la documentación Uso de CLI.

Formatos de salida

El SDK admite múltiples formatos de salida:

Salida de texto (predeterminado)

Devuelve solo el texto de respuesta:

$ claude -p "Explica el archivo src/components/Header.tsx"
# Salida: Este es un componente React que muestra...

Salida JSON

Devuelve datos estructurados que incluyen metadatos:

$ claude -p "¿Cómo funciona la capa de datos?" --output-format json

Formato de respuesta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "El texto de respuesta aquí...",
  "session_id": "abc123"
}

Salida JSON en streaming

Transmite cada mensaje a medida que se recibe:

$ claude -p "Construye una aplicación" --output-format stream-json

Cada conversación comienza con un mensaje de sistema inicial init, seguido de una lista de mensajes de usuario y asistente, seguido de un mensaje de sistema final result con estadísticas. Cada mensaje se emite como un objeto JSON separado.

Esquema de mensajes

Los mensajes devueltos por la API JSON están estrictamente tipados según el siguiente esquema:

type SDKMessage =
  // Un mensaje del asistente
  | {
      type: "assistant";
      message: Message; // del SDK de Anthropic
      session_id: string;
    }

  // Un mensaje del usuario
  | {
      type: "user";
      message: MessageParam; // del SDK de Anthropic
      session_id: string;
    }

  // Emitido como el último mensaje
  | {
      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;
    }

  // Emitido como el último mensaje, cuando hemos alcanzado el 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;
    }

  // Emitido como el primer mensaje al inicio de una conversación
  | {
      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";
    };

Pronto publicaremos estos tipos en un formato compatible con JSONSchema. Usamos versionado semántico para el paquete principal de Claude Code para comunicar cambios importantes en este formato.

Los tipos Message y MessageParam están disponibles en los SDK de Anthropic. Por ejemplo, consulta los SDK de Anthropic TypeScript y Python.

Ejemplos

Integración simple de scripts

#!/bin/bash

# Función simple para ejecutar Claude y verificar el código de salida
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "¡Éxito!"
    else
        echo "Error: Claude falló con código de salida $?" >&2
        return 1
    fi
}

# Ejemplos de uso
run_claude "Escribe una función Python para leer archivos CSV"
run_claude "Optimiza esta consulta de base de datos" "json"

Procesamiento de archivos con Claude

# Procesar un archivo a través de Claude
$ cat mycode.py | claude -p "Revisa este código en busca de errores"

# Procesar múltiples archivos
$ for file in *.js; do
    echo "Procesando $file..."
    claude -p "Añade comentarios JSDoc a este archivo:" < "$file" > "${file}.documented"
done

# Usar Claude en una tubería
$ grep -l "TODO" *.py | while read file; do
    claude -p "Arregla todos los elementos TODO en este archivo" < "$file"
done

Gestión de sesiones

# Iniciar una sesión y capturar el ID de sesión
$ claude -p "Inicializa un nuevo proyecto" --output-format json | jq -r '.session_id' > session.txt

# Continuar con la misma sesión
$ claude -p --resume "$(cat session.txt)" "Añade pruebas unitarias"

Mejores prácticas

  1. Usa el formato de salida JSON para el análisis programático de respuestas:

    # Analizar respuesta JSON con jq
    result=$(claude -p "Generar código" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. Maneja los errores con elegancia - verifica los códigos de salida y stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Ocurrió un error:" >&2
        cat error.log >&2
        exit 1
    fi
    
  3. Usa la gestión de sesiones para mantener el contexto en conversaciones de múltiples turnos

  4. Considera los tiempos de espera para operaciones de larga duración:

    timeout 300 claude -p "$complex_prompt" || echo "Tiempo de espera agotado después de 5 minutos"
    
  5. Respeta los límites de tasa cuando realices múltiples solicitudes añadiendo retrasos entre llamadas

Aplicaciones del mundo real

El SDK de Claude Code permite integraciones potentes con tu flujo de trabajo de desarrollo. Un ejemplo notable son las Acciones de GitHub de Claude Code, que utilizan el SDK para proporcionar capacidades automatizadas de revisión de código, creación de PR y clasificación de problemas directamente en tu flujo de trabajo de GitHub.

Recursos relacionados