Claude Code ist nicht nur ein interaktiver Begleiter im Terminal. Mit dem Headless-Modus lässt sich der Agent per Skript aufrufen, in Pipelines einbinden und mit maschinenlesbarer Ausgabe weiterverarbeiten. Über die offizielle GitHub Action reagiert er zudem auf Kommentare in Issues und Pull Requests. Damit wird aus dem persönlichen Werkzeug ein Baustein Ihrer Automatisierung. Wie Sie beides einrichten, welche Optionen wirklich zählen und wie Sie Kosten und Risiken im Griff behalten, lesen Sie hier.
Headless-Modus: Claude Code als Kommandozeilenprogramm
Mit der Option -p übergeben Sie einen Prompt direkt beim Aufruf. Claude Code arbeitet die Aufgabe ab, gibt das Ergebnis aus und beendet sich. Über die Option für das Ausgabeformat wählen Sie zwischen reinem Text, JSON mit Metadaten wie Kosten und Sitzungs-ID oder stream-json für die zeilenweise Verarbeitung. Mit einer Sitzungs-ID lässt sich ein Gespräch in einem späteren Aufruf fortsetzen.
Entscheidend für den unbeaufsichtigten Betrieb sind die Optionen für erlaubte und verbotene Tools sowie die maximale Anzahl an Durchläufen. Damit legen Sie fest, was der Agent ohne Rückfrage tun darf, und verhindern, dass eine Aufgabe ins Endlose läuft. Projekt-Settings, Hooks und CLAUDE.md gelten auch hier, sodass lokale und automatisierte Läufe denselben Regeln folgen.
Typische Einsätze sind nächtliche Aufräumarbeiten, das Erzeugen von Release Notes, Übersetzungs-Updates oder die Vorabanalyse neuer Issues. Wer mehr Kontrolle braucht, greift auf das Agent SDK zurück, das dieselben Fähigkeiten aus TypeScript oder Python bereitstellt.
GitHub Actions: der Agent im Pull Request
Die offizielle Claude Code Action von Anthropic läuft als Workflow in Ihrem Repository. Am schnellsten richten Sie sie aus Claude Code heraus mit dem Befehl /install-github-app ein, der die GitHub-App installiert und das nötige Secret anlegt. Danach reagiert der Agent, wenn jemand in einem Issue oder Pull Request @claude erwähnt, implementiert Änderungen auf einem Branch oder kommentiert Code.
Alternativ starten Sie die Action automatisch, etwa bei jedem neuen Pull Request für ein erstes Review. Wichtig ist, die Ausführung auf vertrauenswürdige Auslöser zu beschränken: Kommentare von externen Personen in öffentlichen Repositories sollten den Agenten nicht ohne Weiteres starten können.
Bewährt hat sich ein gestuftes Vorgehen: Zuerst kommentiert der Agent nur, später darf er Vorschläge als eigenen Branch anlegen, und erst wenn das Team den Ergebnissen vertraut, übernimmt er auch kleinere Umsetzungen auf Zuruf. So wächst die Autonomie mit der Erfahrung, statt am ersten Tag alles freizugeben.
Einrichtung in fünf Schritten
- Legen Sie fest, welche Aufgaben automatisiert werden sollen, und beginnen Sie mit einer einzigen, etwa dem Review neuer Pull Requests.
- Installieren Sie die GitHub-App und hinterlegen Sie den API-Schlüssel oder die Cloud-Anbindung als Repository-Secret, niemals im Workflow-Code.
- Begrenzen Sie im Workflow die erlaubten Tools, die maximale Anzahl an Durchläufen und die Laufzeit des Jobs.
- Ergänzen Sie die CLAUDE.md um Hinweise speziell für die CI, zum Beispiel welche Tests dort laufen dürfen.
- Werten Sie die ersten Ergebnisse gemeinsam aus und erweitern Sie den Einsatz erst danach.
Sicherheit und Kosten im Blick behalten
In der Pipeline hat der Agent oft Zugriff auf Secrets und Schreibrechte im Repository. Geben Sie dem Workflow nur die GitHub-Berechtigungen, die er tatsächlich braucht, und lassen Sie Merges in geschützte Branches weiterhin von Menschen freigeben. Inhalte aus Issues und Kommentaren sind nicht vertrauenswürdig und können Prompt-Injection-Versuche enthalten.
Bei den Kosten helfen enge Auslöser, ein Limit für Durchläufe und die Wahl eines passenden Modells. Die JSON-Ausgabe liefert Verbrauchsdaten, die Sie in Ihr Monitoring übernehmen können. So fällt früh auf, wenn ein Workflow ungewöhnlich viel verbraucht.
Ein weiterer Hebel ist die Frage, wie viel Kontext ein Lauf überhaupt braucht. Ein Review-Workflow, der nur den Diff und die betroffenen Dateien betrachtet, ist deutlich sparsamer als einer, der bei jedem Pull Request die gesamte Codebasis erkundet. Formulieren Sie die Aufgabe im Workflow daher so eng wie möglich und geben Sie Pfade oder Dateilisten direkt mit.
Vom Experiment zum Standard
Automatisierte Agenten-Workflows sind schnell gebaut, aber ein verlässlicher Standard braucht klare Regeln, Monitoring und ein Team, das die Ergebnisse einordnen kann. Unsere AI Code Engineers von neooutput richten Headless-Workflows und GitHub Actions mit Ihnen gemeinsam ein und schulen Ihr Team im Umgang damit, remote oder vor Ort. Sprechen Sie uns in einem kostenlosen 15-Minuten-Erstgespräch auf Ihren konkreten Anwendungsfall an.
Häufige Fragen
Brauche ich für den Headless-Modus eine andere Lizenz?
Claude Code nutzt im Headless-Modus dieselbe Anmeldung wie interaktiv. In CI-Umgebungen wird üblicherweise ein API-Schlüssel oder eine Anbindung über Amazon Bedrock oder Google Vertex AI verwendet. Prüfen Sie die Konditionen Ihres Vertrags für automatisierte Nutzung.
Kann die GitHub Action direkt in den Hauptbranch pushen?
Technisch ist das je nach Rechten möglich, wir raten aber davon ab. Lassen Sie den Agenten auf eigenen Branches arbeiten und Pull Requests erzeugen, die ein Mensch prüft und mergt.
Funktioniert das auch mit GitLab?
Ja, Claude Code lässt sich im Headless-Modus in jede CI-Umgebung einbinden, die Node.js ausführen kann. Für GitLab CI gibt es zudem eine eigene Integration, die ähnlich wie die GitHub Action funktioniert.