Claude Code programmgesteuert ausführen

Verwenden Sie das Agent SDK, um Claude Code programmgesteuert über die CLI, Python oder TypeScript auszuführen.

Das Agent SDK bietet Ihnen die gleichen Tools, die Agent-Schleife und das Kontextmanagement, die Claude Code antreiben. Es ist als CLI für Skripte und CI/CD verfügbar oder als Python- und TypeScript-Pakete für vollständige programmgesteuerte Kontrolle.

Um Claude Code im nicht-interaktiven Modus auszuführen, übergeben Sie -p mit Ihrer Eingabeaufforderung und allen CLI-Optionen:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Diese Seite behandelt die Verwendung des Agent SDK über die CLI (claude -p). Für die Python- und TypeScript-SDK-Pakete mit strukturierten Ausgaben, Tool-Genehmigungsrückrufen und nativen Nachrichtenobjekten siehe die vollständige Agent SDK-Dokumentation.

Grundlegende Verwendung

Fügen Sie das Flag -p (oder --print) zu jedem claude-Befehl hinzu, um ihn nicht interaktiv auszuführen. Alle CLI-Optionen funktionieren mit -p, einschließlich:

• --continue zum Fortsetzen von Gesprächen
• --allowedTools zum automatischen Genehmigen von Tools
• --output-format für strukturierte Ausgabe

Dieses Beispiel stellt Claude eine Frage zu Ihrer Codebasis und gibt die Antwort aus:

claude -p "What does the auth module do?"

Schneller starten mit Bare-Modus

Fügen Sie --bare hinzu, um die Startzeit zu verkürzen, indem Sie die automatische Erkennung von hooks, skills, plugins, MCP-Servern, automatischem Speicher und CLAUDE.md überspringen. Ohne diese Option lädt claude -p den gleichen Kontext, den eine interaktive Sitzung hätte, einschließlich alles, was im Arbeitsverzeichnis oder in ~/.claude konfiguriert ist.

Der Bare-Modus ist nützlich für CI und Skripte, bei denen Sie auf jedem Computer das gleiche Ergebnis benötigen. Ein hook in der ~/.claude eines Teamkollegen oder ein MCP-Server in der .mcp.json des Projekts werden nicht ausgeführt, da der Bare-Modus diese nie liest. Nur Flags, die Sie explizit übergeben, haben Auswirkungen.

Dieses Beispiel führt eine einmalige Zusammenfassungsaufgabe im Bare-Modus aus und genehmigt das Read-Tool vorab, damit der Aufruf ohne Berechtigungsaufforderung abgeschlossen wird:

claude --bare -p "Summarize this file" --allowedTools "Read"

Im Bare-Modus hat Claude Zugriff auf die Bash-, Dateilesungs- und Dateibearbeitungstools. Übergeben Sie jeden Kontext, den Sie benötigen, mit einem Flag:

Der Bare-Modus überspringt OAuth und Keychain-Lesevorgänge. Die Anthropic-Authentifizierung muss von ANTHROPIC_API_KEY oder einem apiKeyHelper in der an --settings übergebenen JSON stammen. Bedrock, Vertex und Foundry verwenden ihre üblichen Anmeldedaten des Anbieters.

Hintergrundaufgaben beim Beenden

Wenn Claude während einer claude -p-Ausführung eine Hintergrund-Bash-Aufgabe startet, beispielsweise einen Entwicklungsserver oder einen Watch-Build, wird diese Aufgabe etwa fünf Sekunden nach der Rückgabe des endgültigen Ergebnisses durch Claude und dem Schließen von stdin beendet. Die Kulanzfrist ermöglicht es einer Aufgabe, die direkt nach dem Ergebnis endet, ihre Ausgabe noch zu liefern. Vor v2.1.163 würde ein nie endender Hintergrundprozess die claude -p-Invokation auf unbestimmte Zeit offen halten.

Beispiele

Diese Beispiele zeigen häufige CLI-Muster. Für CI und andere skriptgesteuerte Aufrufe fügen Sie --bare hinzu, damit sie nicht abhängig von lokalen Konfigurationen sind.

Daten durch Claude leiten

Der nicht-interaktive Modus liest stdin, sodass Sie Daten wie bei jedem anderen Befehlszeilentool einleiten und die Antwort umleiten können.

Dieses Beispiel leitet ein Build-Protokoll in Claude ein und schreibt die Erklärung in eine Datei:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Mit --output-format json enthält die Antwort-Payload total_cost_usd und eine Kostenaufschlüsselung pro Modell, sodass skriptgesteuerte Aufrufer die Ausgaben pro Aufruf verfolgen können, ohne das Nutzungs-Dashboard zu konsultieren.

Claude zu einem Build-Skript hinzufügen

Sie können einen nicht-interaktiven Aufruf in einem Skript einbinden, um Claude als projektspezifischen Linter oder Reviewer zu verwenden.

Dieses package.json-Skript leitet den Diff gegen main in Claude ein und fordert ihn auf, Tippfehler zu melden. Das Einleiten des Diff bedeutet, dass Claude keine Bash-Berechtigung zum Lesen benötigt, und die maskierten doppelten Anführungszeichen halten das Skript portabel zu Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Strukturierte Ausgabe abrufen

Verwenden Sie --output-format, um zu steuern, wie Antworten zurückgegeben werden:

• text (Standard): einfache Textausgabe
• json: strukturiertes JSON mit Ergebnis, Sitzungs-ID und Metadaten
• stream-json: zeilengetrennte JSON für Echtzeit-Streaming

Dieses Beispiel gibt eine Projektzusammenfassung als JSON mit Sitzungsmetadaten zurück, wobei sich das Textergebnis im Feld result befindet:

claude -p "Summarize this project" --output-format json

Um eine Ausgabe zu erhalten, die einem bestimmten Schema entspricht, verwenden Sie --output-format json mit --json-schema und einer JSON Schema-Definition. Die Antwort enthält Metadaten über die Anfrage (Sitzungs-ID, Nutzung usw.) mit der strukturierten Ausgabe im Feld structured_output.

Dieses Beispiel extrahiert Funktionsnamen und gibt sie als Array von Zeichenketten zurück:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Antworten streamen

Verwenden Sie --output-format stream-json mit --verbose und --include-partial-messages, um Token zu empfangen, während sie generiert werden. Jede Zeile ist ein JSON-Objekt, das ein Ereignis darstellt:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

Das folgende Beispiel verwendet jq, um nach Text-Deltas zu filtern und nur den Streaming-Text anzuzeigen. Das Flag -r gibt Rohzeichenketten aus (keine Anführungszeichen) und -j verbindet ohne Zeilenumbrüche, sodass Token kontinuierlich gestreamt werden:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Wenn eine API-Anfrage mit einem wiederholbaren Fehler fehlschlägt, gibt Claude Code ein system/api_retry-Ereignis vor dem erneuten Versuch aus. Sie können dies verwenden, um Wiederholungsfortschritt anzuzeigen oder benutzerdefinierte Backoff-Logik zu implementieren.

Das system/init-Ereignis meldet Sitzungsmetadaten einschließlich des Modells, Tools, MCP-Server und geladener Plugins. Es ist das erste Ereignis im Stream, es sei denn, CLAUDE_CODE_SYNC_PLUGIN_INSTALL ist gesetzt. In diesem Fall gehen plugin_install-Ereignisse voraus. Verwenden Sie die Plugin-Felder, um CI fehlschlagen zu lassen, wenn ein Plugin nicht geladen wurde:

Wenn CLAUDE_CODE_SYNC_PLUGIN_INSTALL gesetzt ist, gibt Claude Code system/plugin_install-Ereignisse aus, während Marketplace-Plugins vor dem ersten Zug installiert werden. Verwenden Sie diese, um Installationsfortschritt in Ihrer eigenen Benutzeroberfläche anzuzeigen.

Für programmgesteuertes Streaming mit Rückrufen und Nachrichtenobjekten siehe Antworten in Echtzeit streamen in der Agent SDK-Dokumentation.

Tools automatisch genehmigen

Verwenden Sie --allowedTools, um Claude die Verwendung bestimmter Tools ohne Aufforderung zu ermöglichen. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei Claude Bash-Befehle ausführen und Dateien lesen/bearbeiten kann, ohne um Genehmigung zu fragen:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Um einen Baseline für die gesamte Sitzung festzulegen, anstatt einzelne Tools aufzulisten, übergeben Sie einen Berechtigungsmodus. dontAsk verweigert alles, das nicht in Ihren permissions.allow-Regeln oder dem schreibgeschützten Befehlssatz enthalten ist, was für gesperrte CI-Läufe nützlich ist. acceptEdits ermöglicht Claude, Dateien ohne Aufforderung zu schreiben, und genehmigt auch automatisch häufige Dateisystembefehle wie mkdir, touch, mv und cp. Andere Shell-Befehle und Netzwerkanfragen benötigen immer noch einen --allowedTools-Eintrag oder eine permissions.allow-Regel, andernfalls wird der Lauf abgebrochen, wenn einer versucht wird:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Einen Commit erstellen

Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer angemessenen Nachricht:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Das Flag --allowedTools verwendet Berechtigungsregelsyntax. Das nachfolgende * ermöglicht Präfix-Matching, sodass Bash(git diff *) jeden Befehl erlaubt, der mit git diff beginnt. Das Leerzeichen vor * ist wichtig: ohne es würde Bash(git diff*) auch git diff-index entsprechen.

System-Eingabeaufforderung anpassen

Verwenden Sie --append-system-prompt, um Anweisungen hinzuzufügen und dabei das Standardverhalten von Claude Code beizubehalten. Dieses Beispiel leitet einen PR-Diff an Claude weiter und weist ihn an, auf Sicherheitslücken zu überprüfen:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Siehe System-Eingabeaufforderungs-Flags für weitere Optionen, einschließlich --system-prompt, um die Standardeingabeaufforderung vollständig zu ersetzen.

Gespräche fortsetzen

Verwenden Sie --continue, um das neueste Gespräch fortzusetzen, oder --resume mit einer Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folgeeingabeaufforderungen:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Wenn Sie mehrere Gespräche führen, erfassen Sie die Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Führen Sie beide Befehle aus demselben Verzeichnis aus: Die Sitzungs-ID-Suche ist auf das aktuelle Projektverzeichnis und seine Git-Worktrees beschränkt. Siehe Eine Sitzung fortsetzen für die vollständigen Bereichsregeln.

Nächste Schritte

• Agent SDK Schnellstart: Erstellen Sie Ihren ersten Agent mit Python oder TypeScript
• CLI-Referenz: alle CLI-Flags und Optionen
• GitHub Actions: Verwenden Sie das Agent SDK in GitHub-Workflows
• GitLab CI/CD: Verwenden Sie das Agent SDK in GitLab-Pipelines