SpyBara
Go Premium

headless.md 2026-10-05 23:58 UTC to 2026-10-06 16:59 UTC

This page contains 60 additions and 59 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sun 4 23:58 Tue 6 16:59

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, die Sie benötigen:

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. Nicht jede CLI-Option kombiniert mit -p. Claude Code lehnt --bg ab und lehnt --cloud mit einer Aufgabenbeschreibung mit einem Fehler ab, der den Konflikt benennt; --cloud mit einer Sitzungs-ID und -p reiht stattdessen eine Nachricht in diese Cloud-Sitzung ein und beendet sich. Optionen, die Sie häufig mit -p kombinieren, sind:

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

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

Claude Code beendet sich mit Code 0 bei Erfolg und mit einem Code ungleich Null, wenn die Ausführung fehlschlägt, sodass Ihre Skripte basierend auf dem Exit-Status verzweigen können. Wenn Sie ein ungültiges Flag übergeben, meldet Claude Code den Fehler an stderr, bevor die Ausführung beginnt. Wenn ein Fehler während der Ausführung auftritt, z. B. fehlende Authentifizierung, gibt Claude Code den Fehler als Ergebnis auf stdout aus.

Schneller starten mit Bare-Modus

Fügen Sie --bare hinzu, um die Startzeit zu verkürzen, indem Sie die automatische Erkennung von Hooks, Skills, benutzerdefinierten Befehlen, Subagenten, installierten Plugins, MCP-Servern, automatischem Memory und CLAUDE.md überspringen. Ohne diese Option lädt claude -p denselben Kontext wie eine interaktive Sitzung, einschließlich aller im Arbeitsverzeichnis oder in ~/.claude konfigurierten Inhalte.

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 wird nicht ausgeführt, da der Bare-Modus diese nie liest. Ein Verzeichnis, das Sie mit --add-dir benennen, ist eine teilweise Ausnahme: Der Bare-Modus lädt Skills aus seinem .claude/skills/-Ordner, überspringt aber immer noch seine .claude/commands/- und .claude/agents/-Ordner. Skills aus zusätzlichen Verzeichnissen behandelt, was geladen wird und was nicht.

Ohne --bare führt eine -p-Sitzung die Hooks in der .claude/settings.json eines Projekts aus und verbindet die Server in seiner .mcp.json, auch in einem Ordner, dem Sie nie vertraut haben. Eine -p-Sitzung zeigt keinen Workspace-Trust-Dialog und keine Pro-Server-Genehmigungsaufforderung an. Was vor dem Vertrauen in einen Ordner ausgeführt wird behandelt jede Art von Repository-Inhalt unter -p und wie Sie ihn fernhalten.

Dieses Beispiel führt eine einmalige Zusammenfassungsaufgabe im Bare-Modus aus und genehmigt das Read-Tool im Voraus, sodass der Aufruf ohne Genehmigungsaufforderung abgeschlossen wird. Setzen Sie ANTHROPIC_API_KEY vor der Ausführung, da der Bare-Modus Ihren Abonnement-Login nicht verwendet:

claude --bare -p "Summarize README.md" --allowedTools "Read"

Im Bare-Modus liest Claude Code niemals OAuth-Anmeldedaten oder den System-Schlüsselbund. Für die Anthropic API setzen Sie ANTHROPIC_API_KEY in der Umgebung mit einem Schlüssel, der in der Claude Console erstellt wurde, oder geben Sie einen apiKeyHelper in der --settings-JSON an. Amazon Bedrock, Google Clouds Agent Platform und Microsoft Foundry lesen weiterhin ihre eigenen Provider-Anmeldedaten wie gewohnt.

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

Zum Laden Verwenden Sie
Systemanforderungen hinzufügen --append-system-prompt, --append-system-prompt-file
Einstellungen --settings <file-or-json>
MCP-Server --mcp-config <file-or-json>
Benutzerdefinierte Agenten --agents <file-or-json>
Ein Plugin --plugin-dir <path>, --plugin-url <url>

Der Bare-Modus schränkt außerdem ein, was während der Sitzung geschieht:

  • MCP-Server: Es werden nur Server verbunden, die über die Befehlszeile übergeben werden, z. B. mit --mcp-config. In einer interaktiven Sitzung überspringt Claude Code außerdem die automatische IDE-Verbindung, sofern Sie nicht --ide übergeben.
  • System-Erinnerungen: Claude erhält Ihre Prompts und die Tool-Ergebnisse ohne die System-Erinnerungen, die Claude Code ihnen sonst beifügen würde. Beispielsweise wird Claude nicht darüber informiert, wenn sich eine zuvor gelesene Datei auf der Festplatte ändert, und erhält nicht die Liste der verfügbaren Skills, einschließlich Skills aus einem --add-dir-Ordner.
  • Hintergrundaufgaben: Es werden keine ausgeführt. Ein Befehl, der sein Timeout erreicht, wird gestoppt, statt in den Hintergrund verschoben zu werden.

Vor v2.1.286 galten diese Einschränkungen nur teilweise: Eine interaktive --bare-Sitzung verband die MCP-Server, die auch eine normale Sitzung verbinden würde, jede --bare-Sitzung sendete System-Erinnerungen, und Hintergrundaufgaben blieben verfügbar.

Hintergrundaufgaben beim Beenden

Wenn Claude während einer claude -p-Ausführung eine Hintergrund-Bash-Aufgabe startet, z. B. einen Dev-Server oder einen Watch-Build, wird diese Shell etwa fünf Sekunden nach der Rückgabe des Endergebnisses durch Claude und dem Schließen von stdin beendet. Die Kulanzfrist ermöglicht es einer Aufgabe, die kurz nach dem Ergebnis endet, ihre Ausgabe noch zu liefern.

Wenn Claude einen Hintergrund-Subagenten oder Workflow startet, bleibt claude -p stattdessen offen, bis diese Arbeit abgeschlossen ist, da ihr Ergebnis Teil der endgültigen Ausgabe ist.

Standardmäßig endet das Warten nach 10 Minuten kontinuierlichen Wartens im Leerlauf, sodass ein feststeckender Subagent oder Workflow den Prozess nicht unbegrenzt offen halten kann. An diesem Punkt stoppt Claude Code alles, was noch läuft, und verwirft sein Teilergebnis. Um das Limit zu ändern, setzen Sie CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, oder setzen Sie es auf 0, um ohne Limit zu warten.

Wenn Claude während einer claude -p-Ausführung eine Monitor-Watch startet, wartet Claude Code auf die Watch, bis sie abläuft oder die Zehn-Minuten-Obergrenze das Warten beendet, je nachdem, was zuerst eintritt. Während es wartet, antwortet Claude weiterhin auf das, was die Watch meldet. Standardmäßig läuft eine Watch fünf Minuten nach dem Start durch Claude ab.

Beenden Sie eine Ausführung mit SIGTERM

Wenn Sie eine claude -p-Ausführung mit SIGTERM beenden, z. B. mit kill oder von einem Prozessüberwacher, beendet sich Claude Code mit Code 143. Claude Code lässt den laufenden Turn unvollständig und zeichnet kein Ergebnis dafür auf. Um den Turn stattdessen zu beenden, senden Sie SIGINT oder rufen Sie die interrupt()-Methode des Agent SDK auf, bevor Sie den Prozess stoppen.

Bei SIGTERM beendet Claude Code die Prozessstruktur aller noch laufenden Bash-Befehle. Claude Code führt dann SessionEnd-Hooks aus und beendet sich. Beim Beenden startet Claude Code keinen neuen Tool-Aufruf, sendet keine neue Modellanfrage und führt keinen Hook außer SessionEnd aus. Wenn die Ausführung in der Mitte eines Befehls oder beim Warten auf eine Antwort auf eine Genehmigungsaufforderung war, als das Signal ankam, behandelt Claude Code diesen Schritt wie folgt:

  • Ausführung eines Befehls: Claude Code zeichnet den Befehl als beendet in der Sitzung auf.
  • Warten auf eine Antwort auf eine Genehmigungsaufforderung: Wenn Sie SIGTERM an den Prozess senden, lässt Claude Code die Aufforderung unbeantwortet. Wenn Ihr Programm die Sitzung über das Agent SDK schließt, beendet das SDK Claude Codes Eingabe vor dem Senden eines Signals, und Claude Code bricht die Aufforderung auf, sobald die Eingabe endet.

Wenn Sie die Sitzung fortsetzen, lässt Claude Code den unterbrochenen Turn unverändert, und Ihre nächste Eingabe treibt das Gespräch voran. Um Claude Code stattdessen den unterbrochenen Turn beim Fortsetzen fortzusetzen, setzen Sie CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Wenn das Arbeitsverzeichnis gelöscht wird

Wenn das Arbeitsverzeichnis einer claude -p- oder Agent SDK-Sitzung während der Sitzung gelöscht wird, läuft die Sitzung weiter. Wenn ein Turn beginnt, während das Verzeichnis fehlt, gibt Claude Code eine Warnmeldung in der stream-json-Ausgabe aus, und Shell-Befehle schlagen fehl, bis das Verzeichnis wieder vorhanden ist.

Beispiele

Diese Beispiele zeigen häufige CLI-Muster. Wenn ein Befehl eine Datei wie auth.py oder build-error.txt benennt, ersetzen Sie diese durch eine Datei aus Ihrem eigenen Projekt. Fügen Sie in CI oder anderen skriptgesteuerten Umgebungen --bare hinzu, damit Claude Code startet, ohne die Hooks, Plugins, das Auto-Memory oder die CLAUDE.md des Hosts zu laden.

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-Log 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 verfolgen können, ohne das Nutzungs-Dashboard zu konsultieren. Wenn Sie eine frühere Konversation mit --continue oder --resume fortsetzen, meldet der Lauf die Gesamtsumme der Konversation, einschließlich der Ausgaben früherer Läufe. Beide Zahlen sind clientseitige Schätzungen und können sich von Ihrer tatsächlichen Rechnung unterscheiden.

Wenn Claude Code stdin nicht lesen kann, beispielsweise weil der Prozess, der es gestartet hat, sein Ende getrennt hat, gibt Claude Code eine Warnung auf stderr aus und fährt mit dem Prompt aus der Befehlszeile fort. Vor v2.1.211 führte ein nicht lesbares stdin unter Windows zum Absturz der Sitzung oder zum stillen Beenden ohne Ausgabe.

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 Claude auf, Tippfehler zu melden. Durch das Einleiten des Diffs benötigt Claude keine Bash-Berechtigung zum Lesen, und die maskierten doppelten Anführungszeichen halten das Skript unter Windows portabel:

{
  "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.\""
  }
}

Führen Sie es mit npm run lint:claude aus.

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: zeilengetrenntes 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"]}'

Wenn der Wert kein gültiges JSON Schema ist, beendet sich claude mit Error: --json-schema is not a valid JSON Schema gefolgt von der Diagnose des Validators. Claude Code akzeptiert Schemas, die das Schlüsselwort format verwenden, wie "format": "email", behandelt format aber als Anmerkung und erzwingt es nicht. Vor v2.1.205 ignorierte Claude Code ein ungültiges Schema stillschweigend und gab unstrukturierten Text zurück, und behandelte jedes Schema, das format enthielt, als ungültig.

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

Die letzte Zeile des Streams ist eine result-Nachricht mit dem endgültigen Antworttext, den Kosten und den Sitzungsmetadaten.

Wenn Ihr Consumer den Stream langsam liest, wartet Claude Code vor dem Beenden darauf, dass die in der Warteschlange befindliche Ausgabe abfließt, und skaliert die Wartezeit mit der Menge, die sich noch in der Warteschlange befindet, begrenzt auf 30 Sekunden. Vor v2.1.214 war die Wartezeit beim Beenden auf etwa zwei Sekunden begrenzt, was das Ende einer großen Antwort abschneiden konnte.

Das folgende Beispiel verwendet jq zum Filtern nach Text-Deltas und zum Anzeigen nur des Streaming-Texts. 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'

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

Subagenten-Nachrichten folgen

Nachrichten von Subagenten erscheinen im Stream als assistant- und user-Nachrichten, deren Feld parent_tool_use_id die ID des Tool-Aufrufs ist, der den Subagenten gestartet hat. Nachrichten aus der Hauptkonversation tragen null in diesem Feld.

Die erste Nachricht eines Subagenten, der im Vordergrund läuft, ist eine user-Nachricht mit dem Prompt, der ihn steuert. Nach dieser ersten Nachricht gibt Claude Code Folgendes aus:

  • Standardmäßig: die tool_use- und tool_result-Blöcke des Subagenten.
  • Mit --forward-subagent-text oder CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: auch die Text- und Thinking-Blöcke des Subagenten, damit Sie das Transkript jedes Subagenten rekonstruieren können. Dies erfordert Claude Code v2.1.211 oder später.

Wenn Sie eine der beiden Optionen aktivieren, leitet Claude Code Nachrichten von Subagenten auf jeder Verschachtelungstiefe weiter, unabhängig davon, ob jeder mit dem Agent-Tool oder als geforkter Skill gestartet wurde. Nachrichten von Subagenten, die ein geforkter Skill startet, und von geforkten Skills, die in einem Subagenten oder einem anderen geforkten Skill gestartet werden, erfordern Claude Code v2.1.275 oder später. In parent_tool_use_id tragen die Nachrichten des verschachtelten Subagenten die ID des Agent- oder Skill-Tool-Aufrufs, der ihn gestartet hat, sodass Sie den vollständigen Verschachtelungsbaum rekonstruieren können, indem Sie diesen IDs folgen. Vor v2.1.219 erschienen Nachrichten von verschachtelten Subagenten nicht im Stream.

Skills, die in einem Subagenten laufen, erscheinen im Stream auf die gleiche Weise: Die erste Nachricht des geforkten Skills ist eine user-Nachricht mit dem Skill-Inhalt, der den Lauf steuert. Wenn Sie eine der beiden Optionen aktivieren, enthält der Stream auch die Text- und Thinking-Blöcke des geforkten Skills. Vor v2.1.265 erschienen nur die tool_use- und tool_result-Blöcke eines geforkten Skills im Stream.

API-Wiederholungsversuche verarbeiten

Wenn eine API-Anfrage mit einem Fehler fehlschlägt, bei dem ein erneuter Versuch möglich ist, gibt Claude Code vor dem erneuten Versuch ein system/api_retry-Ereignis aus. Wenn bei v2.1.246 oder später ein 401 oder 403 über apiKeyHelper bereitgestellte Anmeldedaten ablehnt, führt Claude Code die ersten beiden Wiederholungsversuche stillschweigend ohne Ereignis durch und gibt das Ereignis dann ab dem dritten aufeinanderfolgenden Wiederholungsversuch wie gewohnt aus. Die stillen Wiederholungsversuche zählen trotzdem zu attempt. Sie können das Ereignis verwenden, um den Fortschritt der Wiederholungsversuche in Ihrer eigenen Benutzeroberfläche anzuzeigen.

Feld Typ Beschreibung
type "system" Nachrichtentyp
subtype "api_retry" kennzeichnet dies als Wiederholungsereignis
attempt Ganzzahl aktuelle Versuchsnummer, beginnend bei 1
max_retries Ganzzahl insgesamt zulässige Wiederholungsversuche für die Ursache dieses Fehlers, die weniger als das sitzungsweite Budget sein können
retry_delay_ms Ganzzahl Millisekunden bis zum nächsten Versuch
error_status Ganzzahl oder null HTTP-Statuscode des fehlgeschlagenen Versuchs oder null, wenn der Versuch keine HTTP-Antwort von der API erhielt
no_response Objekt, optional nur vorhanden, wenn der fehlgeschlagene Versuch nicht rechtzeitig Response-Header erhielt. waited_ms gibt an, wie lange dieser Versuch gewartet hat, und retry_wait_ms, wie lange der Wiederholungsversuch warten wird. In diesen Ereignissen spiegelt max_retries den einen Wiederholungsversuch wider, den diese Ursache normalerweise erhält, nicht das sitzungsweite Budget. Erfordert Claude Code v2.1.261 oder später
error Zeichenkette Fehlerkategorie: authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens, cloud_credential_error oder unknown
uuid Zeichenkette eindeutige Ereigniskennung
session_id Zeichenkette Sitzung, zu der das Ereignis gehört

Sitzungsmetadaten lesen

Das system/init-Ereignis meldet Sitzungsmetadaten einschließlich des Modells, der Tools, der MCP-Server und der geladenen Plugins. Es ist das erste Ereignis im Stream, es sei denn, Startereignisse gehen ihm voraus:

Das Ereignis enthält außerdem ein optionales Array capabilities von Zeichenketten, das die Protokollverhalten benennt, die diese Claude Code-Version implementiert, wie interrupt_receipt_v1 oder interrupt_cancel_queued_v1. Prüfen Sie es, um Funktionen zu erkennen, anstatt Versionszeichenketten zu vergleichen, und ignorieren Sie Werte, die Sie nicht kennen. Das Feld erfordert Claude Code v2.1.205 oder später und fehlt in früheren Versionen. Siehe SDKSystemMessage für die Liste der Fähigkeiten.

CI fehlschlagen lassen, wenn ein Plugin oder MCP-Server nicht geladen wird

Verwenden Sie die Plugin-Felder im system/init-Ereignis, um ein Plugin zu erkennen, das nicht geladen wurde:

Feld Typ Beschreibung
plugins Array Plugins, die erfolgreich geladen wurden, jeweils mit name und path
plugin_errors Array Plugin-Ladefehler, jeweils mit plugin, type und message. Umfasst nicht erfüllte Abhängigkeitsversionen und --plugin-dir-Ladefehler wie einen fehlenden Pfad oder ein ungültiges Archiv. Ein Plugin, das nicht geladen wurde, fehlt in plugins. Der Schlüssel wird weggelassen, wenn es keine Fehler gibt

Wenn ein --plugin-dir-Verzeichnis oder -Archiv selbst nicht geladen werden kann, enthält sein plugin_errors-Eintrag den aufgelösten absoluten Pfad als path. Verwenden Sie ihn, um zu erkennen, welcher von mehreren --plugin-dir-Werten fehlgeschlagen ist. Das Feld path erfordert Claude Code v2.1.283 oder später.

Verwenden Sie die MCP-Server-Felder auf die gleiche Weise. Wenn Sie --mcp-config mit -p übergeben, wartet Claude Code auf noch ausstehende Server, bevor der erste Turn ausgeführt wird, höchstens bis zum Start-Timeout MCP_TIMEOUT, standardmäßig 30 Sekunden. Ein Remote-Server mit einer zwischengespeicherten Tool-Liste überspringt das Warten, zeigt pending in system/init an und verbindet sich beim ersten Tool-Aufruf. Das Warten erfordert Claude Code v2.1.221 oder später.

Claude Code validiert jeden --mcp-config-Eintrag beim Start und überspringt Einträge, die die Validierung nicht bestehen, beispielsweise einen url-Eintrag ohne type. Der Lauf wird fortgesetzt und beendet sich sauber, prüfen Sie also diese Felder, um einen Server zu erkennen, der nie geladen wurde:

Feld Typ Beschreibung
mcp_servers Array MCP-Server in der Sitzung, jeweils mit name und status
mcp_server_errors Array --mcp-config-Einträge, die durch die Konfigurationsvalidierung übersprungen wurden, jeweils mit name, type und message. type ist eine Überspringungskategorie wie unknown_type, url_missing_type, invalid_config oder reserved_name; behandeln Sie Werte, die Sie nicht kennen, als generisches Überspringen. Betroffene Server fehlen in mcp_servers. Der Schlüssel wird weggelassen, wenn es keine Fehler gibt, sodass ein CI-Gate bei einem nicht leeren Array fehlschlagen kann. Erfordert Claude Code v2.1.219 oder später

Wenn Sie den Befehl von Hand in einem Terminal ausführen, gibt Claude Code außerdem eine Startwarnung auf stderr aus, wie Warning: 1 MCP server skipped due to invalid config:, gefolgt vom Grund für jeden übersprungenen Eintrag. Wenn Sie stderr umleiten oder wenn ein Programm wie ein CI-Runner oder ein SDK-Host es erfasst, gibt Claude Code keine Warnung aus und meldet die übersprungenen Einträge nur im Feld mcp_server_errors. Die Warnung erfordert Claude Code v2.1.219 oder später.

Plugin-Installationen verfolgen

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

Feld Typ Beschreibung
type "system" Nachrichtentyp
subtype "plugin_install" kennzeichnet 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

Tools automatisch genehmigen

Verwenden Sie --allowedTools, damit Claude bestimmte Tools ohne Nachfrage verwenden kann. Wenn Sie Read und Edit auflisten, kann Claude Dateien lesen und bearbeiten, ohne um Erlaubnis zu fragen. Das Auflisten von Bash bewirkt dasselbe für Shell-Befehle, außer in einem Lauf, der im Auto-Modus startet: Dort verwirft Claude Code einen bloßen Bash-Eintrag als zu breite allow-Regel, und der Auto-Modus bewertet stattdessen jeden Befehl. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei diese drei Tools aufgelistet sind:

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

Um eine Baseline für die gesamte Sitzung festzulegen, anstatt einzelne Tools aufzulisten, übergeben Sie einen Berechtigungsmodus. Ein Lauf, bei dem nichts einen Berechtigungsmodus setzt, verwendet den integrierten Start-Berechtigungsmodus, der auto sein kann. Übergeben Sie also den gewünschten Modus:

  • auto: Übergeben Sie --permission-mode auto, damit ein Klassifikator anstelle von Ihnen die meisten Aktionen überprüft
  • dontAsk: Claude Code verweigert jeden Aufruf, bei dem sonst nachgefragt würde, was für abgeschottete CI-Läufe nützlich ist. Aktionen, die im Manual-Modus keine Genehmigung benötigen, werden weiterhin ausgeführt, etwa Dateilesevorgänge in Ihren Arbeitsverzeichnissen und die nur lesenden Befehle, ebenso Aktionen, die Ihre --allowedTools-Einträge oder permissions.allow-Regeln abdecken. AskUserQuestion, Konnektor-Tools, die Ihre Organisation auf ask gesetzt hat, und MCP-Tools, die mit requiresUserInteraction gekennzeichnet sind, werden verweigert, auch wenn eine allow-Regel passt
  • acceptEdits: Claude schreibt Dateien ohne Nachfrage, und Claude Code genehmigt automatisch häufige Dateisystembefehle wie mkdir, touch, mv und cp. Die Aktionen, die kein Modus automatisch genehmigt, gelten weiterhin. Abgesehen von den nur lesenden Befehlen benötigen andere Shell-Befehle und Netzwerkanfragen weiterhin einen --allowedTools-Eintrag oder eine permissions.allow-Regel. Siehe was acceptEdits automatisch genehmigt für die vollständige Liste

Dieses Beispiel wendet Lint-Korrekturen mit acceptEdits als Baseline an:

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

Berechtigungsabfragen in unbeaufsichtigten Läufen ausschalten

Übergeben Sie --permission-prompts none, wenn niemand verfügbar ist, um Berechtigungsabfragen zu beantworten, beispielsweise in einem geplanten Job. Das Flag ist vor allem dann relevant, wenn Ihr Lauf einen Berechtigungshost hat: eine Agent SDK-App mit einem canUseTool-Callback oder ein MCP-Tool, das Sie mit --permission-prompt-tool übergeben. Ohne das Flag wartet Ihr Lauf darauf, dass dieser Host jede Berechtigungsanfrage beantwortet.

Mit dem Flag konsultiert Ihr Lauf den Host nicht und wartet nicht auf ihn. Alles, wofür nachgefragt würde, wird verweigert, es sei denn, ein PermissionRequest-Hook erlaubt es. Claude wird mitgeteilt, dass niemand die Anfrage genehmigen kann und dass Claude sie nicht erneut versuchen soll, und der Lauf wird fortgesetzt. In einem -p-Lauf ohne Host werden diese Anfragen ohnehin verweigert, und das Flag teilt Claude zusätzlich mit, sie nicht erneut zu versuchen. Berechtigungsregeln, PermissionRequest-Hooks und der von Ihnen festgelegte Berechtigungsmodus entscheiden weiterhin zuerst über jeden Aufruf; Claude Code verweigert nur die Anfragen, die durch nichts anderes aufgelöst werden.

Dieses Beispiel führt eine unbeaufsichtigte Aufgabe im Auto-Modus aus. Der Klassifikator überprüft jede Aktion wie gewohnt, und Claude Code verweigert alles, was auf eine Berechtigungsabfrage zurückgefallen wäre:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Mit --permission-prompts none entfernt Claude Code die Tools, die eine Antwort von einer Person benötigen, wie AskUserQuestion, sodass Claude sie nicht aufrufen kann. Jede MCP-Elicitation-Anfrage, die kein Elicitation-Hook beantwortet, wird abgebrochen.

Mit --output-format stream-json erscheinen Ablehnungen als permission_denied-Systemnachrichten, und die abschließende Ergebnisnachricht listet sie in permission_denials auf.

Einen Commit erstellen

Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer passenden 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 die Syntax für Berechtigungsregeln. Das nachgestellte * 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 auf git diff-index passen.

System-Prompt 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 Claude an, ihn auf Sicherheitslücken zu überprüfen. Speichern Sie es als Shell-Skript, zum Beispiel review.sh:

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

Im Skript steht "$1" für das erste Argument, das Sie in der Befehlszeile übergeben. Führen Sie bash review.sh 123 aus, und die Shell ersetzt "$1" durch 123, sodass das Skript den Diff für PR 123 abruft. Claude Code gibt die Überprüfung als JSON aus, wobei sich der Text im Feld result befindet.

Siehe System-Prompt-Flags für weitere Optionen, einschließlich --system-prompt, um den Standard-Prompt vollständig zu ersetzen.

Konversationen fortsetzen

Verwenden Sie --continue, um die neueste Konversation fortzusetzen, oder --resume mit einer Sitzungs-ID, um eine bestimmte Konversation fortzusetzen. Wenn Sie bei Claude Code v2.1.257 oder später --continue übergeben, öffnet Claude Code eine Hintergrundsitzung, die beendet ist, aber keine, die noch läuft. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folge-Prompts:

# 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 Konversationen führen, erfassen Sie die Sitzungs-ID, um eine bestimmte fortzusetzen:

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

Sie können die beiden Befehle aus verschiedenen Verzeichnissen ausführen: Claude Code findet die Sitzung anhand ihrer ID in jedem Projekt auf diesem Computer. Vor v2.1.223 suchte Claude Code die ID nur im aktuellen Projektverzeichnis und seinen Git-Worktrees, sodass Sie beide Befehle aus demselben Verzeichnis ausführen mussten.

Anstelle der Sitzungs-ID können Sie --resume den absoluten Pfad zur .jsonl-Transkriptdatei einer Sitzung übergeben, und Claude Code setzt die in dieser Datei gespeicherte Konversation fort.

Nächste Schritte