Ausgabeformate: json / text / stream-json

Verwenden Sie bei claude -p --output-format, um die Claude Code-Ausgabe in Skripten und CI zu verarbeiten — strukturiertes json-Parsing, Echtzeit-stream-json-Ereignisströme, Standard-Klartext, mit jq- und Pipe-Rezepten

In Skripten, CI/CD und Automatisierungspipelines benötigen Sie mehr als eine für Menschen lesbare Antwort — Sie benötigen strukturierte Daten, die ein Programm parsen kann. Der Headless-Modus von Claude Code (claude -p) bietet über --output-format drei Ausgabeformate, mit denen Sie Claude Code wie jedes andere CLI-Tool in eine Pipeline einbinden können.

Dies ist eine Claude Code-Funktionalität und ist unabhängig vom Upstream: Ob Claude Code auf die offizielle API oder auf QCode zeigt, --output-format funktioniert gleich. Diese Seite konzentriert sich auf die Ausgabeformate; die vollständige Referenz der Headless-Flags und CI-Vorlagen finden Sie unter Automation & CI/CD.

1. Die drei Formate auf einen Blick¶

# text is the default, so these two lines are equivalent
claude -p "Explain idempotence in one sentence"
claude -p "Explain idempotence in one sentence" --output-format text

2. text: der Standard-Klartext¶

Ohne --output-format erhalten Sie text: stdout ist schlicht die finale Antwort des Modells — gut zum direkten Lesen oder für eine einfache Pipe.

# Read directly
claude -p "Rewrite this function to be async"

# Pipe to another tool
claude -p "Generate 5 candidate commit messages" | head -5

# Write to a file
claude -p "Write a short README intro for this repo" > intro.txt

Einschränkung: text liefert Ihnen nur die „Antwort“ — keine Kosten, Token-Nutzung oder Sitzungs-ID-Metadaten, und mehrstufige Aufgaben sind nicht vom Endergebnis zu unterscheiden. Wenn Sie das benötigen, wechseln Sie zu json oder stream-json.

3. json: ein einzelnes strukturiertes Objekt¶

--output-format json gibt nach Abschluss der Aufgabe ein JSON-Objekt aus, das das Endergebnis plus eine Reihe von Metadatenfeldern enthält. Dies ist das Format, das Skripte am häufigsten verwenden.

claude -p "Count how many TODO comments are under src/" --output-format json

Übliche Felder im zurückgegebenen Objekt (die tatsächlichen Felder hängen von der Ausgabe Ihrer Version ab):

Parsen mit jq¶

Das json-Format ist wie gemacht für jq:

# Just the final answer
claude -p "Summarize this change in one sentence" --output-format json | jq -r '.result'

# Pull out the cost of this call
claude -p "Review auth.py" --output-format json | jq '.total_cost_usd'

# Grab several fields at once
claude -p "Analyze the architecture" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'

Verzweigen und Kosten in einem Skript akkumulieren¶

#!/usr/bin/env bash
set -euo pipefail

out=$(claude -p "Write unit tests for UserService" \
        --output-format json --max-turns 8)

result=$(echo "$out" | jq -r '.result')
cost=$(echo "$out"   | jq -r '.total_cost_usd')
sid=$(echo "$out"    | jq -r '.session_id')

echo "Result: $result"
echo "Cost this call: \$$cost"
echo "Session ID: $sid (resume with claude --resume $sid)"

Tipp: json gibt das gesamte Objekt erst nach Abschluss der Aufgabe auf einmal aus — während eines langen Laufs gibt es keine Ausgabe. Um den Fortschritt live zu verfolgen, verwenden Sie das folgende stream-json.

4. stream-json: ein Echtzeit-Ereignisstream¶

--output-format stream-json zerlegt die Ausführung in durch Zeilenumbrüche getrennte JSON-Ereignisse (NDJSON), eines pro Zeile, sofort ausgegeben. Es eignet sich für Live-Fortschritt bei langen Aufgaben, Streaming-UIs oder Pipelines, die Ausgaben verarbeiten, während sie erzeugt werden.

claude -p "Refactor the whole utils directory and add tests" \
  --output-format stream-json --max-turns 20

Die Ausgabe sieht ungefähr so aus (jede Zeile ist unabhängiges JSON; Felder hängen von Ihrer Version ab):

{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}

Zeile für Zeile verarbeiten¶

Jede Zeile ist gültiges JSON, sodass Sie sie während des Streamings verarbeiten können:

# Print the type of each event in real time
claude -p "Migrate to the new API" --output-format stream-json \
  | jq -r '.type'

# Pull result and cost only when the final event appears
claude -p "Migrate to the new API" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nCost $\(.total_cost_usd)"'

# Process line by line with a while loop for live progress feedback
claude -p "Repository-wide code review" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ Starting…" ;;
    assistant) echo "… thinking" ;;
    result) echo "✓ Done: $(echo "$line" | jq -r '.result')" ;;
  esac
done

json vs. stream-json: json wartet, bis die Aufgabe abgeschlossen ist, und liefert ein vollständiges Objekt – einfach zu parsen; stream-json streamt mehrere Ereignisse über die gesamte Laufzeit, ermöglicht Live-Feedback, erfordert aber zeilenweises Parsen. In CI nutzen Sie json für das Endergebnis und stream-json für Fortschritts-Logs.

5. CI- / Pipeline-Rezepte¶

Ergebnis abrufen und Kommentar in GitHub Actions posten¶

- name: Claude review
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "Review this PR's diff and list issues" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "This review cost \$$(echo "$out" | jq -r '.total_cost_usd')"

Kosten-Gate hinzufügen (Fehler, wenn Budget überschritten)¶

out=$(claude -p "Generate release notes" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# Float comparison with awk: fail CI if over $0.50
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "Cost \$$cost over budget"; exit 1; }
echo "$out" | jq -r '.result'

Kosten über mehrere Aufrufe hinweg summieren¶

total=0
for f in src/*.py; do
  out=$(claude -p "Write docstrings for $f" --output-format json)
  c=$(echo "$out" | jq -r '.total_cost_usd')
  total=$(awk -v t="$total" -v c="$c" 'BEGIN{ printf "%.4f", t + c }')
done
echo "Total cost across all files: \$$total"

QCode-Anbindung: Die obigen Befehle sind für die offizielle API und QCode identisch – richten Sie ANTHROPIC_BASE_URL einfach auf https://api.qcode.cc/api (Hinweis: kein abschließender Schrägstrich) und setzen Sie Ihren cr_-Key in ANTHROPIC_AUTH_TOKEN. Nutzer in China können asia.qcode.cc verwenden. Siehe Endpunkte & API-Formate.

6. Häufige Stolperfallen¶

• json schweigt bei langen Aufgaben: Es gibt einmal am Ende aus – kein sichtbarer Fortschritt ist normal; nutzen Sie stream-json für Fortschrittsanzeige.
• stream-json lässt sich nicht als ein einzelner JSON-Block mit jq verarbeiten: Es handelt sich um NDJSON; mehrere Objekte bilden kein einzelnes JSON-Dokument. Verwenden Sie zeilenweises jq, jq -c oder --stream – führen Sie kein jq '.' auf dem gesamten Stream aus.
• --max-turns nicht vergessen: Begrenzen Sie die Runden in der Automatisierung, damit eine Aufgabe nicht durchläuft und Kosten verursacht.
• Kein abschließender Schrägstrich bei BASE_URL: https://api.qcode.cc/api ist korrekt; ein zusätzliches / erzeugt einen falschen Pfad.
• Metadaten-Felder variieren je nach Version: Vertrauen Sie der tatsächlichen Ausgabe von claude -p ... --output-format json auf Ihrem System – führen Sie zuerst jq 'keys' aus, um zu sehen, welche Felder vorhanden sind.

Nächste Schritte¶

• Automatisierung & CI/CD – vollständige Referenz der Headless-Flags und CI/CD-Rezepte
• Subagents – Claude Code Hintergrund-Agents parallel orchestrieren lassen
• Kostenoptimierung – Kosten mit total_cost_usd steuern
• Endpunkte & API-Formate – die drei Domains und Protokollpfade

Sobald Claude Code in Ihre Pipeline integriert ist, stehen die Kosten direkt in der Ausgabe – sehen Sie sich QCode-Tarife & Preise an und wählen Sie eine Stufe, die zu Ihrem Automatisierungsvolumen passt.