Das Claude Code SDK ermöglicht es, Claude Code als Unterprozess auszuführen und bietet eine Möglichkeit, KI-gestützte Coding-Assistenten und Tools zu erstellen, die Claudes Fähigkeiten nutzen.

Das SDK ist für die Verwendung über die Kommandozeile, TypeScript und Python verfügbar.

Authentifizierung

Das Claude Code SDK unterstützt mehrere Authentifizierungsmethoden:

Anthropic API-Schlüssel

Um das Claude Code SDK direkt mit Anthropics API zu verwenden, empfehlen wir die Erstellung eines dedizierten API-Schlüssels:

  1. Erstellen Sie einen Anthropic API-Schlüssel in der Anthropic Console
  2. Setzen Sie dann die Umgebungsvariable ANTHROPIC_API_KEY. Wir empfehlen, diesen Schlüssel sicher zu speichern (z.B. mit einem Github Secret)

Drittanbieter-API-Anmeldedaten

Das SDK unterstützt auch Drittanbieter-API-Provider:

  • Amazon Bedrock: Setzen Sie die Umgebungsvariable CLAUDE_CODE_USE_BEDROCK=1 und konfigurieren Sie AWS-Anmeldedaten
  • Google Vertex AI: Setzen Sie die Umgebungsvariable CLAUDE_CODE_USE_VERTEX=1 und konfigurieren Sie Google Cloud-Anmeldedaten

Für detaillierte Konfigurationsanweisungen für Drittanbieter-Provider siehe die Dokumentation zu Amazon Bedrock und Google Vertex AI.

Grundlegende SDK-Verwendung

Das Claude Code SDK ermöglicht es Ihnen, Claude Code im nicht-interaktiven Modus aus Ihren Anwendungen zu verwenden.

Kommandozeile

Hier sind einige grundlegende Beispiele für das Kommandozeilen-SDK:

# Führe eine einzelne Eingabeaufforderung aus und beende (Print-Modus)
$ claude -p "Schreibe eine Funktion zur Berechnung von Fibonacci-Zahlen"

# Verwende eine Pipe, um stdin bereitzustellen
$ echo "Erkläre diesen Code" | claude -p

# Ausgabe im JSON-Format mit Metadaten
$ claude -p "Generiere eine Hello-World-Funktion" --output-format json

# Streame JSON-Ausgabe, während sie ankommt
$ claude -p "Erstelle eine React-Komponente" --output-format stream-json

TypeScript

Das TypeScript SDK ist im Hauptpaket @anthropic-ai/claude-code auf NPM enthalten:

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

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "Schreibe ein Haiku über foo.py",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

Das TypeScript SDK akzeptiert alle Argumente, die vom Kommandozeilen-SDK unterstützt werden, sowie:

ArgumentBeschreibungStandard
abortControllerAbort-Controllernew AbortController()
cwdAktuelles Arbeitsverzeichnisprocess.cwd()
executableWelche JavaScript-Laufzeit zu verwendennode bei Ausführung mit Node.js, bun bei Ausführung mit Bun
executableArgsArgumente, die an die ausführbare Datei übergeben werden[]
pathToClaudeCodeExecutablePfad zur Claude Code-AusführungsdateiAusführbare Datei, die mit @anthropic-ai/claude-code geliefert wird

Python

Das Python SDK ist als claude-code-sdk auf PyPI verfügbar:

pip install claude-code-sdk

Voraussetzungen:

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

Grundlegende Verwendung:

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="Schreibe ein Haiku über foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

Das Python SDK akzeptiert alle Argumente, die vom Kommandozeilen-SDK unterstützt werden, über die ClaudeCodeOptions-Klasse:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="Du bist ein hilfreicher Assistent",
    cwd=Path("/pfad/zum/projekt"),  # Kann String oder Path sein
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

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

Erweiterte Verwendung

Die nachfolgende Dokumentation verwendet das Kommandozeilen-SDK als Beispiel, kann aber auch mit den TypeScript- und Python-SDKs verwendet werden.

Multi-Turn-Gespräche

Für Multi-Turn-Gespräche können Sie Gespräche fortsetzen oder von der neuesten Sitzung aus weitermachen:

# Setze das neueste Gespräch fort
$ claude --continue

# Setze fort und gib eine neue Eingabeaufforderung an
$ claude --continue "Refaktoriere das jetzt für bessere Leistung"

# Setze ein bestimmtes Gespräch anhand der Sitzungs-ID fort
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Setze im Print-Modus fort (nicht-interaktiv)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Aktualisiere die Tests"

# Setze im Print-Modus fort (nicht-interaktiv)
$ claude -p --continue "Füge Fehlerbehandlung hinzu"

Benutzerdefinierte System-Prompts

Sie können benutzerdefinierte System-Prompts bereitstellen, um Claudes Verhalten zu steuern:

# Überschreibe System-Prompt (funktioniert nur mit --print)
$ claude -p "Erstelle eine REST-API" --system-prompt "Du bist ein Senior-Backend-Ingenieur. Konzentriere dich auf Sicherheit, Leistung und Wartbarkeit."

# System-Prompt mit spezifischen Anforderungen
$ claude -p "Erstelle ein Datenbankschema" --system-prompt "Du bist ein Datenbankarchitekt. Verwende PostgreSQL-Best-Practices und schließe ordnungsgemäße Indizierung ein."

Sie können auch Anweisungen an den Standard-System-Prompt anhängen:

# Hänge System-Prompt an (funktioniert nur mit --print)
$ claude -p "Erstelle eine REST-API" --append-system-prompt "Nachdem du Code geschrieben hast, führe unbedingt eine Code-Review durch."

MCP-Konfiguration

Das Model Context Protocol (MCP) ermöglicht es Ihnen, Claude Code mit zusätzlichen Tools und Ressourcen von externen Servern zu erweitern. Mit dem --mcp-config-Flag können Sie MCP-Server laden, die spezialisierte Fähigkeiten wie Datenbankzugriff, API-Integrationen oder benutzerdefinierte Tools bereitstellen.

Erstellen Sie eine JSON-Konfigurationsdatei mit Ihren MCP-Servern:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/pfad/zu/erlaubten/dateien"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ihr-github-token"
      }
    }
  }
}

Verwenden Sie es dann mit Claude Code:

# Lade MCP-Server aus der Konfiguration
$ claude -p "Liste alle Dateien im Projekt auf" --mcp-config mcp-servers.json

# Wichtig: MCP-Tools müssen explizit mit --allowedTools erlaubt werden
# MCP-Tools folgen dem Format: mcp__$serverName__$toolName
$ claude -p "Suche nach TODO-Kommentaren" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Verwende ein MCP-Tool für die Behandlung von Berechtigungsaufforderungen im nicht-interaktiven Modus
$ claude -p "Stelle die Anwendung bereit" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

Bei der Verwendung von MCP-Tools müssen Sie diese explizit mit dem --allowedTools-Flag erlauben. MCP-Tool-Namen folgen dem Muster mcp__<serverName>__<toolName>, wobei:

  • serverName der Schlüssel aus Ihrer MCP-Konfigurationsdatei ist
  • toolName das spezifische Tool ist, das von diesem Server bereitgestellt wird

Diese Sicherheitsmaßnahme stellt sicher, dass MCP-Tools nur verwendet werden, wenn sie explizit erlaubt sind.

Wenn Sie nur den Servernamen angeben (d.h. mcp__<serverName>), werden alle Tools von diesem Server erlaubt.

Glob-Muster (z.B. mcp__go*) werden nicht unterstützt.

Benutzerdefiniertes Berechtigungsaufforderungs-Tool

Verwenden Sie optional --permission-prompt-tool, um ein MCP-Tool zu übergeben, das wir verwenden werden, um zu überprüfen, ob der Benutzer dem Modell die Berechtigung erteilt, ein bestimmtes Tool aufzurufen. Wenn das Modell ein Tool aufruft, passiert Folgendes:

  1. Wir überprüfen zuerst die Berechtigungseinstellungen: alle settings.json-Dateien sowie --allowedTools und --disallowedTools, die an das SDK übergeben wurden; wenn eine davon den Tool-Aufruf erlaubt oder verweigert, fahren wir mit dem Tool-Aufruf fort
  2. Andernfalls rufen wir das MCP-Tool auf, das Sie in --permission-prompt-tool bereitgestellt haben

Das --permission-prompt-tool MCP-Tool erhält den Tool-Namen und die Eingabe und muss eine JSON-stringifizierte Nutzlast mit dem Ergebnis zurückgeben. Die Nutzlast muss eine der folgenden sein:

// Tool-Aufruf ist erlaubt
{
  "behavior": "allow",
  "updatedInput": {...}, // aktualisierte Eingabe, oder geben Sie einfach die ursprüngliche Eingabe zurück
}

// Tool-Aufruf wird verweigert
{
  "behavior": "deny",
  "message": "..." // menschenlesbare Zeichenkette, die erklärt, warum die Berechtigung verweigert wurde
}

Zum Beispiel könnte eine TypeScript MCP-Berechtigungsaufforderungs-Tool-Implementierung so aussehen:

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

server.tool(
  "approval_prompt",
  'Simuliere eine Berechtigungsprüfung - genehmige, wenn die Eingabe "allow" enthält, andernfalls verweigere',
  {
    tool_name: z.string().describe("Das Tool, das eine Berechtigung anfordert"),
    input: z.object({}).passthrough().describe("Die Eingabe für das Tool"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Berechtigung vom Test-approval_prompt-Tool verweigert",
                }
          ),
        },
      ],
    };
  }
);

Um dieses Tool zu verwenden, fügen Sie Ihren MCP-Server hinzu (z.B. mit --mcp-config) und rufen Sie dann das SDK so auf:

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

Verwendungshinweise:

  • Verwenden Sie updatedInput, um dem Modell mitzuteilen, dass die Berechtigungsaufforderung seine Eingabe verändert hat; setzen Sie andernfalls updatedInput auf die ursprüngliche Eingabe, wie im obigen Beispiel. Wenn das Tool beispielsweise einem Benutzer ein Datei-Edit-Diff zeigt und ihm erlaubt, das Diff manuell zu bearbeiten, sollte das Berechtigungsaufforderungs-Tool diese aktualisierte Bearbeitung zurückgeben.
  • Die Nutzlast muss JSON-stringifiziert sein

Verfügbare CLI-Optionen

Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:

FlagBeschreibungBeispiel
--print, -pIm nicht-interaktiven Modus ausführenclaude -p "Abfrage"
--output-formatAusgabeformat angeben (text, json, stream-json)claude -p --output-format json
--resume, -rEin Gespräch anhand der Sitzungs-ID fortsetzenclaude --resume abc123
--continue, -cDas neueste Gespräch fortsetzenclaude --continue
--verboseAusführliche Protokollierung aktivierenclaude --verbose
--max-turnsAgentische Wendungen im nicht-interaktiven Modus begrenzenclaude --max-turns 3
--system-promptSystem-Prompt überschreiben (nur mit --print)claude --system-prompt "Benutzerdefinierte Anweisung"
--append-system-promptAn System-Prompt anhängen (nur mit --print)claude --append-system-prompt "Benutzerdefinierte Anweisung"
--allowedToolsLeerzeichengetrennte Liste erlaubter Tools, oder

Zeichenkette mit kommagetrennte Liste erlaubter Tools
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLeerzeichengetrennte Liste verweigerter Tools, oder

Zeichenkette mit kommagetrennte Liste verweigerter Tools
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configMCP-Server aus einer JSON-Datei ladenclaude --mcp-config servers.json
--permission-prompt-toolMCP-Tool für die Behandlung von Berechtigungsaufforderungen (nur mit --print)claude --permission-prompt-tool mcp__auth__prompt

Für eine vollständige Liste der CLI-Optionen und -Funktionen siehe die Dokumentation zur CLI-Referenz.

Ausgabeformate

Das SDK unterstützt mehrere Ausgabeformate:

Textausgabe (Standard)

Gibt nur den Antworttext zurück:

$ claude -p "Erkläre Datei src/components/Header.tsx"
# Ausgabe: Dies ist eine React-Komponente, die...

JSON-Ausgabe

Gibt strukturierte Daten einschließlich Metadaten zurück:

$ claude -p "Wie funktioniert die Datenschicht?" --output-format json

Antwortformat:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Der Antworttext hier...",
  "session_id": "abc123"
}

Streaming-JSON-Ausgabe

Streamt jede Nachricht, während sie empfangen wird:

$ claude -p "Erstelle eine Anwendung" --output-format stream-json

Jedes Gespräch beginnt mit einer anfänglichen init-Systemnachricht, gefolgt von einer Liste von Benutzer- und Assistentennachrichten, gefolgt von einer abschließenden result-Systemnachricht mit Statistiken. Jede Nachricht wird als separates JSON-Objekt ausgegeben.

Nachrichtenschema

Nachrichten, die von der JSON-API zurückgegeben werden, sind streng typisiert gemäß dem folgenden Schema:

type SDKMessage =
  // Eine Assistentennachricht
  | {
      type: "assistant";
      message: Message; // aus Anthropic SDK
      session_id: string;
    }

  // Eine Benutzernachricht
  | {
      type: "user";
      message: MessageParam; // aus Anthropic SDK
      session_id: string;
    }

  // Als letzte Nachricht ausgegeben
  | {
      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;
    }

  // Als letzte Nachricht ausgegeben, wenn wir die maximale Anzahl von Wendungen erreicht haben
  | {
      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;
    }

  // Als erste Nachricht zu Beginn eines Gesprächs ausgegeben
  | {
      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";
    };

Wir werden diese Typen bald in einem JSONSchema-kompatiblen Format veröffentlichen. Wir verwenden semantische Versionierung für das Haupt-Claude-Code-Paket, um Breaking Changes an diesem Format zu kommunizieren.

Message- und MessageParam-Typen sind in Anthropic SDKs verfügbar. Siehe zum Beispiel die Anthropic TypeScript- und Python-SDKs.

Eingabeformate

Das SDK unterstützt mehrere Eingabeformate:

Texteingabe (Standard)

Eingabetext kann als Argument bereitgestellt werden:

$ claude -p "Erkläre diesen Code"

Oder Eingabetext kann über stdin weitergeleitet werden:

$ echo "Erkläre diesen Code" | claude -p

Streaming-JSON-Eingabe

Ein Stream von Nachrichten, die über stdin bereitgestellt werden, wobei jede Nachricht eine Benutzerwendung darstellt. Dies ermöglicht mehrere Wendungen eines Gesprächs, ohne die claude-Binärdatei neu zu starten, und ermöglicht es, dem Modell Anleitung zu geben, während es eine Anfrage verarbeitet.

Jede Nachricht ist ein JSON-‘Benutzernachricht’-Objekt, das dem gleichen Format wie das Ausgabenachrichtenschema folgt. Nachrichten werden mit dem jsonl-Format formatiert, wobei jede Eingabezeile ein vollständiges JSON-Objekt ist. Streaming-JSON-Eingabe erfordert -p und --output-format stream-json.

Derzeit ist dies auf reine Textnachrichten von Benutzern beschränkt.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Erkläre diesen Code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Beispiele

Einfache Skriptintegration

#!/bin/bash

# Einfache Funktion zum Ausführen von Claude und Überprüfen des Exit-Codes
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Erfolg!"
    else
        echo "Fehler: Claude ist mit Exit-Code $? fehlgeschlagen" >&2
        return 1
    fi
}

# Verwendungsbeispiele
run_claude "Schreibe eine Python-Funktion zum Lesen von CSV-Dateien"
run_claude "Optimiere diese Datenbankabfrage" "json"

Dateien mit Claude verarbeiten

# Verarbeite eine Datei durch Claude
$ cat mycode.py | claude -p "Überprüfe diesen Code auf Fehler"

# Verarbeite mehrere Dateien
$ for file in *.js; do
    echo "Verarbeite $file..."
    claude -p "Füge JSDoc-Kommentare zu dieser Datei hinzu:" < "$file" > "${file}.documented"
done

# Verwende Claude in einer Pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Behebe alle TODO-Elemente in dieser Datei" < "$file"
done

Sitzungsverwaltung

# Starte eine Sitzung und erfasse die Sitzungs-ID
$ claude -p "Initialisiere ein neues Projekt" --output-format json | jq -r '.session_id' > session.txt

# Setze mit derselben Sitzung fort
$ claude -p --resume "$(cat session.txt)" "Füge Unit-Tests hinzu"

Best Practices

  1. Verwenden Sie das JSON-Ausgabeformat für programmatisches Parsen von Antworten:

    # Parse JSON-Antwort mit jq
    result=$(claude -p "Generiere Code" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. Behandeln Sie Fehler elegant - überprüfen Sie Exit-Codes und stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Fehler aufgetreten:" >&2
        cat error.log >&2
        exit 1
    fi
    
  3. Verwenden Sie Sitzungsverwaltung für die Aufrechterhaltung des Kontexts in Multi-Turn-Gesprächen

  4. Berücksichtigen Sie Timeouts für langwierige Operationen:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout nach 5 Minuten"
    
  5. Respektieren Sie Rate-Limits bei mehreren Anfragen, indem Sie Verzögerungen zwischen Aufrufen hinzufügen

Reale Anwendungen

Das Claude Code SDK ermöglicht leistungsstarke Integrationen in Ihren Entwicklungsworkflow. Ein bemerkenswertes Beispiel sind die Claude Code GitHub Actions, die das SDK verwenden, um automatisierte Code-Review-, PR-Erstellungs- und Issue-Triage-Funktionen direkt in Ihrem GitHub-Workflow bereitzustellen.

Verwandte Ressourcen