Headless-Modus und Agent SDK

Claude automatisch in Skripten und CI/CD-Pipelines laufen lassen

⏱ ca. ~6 Min

01 · Lesen

Alles, was du bisher mit Claude Code gemacht hast, war interaktiv — du tippst, Claude antwortet, du genehmigst. Aber was, wenn Claude automatisch laufen soll? In einer CI/CD-Pipeline, die jeden Pull Request reviewt? In einem nächtlichen Skript, das Lint-Fehler fixt?

Headless-Modus (claude -p) lässt Claude ohne interaktives Terminal laufen. Du gibst ihm einen Prompt, er erledigt die Arbeit, gibt das Ergebnis zurück. Kein Tippen, keine Genehmigungs-Dialoge — nur Input und Output.

So binden Teams Claude in automatisierte Abläufe ein: Code-Review-Bots, Test-Fixer, Doku-Generatoren und vieles mehr.

💡 Stell dir das so vorInteraktives Claude ist wie ein Gespräch am Schreibtisch deiner Kollegin. Headless-Claude ist, als würdest du ihr Aufgaben per E-Mail schicken — du schickst die Anfrage, sie erledigt sie, du bekommst das Ergebnis zurück. Kein Hin und Her.

Kernpunkte

claude -p lässt Claude nicht-interaktiv laufen (Headless-Modus)
Ideal für Skripte, CI/CD-Pipelines, Automatisierung
Keine Genehmigungs-Dialoge — gib erlaubte Tools vorab an
Output kann Text, JSON oder Streaming-JSON sein

02 · Code-Beispiel

Hier sind gängige Headless-Modus-Muster. Das -p-Flag macht es nicht-interaktiv.

Headless-Grundnutzung

# Simple query
claude -p "Find all TODO comments in this project"

# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
  --allowedTools "Bash(npm test*),Read,Edit"

# Structured JSON output
claude -p "List all API endpoints" \
  --output-format json

Das -p-Flag (kurz für „print") lässt Claude nicht-interaktiv laufen. --allowedTools gibt bestimmte Tools vorab frei, damit Claude ohne Permission-Abfragen arbeiten kann. --output-format json liefert strukturierte Daten statt reinem Text — nützlich, wenn ein anderes Programm das Ergebnis parsen soll.

03 · Code-Beispiel

Hier ist, wie Teams den Headless-Modus in CI/CD-Pipelines nutzen — ein automatischer Code-Reviewer, der bei jedem Pull Request läuft.

GitHub Actions — automatisches Code-Review

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review PR
        run: |
          claude -p "Review the changes in this PR. \
            Focus on bugs, security, and performance." \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

Dieser GitHub Action lässt Claude im Headless-Modus bei jedem Pull Request laufen. Er erlaubt nur Read-only-Tools (Read, Grep, Glob), sodass Claude Code analysieren, aber nichts ändern kann. Der Review-Output erscheint im CI-Log und kann vom Team gelesen werden.

04 · Lesen

Für komplexere Automatisierung bietet Anthropic das Agent SDK — Bibliotheken in Python und TypeScript mit voller Claude-Tool-Unterstützung, um produktionsreife Agents zu bauen.

Das Agent SDK gibt dir programmatische Kontrolle über alles: welche Tools verfügbar sind, wie Ergebnisse verarbeitet werden, Session-Management (Unterhaltungen fortsetzen), sogar MCP-Server-Verbindungen. Es trägt die anspruchsvollsten Claude-Code-Integrationen.

Das CLI (claude -p) eignet sich für einfache Automatisierung. Das Agent SDK nimmst du, wenn du volle programmatische Kontrolle brauchst — eigene Fehlerbehandlung, Streaming-Ergebnisse, mehrere Claude-Aufrufe verketten oder ein Produkt auf Claudes Fähigkeiten aufbauen.

Kernpunkte

Agent SDK: Python- und TypeScript-Bibliotheken für produktionsreife Agents
Volle programmatische Kontrolle über Tools, Sessions, Ergebnisse
CLI (claude -p): einfache Automatisierung und Skripte
Agent SDK: komplexe Anwendungen und Produktionssysteme
Session-Management: Unterhaltungen programmatisch erfassen und fortsetzen

05 · Code-Beispiel

Hier ist ein einfaches Agent-SDK-Beispiel in TypeScript, das einen Bug programmatisch findet und fixt.

Agent SDK — Bug-Fixer

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const msg of query({
  prompt: "Find and fix the failing test in auth.test.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
  }
})) {
  if (msg.result) {
    console.log('Fix applied:', msg.result);
  }
}

Das Agent SDK gibt dir ein Streaming-Interface — du iterierst über Nachrichten, während Claude arbeitet. Das allowedTools-Array steuert, was Claude darf. Wenn Claude fertig ist, enthält die Result-Nachricht eine Zusammenfassung dessen, was getan wurde. So baust du automatisierte Agents, die lesen, editieren und Befehle ausführen können.

06 · Quiz

Welches Flag lässt Claude Code nicht-interaktiv laufen, ohne interaktives Terminal?

claude --headless
claude --auto
claude -p
claude --batch

07 · Ausfüllen

Um Claude in einer CI/CD-Pipeline ohne Nutzerinteraktion laufen zu lassen, nutze claude _____ "dein Prompt".

08 · Zuordnen

Ordne jede Automatisierungsmethode dem besten Einsatz zu.

(Diese Sektion ist interaktiv — aktiviere JavaScript, um sie zu nutzen.)

Andere Lektionen aus diesem Kapitel

⚠ Das volle interaktive Erlebnis braucht JavaScript. Bitte aktiviere es und lade die Seite neu.

※ Diese Seite ist ein unabhängiges Bildungsprojekt — kein offizielles Anthropic-Produkt. Claude™ ist eine eingetragene Marke von Anthropic, PBC.