SpyBara
Go Premium

headless.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

225 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

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 programmgesteuert über die CLI 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:

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:

Zum Laden Verwenden Sie
Systemanfrage-Ergänzungen --append-system-prompt, --append-system-prompt-file
Einstellungen --settings <file-or-json>
MCP-Server --mcp-config <file-or-json>
Benutzerdefinierte Agenten --agents <json>
Ein Plugin-Verzeichnis --plugin-dir <path>

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.

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.

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.

Feld Typ Beschreibung
type "system" Nachrichtentyp
subtype "api_retry" identifiziert dies als Wiederholungsereignis
attempt Ganzzahl aktuelle Versuchsnummer, beginnend bei 1
max_retries Ganzzahl insgesamt zulässige Wiederholungen
retry_delay_ms Ganzzahl Millisekunden bis zum nächsten Versuch
error_status Ganzzahl oder null HTTP-Statuscode oder null für Verbindungsfehler ohne HTTP-Antwort
error Zeichenkette Fehlerkategorie: authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, invalid_request, server_error, max_output_tokens oder unknown
uuid Zeichenkette eindeutige Ereigniskennung
session_id Zeichenkette Sitzung, zu der das Ereignis gehört

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:

Feld Typ Beschreibung
plugins Array Plugins, die erfolgreich geladen wurden, jeweils mit name und path
plugin_errors Array Plugin-Ladefehler wie eine nicht erfüllte Abhängigkeitsversion, jeweils mit plugin, type und message. Betroffene Plugins werden herabgestuft und fehlen in plugins. Der Schlüssel wird weggelassen, wenn es keine Fehler gibt

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.

Feld Typ Beschreibung
type "system" Nachrichtentyp
subtype "plugin_install" identifiziert dies als Plugin-Installationsereignis
status "started", "installed", "failed" oder "completed" started und completed rahmen die Gesamtinstallation ein; installed und failed melden einzelne Marketplaces
name Zeichenkette, optional Marketplace-Name, vorhanden bei installed und failed
error Zeichenkette, optional Fehlermeldung, vorhanden bei failed
uuid Zeichenkette eindeutige Ereigniskennung
session_id Zeichenkette Sitzung, zu der das Ereignis gehört

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"

Nächste Schritte