Deepseek ArtifactsDeepseek Artifacts
Automatisierungs-Guide

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

Ansehen

Headless mode — official documentation

Offizielle Doku: code.claude.com/docs

Ansehen

Claude Code GitHub Action — official docs

Offizielle Doku: code.claude.com/docs

Ansehen

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. 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.

    Claude Code SDK slide describing programmatic access to Claude Code in headless environments as a building block for scripts, CI tools and remote environments
    Anthropics eigene Rahmung: das SDK ist programmgesteuerter Zugriff auf Claude Code in headless Umgebungen.Ansehen bei 2:10
  2. 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.

    Claude Code headless one-shot command claude -p writing a Fibonacci function with the allowedTools flag in a terminal
    Eine Einmal-Frage: claude -p erzeugt die Fibonacci-Funktion und beendet sich — keine TUI, keine Rückfragen.Ansehen bei 3:30
  3. 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.

    Piping app log files into Claude Code headless mode with cat and claude -p to summarize the most common error logs
    cat plus Pipe-Symbol plus claude -p: aus zweitausend Logzeilen wird eine Diagnose in drei Sätzen.Ansehen bei 3:55
  4. 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.

    Claude Code headless mode explaining the output of ifconfig after piping the command result into claude -p
    ifconfig durch claude -p gepipt: jede Schnittstelle erklärt, Loopback auf Wunsch ausgenommen.Ansehen bei 4:15
  5. 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.

    Claude Code headless JSON output showing the result field, session id and total cost from the output-format json flag
    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

  1. 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.

    Claude Code SDK deep dive slide listing allowedTools permission rules, output-format stream-json and the system-prompt flag
    Der SDK-Deep-Dive: Tool-Berechtigungen, strukturierte Ausgabemodi und eigene System-Prompts auf einer Folie.Ansehen bei 11:00
  2. 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.

  3. 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.

  4. 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

  1. 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.

    Anthropic slide listing what the Claude GitHub Action does when tagged on a pull request or issue, running on existing GitHub runners
    Der Vertrag der Action: @claude taggen, beschreiben, was Sie brauchen — und sie bearbeitet das Repository auf Ihren eigenen Runnern.Ansehen bei 17:10
  2. 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.

    GitHub issue where tagging at-claude produced a scoped implementation plan comment for a per question timer feature
    Der @claude-Kommentar an einem echten Issue: Claude antwortet mit einem eingegrenzten Plan, bevor es Code anfasst.Ansehen bei 7:50
  3. 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.

    GitHub issue completed by the Claude Code action showing a checked implementation summary and the features added to the quiz app
    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.

Häufige Fragen

Weitere Claude-Code-Guides