Claude Code Headless-Modus: -p, CI & die GitHub Action
Skripten Sie Claude Code wie ein Unix-Tool: Einmal-Prompts mit claude -p, Dateien einpipen, JSON auswerten, Sitzungen per ID fortsetzen, für CI mit --bare fahren und die @claude-GitHub-Action Features aus einem Issue bauen lassen — direkt aus Anthropics eigenem Walkthrough.
Kurz zusammengefasst
- claude -p "prompt" läuft einmalig und druckt das Ergebnis — keine interaktive Sitzung. Es kombiniert sich wie jedes Unix-Tool: rein pipen, raus pipen, in Skripte und CI-Schritte ketten.
- --output-format json liefert das Ergebnis plus session_id, Kosten und Metadaten; stream-json emittiert zeilengetrennte Ereignisse für Echtzeit-Verbraucher. Mit jq parsen und darauf aufbauen.
- Headless startet ohne Änderungs- oder destruktive Berechtigungen. Geben Sie exakt das Nötige mit --allowedTools "Bash(git diff *),Edit" — Permission-Regel-Syntax, Präfix-Abgleich.
- Die @claude-GitHub-Action ist Headless-Modus mit Frontend: Taggen Sie @claude an einem Issue oder PR, liest sie Code, erstellt PRs und Commits, beantwortet Fragen und reviewt Code — auf Ihren eigenen GitHub-Runnern.
Building headless automation with Claude Code | Code w/ Claude
Kanal: Anthropic20:59
Headless mode — official documentation
Offizielle Doku: code.claude.com/docs
Claude Code GitHub Action — official docs
Offizielle Doku: code.claude.com/docs
Flags, Grenzwerte und Verhalten auf dieser Seite sind gegen die offizielle Headless-Dokumentation verifiziert; der Vortrag oben ist Anthropics eigener Walkthrough und die visuelle Quelle der Screenshots.
Screenshots werden ihren Urhebern zugeordnet, mit Deep-Links zu den exakten Zeitstempeln. Sprecher- und Publikumsaufnahmen werden nicht verwendet.
Claude Code headless ausführen, Schritt für Schritt
Teil 1 — Headless-Grundlagen
- 1
Was der Headless-Modus ist
Headless-Modus ist Claude Code ohne interaktive UI: derselbe Agent, programmgesteuert. Anthropic rahmt ihn als simplen Baustein für agentische Anwendungen — nutzen Sie ihn wie ein Unix-Tool in Skripten und Pipelines, für CI-Automatisierung, entfernte Umgebungen oder als Engine hinter einer Web-Chat-Oberfläche.

Anthropics eigene Rahmung: das SDK ist programmgesteuerter Zugriff auf Claude Code in headless Umgebungen.Ansehen bei 2:10 - 2
Einmal-Prompts mit claude -p
Das Flag -p (oder --print) führt einen einzelnen Prompt aus und beendet sich: claude -p "Write me a function that calculates the Fibonacci sequence". Nichts bleibt offen — Sie bekommen die Ausgabe auf stdout und einen Exit-Code, den Ihre Skripte prüfen können. Koppeln Sie es mit --allowedTools, um Schreibrechte vorab zu gewähren.

Eine Einmal-Frage: claude -p erzeugt die Fibonacci-Funktion und beendet sich — keine TUI, keine Rückfragen.Ansehen bei 3:30 - 3
Dateien direkt in Claude pipen
Stdin funktioniert wie bei jedem CLI-Tool: cat app.log | claude -p "summarize the most common error logs". In Anthropics Demo gehen 2000 Logzeilen hinein und eine Klartext-Fehlerzusammenfassung heraus — derselbe Trick funktioniert für Build-Fehler, Stack Traces und Exporte. Gepiptes Stdin ist auf 10 MB gedeckelt.

cat plus Pipe-Symbol plus claude -p: aus zweitausend Logzeilen wird eine Diagnose in drei Sätzen.Ansehen bei 3:55 - 4
Ausgaben entschlüsseln, die Sie ungern lesen
Dasselbe Muster macht aus feindseligen Ausgaben Antworten: ifconfig | claude -p "what interfaces do I have configured? don't include lo". Alles, was ein Befehl druckt — Netzwerkzustand, Compiler-Fehler, Terraform-Pläne — lässt sich für eine menschenlesbare Zusammenfassung durch Claude routen.

ifconfig durch claude -p gepipt: jede Schnittstelle erklärt, Loopback auf Wunsch ausgenommen.Ansehen bei 4:15 - 5
Strukturiertes JSON herausbekommen
Ergänzen Sie --output-format json, und die Antwort wird ein parsiertes Objekt: der Ergebnis-Text, die session_id, Dauer und total_cost_usd. Für Live-Verbraucher emittiert --output-format stream-json zeilengetrennte Ereignisse, wie sie passieren — die letzte Zeile ist das Endergebnis.

JSON-Modus: ein Klumpen mit dem Ergebnis, einer session_id zum späteren Fortsetzen und den Kosten des Laufs.Ansehen bei 4:35
Teil 2 — Skripten wie ein Ingenieur
- 6
Tools bewusst gewähren
Headless startet ohne Änderungs- oder destruktive Berechtigungen. --allowedTools gibt im Voraus frei, was die Aufgabe braucht — in Permission-Regel-Syntax: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". MCP-Tools lassen sich genauso auf die Allow-Liste setzen — gewähren Sie das schmalste Set, das die Aufgabe erledigt.

Der SDK-Deep-Dive: Tool-Berechtigungen, strukturierte Ausgabemodi und eigene System-Prompts auf einer Folie.Ansehen bei 11:00 - 7
Kontext über Läufe hinweg behalten
Der JSON-Modus liefert eine session_id — reichen Sie sie mit --resume "$session_id" zurück, um denselben Konversationszustand aus einem späteren Lauf oder einem anderen Prozess fortzusetzen. So bauen Sie interaktive Produkte darauf auf: Der Nutzer sagt etwas, Claude antwortet, Sie bewahren die Sitzung für den nächsten Zug auf.
- 8
Berechtigungen ohne Menschen handhaben
Wenn Sie nicht vorhersagen können, welche Tools Claude braucht, lagert --permission-prompt-tool die Freigabeentscheidungen zur Laufzeit an einen MCP-Server aus — das Tool fragt Ihren Dienst (oder Ihren Nutzer, via Ihrer App), ob jede Aktion erlaubt werden soll, statt dass Sie alles vorab auflisten.
- 9
Für CI mit --bare fahren
--bare überspringt die Auto-Entdeckung von Hooks, Skills, Custom Commands, Subagents, Plugins, MCP-Servern und CLAUDE.md für den schnellstmöglichen Start — empfohlen für Skripte und CI, und als Standard für -p angekündigt. Es verlangt ANTHROPIC_API_KEY und nimmt Kontext explizit über Flags entgegen.
Teil 3 — Die @claude-GitHub-Action
- 10
Die @claude-GitHub-Action kennenlernen
Die GitHub Action ist Headless-Modus mit einem auf dem SDK gebauten Frontend. Taggen Sie @claude an einen beliebigen PR oder Issue, dann liest sie Ihren Code, erstellt PRs, hängt Commits an bestehende an, beantwortet Fragen und reviewt Änderungen — laufend auf Ihren vorhandenen GitHub-Runnern, also keine Infrastruktur zu pflegen.

Der Vertrag der Action: @claude taggen, beschreiben, was Sie brauchen — und sie bearbeitet das Repository auf Ihren eigenen Runnern.Ansehen bei 17:10 - 11
Claude ein Issue zuweisen
In Anthropics Live-Demo antwortete ein Kommentar „@claude please implement this feature and comment on it“ mit einem eingegrenzten Plan — Stichpunkten, was gebaut würde — bevor Branch, Commits und Pull Request entstanden, alles nachvollziehbar in den Logs der Action.

Der @claude-Kommentar an einem echten Issue: Claude antwortet mit einem eingegrenzten Plan, bevor es Code anfasst.Ansehen bei 7:50 - 12
Auf Ihrem Repository installieren
Das Ergebnis ist ein abgehakter Umsetzungsplan im Issue — Features ergänzt, Todos geschlossen. Um dorthin zu gelangen, öffnen Sie Claude Code in Ihrem Repository und führen Sie /install-github-action aus: Ein interaktiver Ablauf öffnet einen PR mit dem Workflow-YAML, dann konfigurieren Sie API-Keys als Repo-Secrets und mergen.

Der fertige Lauf: eine abgehakte Umsetzungsliste mit jedem Feature, das die Action der Demo-App hinzufügte.Ansehen bei 13:30
Headless vs. interaktiv vs. SDK vs. die GitHub Action
Vier Wege, denselben Agenten zu treiben — wählen Sie danach, wer (oder was) fragt:
- 1Interaktive CLI — die TUI-Sitzung: Berechtigungs-Prompts, Plan-Modus, /commands. Am besten für Menschen, die jetzt eine Aufgabe treiben.
- 2Headless claude -p — ein programmatischer Schuss: stdin und stdout, Exit-Codes, keine UI. Am besten für Skripte, Cron-Jobs und schnelle Fragen anderer Tools.
- 3Das Agent SDK — dieselbe Headless-Kraft als typisierte Bibliothek: mehrstufige Sitzungen, eigene Tools, Streaming. Am besten, wenn Claude eine Komponente in Ihrer Anwendung ist.
- 4Die @claude-GitHub-Action — Headless auf GitHub-Ereignismodell: Issues, PRs und Reviews auf Ihren eigenen Runnern. Am besten für repo-weite Automatisierung, die das ganze Team auslösen kann.
- 5--bare headless — ein entkleideter Start für CI: keine CLAUDE.md, keine Hooks, Skills, Plugins oder MCP-Auto-Entdeckung, expliziter Kontext über Flags, schnellster Kaltstart.
Sie teilen sich denselben Modellzugriff und dieselbe Berechtigungssystematik — eine für Headless gewährte Berechtigungsregel gilt überall, deshalb zählt --allowedTools-Disziplin.
Headless macht Probleme? Erste Hilfe
Fünf headless-typische Stolperfallen und die Lösung für jede:
- 1Skript beendet sich, bevor Claude fertig ist. Prüfen Sie den Exit-Code: 0 ist Erfolg, alles andere ist ein Fehlschlag. SIGTERM endet mit 143 und lässt den Zug unvollendet — beenden Sie Läufe mit SIGINT oder dem interrupt() des SDK, wenn Sie mitten im Zug stoppen müssen.
- 2Gepipte Eingabe still gekürzt. Stdin ist auf 10 MB gedeckelt — schreiben Sie größere Nutzdaten in eine Datei und referenzieren Sie den Pfad im Prompt.
- 3„--bg rejected“ oder ein --cloud-Fehler. Nur-interaktive Flags greifen bei -p nicht: --bg wird rundheraus abgelehnt, und --cloud braucht eine session_id, um eine Nachricht einzureihen, statt einer Aufgabenbeschreibung.
- 4Der CI-Lauf ignoriert Ihre CLAUDE.md und Hooks. Das ist --bare bei der Arbeit: Es überspringt die Auto-Entdeckung. Reichen Sie Kontext explizit mit --settings, --mcp-config, --agents oder --plugin-dir nach.
- 5Hintergrund-Bash-Tasks sterben mittendrin. Hintergrund-Shells werden etwa 5 Sekunden nach Eintreffen des Ergebnisses getötet; Subagents und Workflows halten den Prozess bis zu einer Idle-Grenze von 10 Minuten am Leben. Warten Sie in CI explizit auf sie.
Für alles andere: --verbose ergänzen und die stream-json-Ereignisse lesen — system/init nennt Modell, Tools und MCP-Server, die tatsächlich geladen wurden.
