El SDK de Claude Code permite ejecutar Claude Code como un subproceso, proporcionando una forma de construir asistentes de codificación y herramientas impulsadas 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 (ej. 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:

# Ejecutar una sola consulta y salir (modo de impresión)
$ claude -p "Escribe una función para calcular números de Fibonacci"

# Usar un pipe para proporcionar stdin
$ echo "Explica este código" | claude -p

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

# Transmitir 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 soportados por el SDK de línea de comandos, así como:

ArgumentoDescripciónPor defecto
abortControllerControlador de abortonew AbortController()
cwdDirectorio de trabajo actualprocess.cwd()
executableQué runtime de 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

Prerrequisitos:

  • 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 soportados por 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("/ruta/al/proyecto"),  # 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 usa el SDK de línea de comandos como ejemplo, pero también puede usarse con los SDKs 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 una nueva consulta
$ claude --continue "Ahora refactoriza esto para mejor rendimiento"

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

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

# Continuar en modo de 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:

# Sobrescribir prompt de sistema (solo funciona con --print)
$ claude -p "Construye una API REST" --system-prompt "Eres un ingeniero backend senior. Enfócate en seguridad, rendimiento y 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. Usa las mejores prácticas de PostgreSQL e incluye indexación apropiada."

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

# Añadir 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 hacer una revisión de código por ti mismo."

Configuración MCP

El Protocolo de Contexto de 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",
        "/ruta/a/archivos/permitidos"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "tu-token-de-github"
      }
    }
  }
}

Luego úsalo con Claude Code:

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

# Importante: Las herramientas MCP deben ser 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 prompts 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

Cuando uses herramientas MCP, debes permitirlas explícitamente usando la bandera --allowedTools. Los nombres de 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 asegura que las herramientas MCP solo se usen cuando están explícitamente permitidas.

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

Los patrones glob (ej., mcp__go*) no están soportados.

Herramienta de prompt de permisos personalizada

Opcionalmente, usa --permission-prompt-tool para pasar una herramienta MCP que usaremos para verificar si el usuario otorga permisos al modelo para invocar una herramienta dada. 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 niega 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:

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

// la llamada a la herramienta es denegada
{
  "behavior": "deny",
  "message": "..." // cadena legible por humanos explicando por qué se negó el permiso
}

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

const server = new McpServer({
  name: "Servidor MCP de prompt de permisos de prueba",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simular una verificación de permisos - aprobar si la entrada contiene "allow", de lo contrario denegar',
  {
    tool_name: z.string().describe("La herramienta solicitando 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 approval_prompt de prueba",
                }
          ),
        },
      ],
    };
  }
);

Para usar esta herramienta, añade tu servidor MCP (ej. 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 decirle al modelo que el prompt de permisos mutó 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 le permite editar el diff manualmente, la herramienta de prompt de permisos debería devolver esa edición actualizada.
  • La carga útil debe ser JSON-stringified

Opciones CLI disponibles

El SDK aprovecha todas las opciones CLI disponibles en Claude Code. Aquí están las principales para 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 logging verbosoclaude --verbose
--max-turnsLimitar turnos agénticos en modo no interactivoclaude --max-turns 3
--system-promptSobrescribir 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 prompts de permisos (solo con --print)claude --permission-prompt-tool mcp__auth__prompt

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

Formatos de salida

El SDK soporta múltiples formatos de salida:

Salida de texto (por defecto)

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 incluyendo 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 init inicial, seguido de una lista de mensajes de usuario y asistente, seguido de un mensaje de sistema result final con estadísticas. Cada mensaje se emite como un objeto JSON separado.

Esquema de mensajes

Los mensajes devueltos desde 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 que rompen la compatibilidad con este formato.

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

Formatos de entrada

El SDK soporta múltiples formatos de entrada:

Entrada de texto (por defecto)

El texto de entrada puede proporcionarse como argumento:

$ claude -p "Explica este código"

O el texto de entrada puede enviarse por pipe vía stdin:

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

Entrada JSON en streaming

Un flujo de mensajes proporcionado vía stdin donde cada mensaje representa un turno del usuario. Esto permite múltiples turnos de una conversación sin relanzar el binario claude y permite proporcionar orientación al modelo mientras está procesando una solicitud.

Cada mensaje es un objeto JSON ‘Mensaje de usuario’, siguiendo el mismo formato que el esquema de mensaje de salida. Los mensajes se formatean usando el formato jsonl donde cada línea de entrada es un objeto JSON completo. La entrada JSON en streaming requiere -p y --output-format stream-json.

Actualmente esto está limitado a mensajes de usuario solo de texto.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explica este código"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Ejemplos

Integración de script simple

#!/bin/bash

# Función simple para ejecutar Claude y verificar 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"

Procesando 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 un pipeline
$ 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 formato de salida JSON para análisis programático de respuestas:

    # Analizar respuesta JSON con jq
    result=$(claude -p "Genera código" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. Maneja errores con gracia - verifica 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 gestión de sesiones para mantener contexto en conversaciones de múltiples turnos

  4. Considera timeouts para operaciones de larga duración:

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

Aplicaciones del mundo real

El SDK de Claude Code permite integraciones poderosas con tu flujo de trabajo de desarrollo. Un ejemplo notable son las GitHub Actions de Claude Code, que usa el SDK para proporcionar capacidades de revisión de código automatizada, creación de PR y triaje de issues directamente en tu flujo de trabajo de GitHub.

Recursos relacionados