# Ausgabeformate: json / text / stream-json

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](/docs/advanced/headless).

---

## 1. Die drei Formate auf einen Blick

| Format | Flag | Ausgabeform | Einsatzzweck |
|------|------|---------|---------|
| Klartext | `--output-format text` (Standard) | Ein einzelner Block Klartext | Lesen durch Menschen, einfache Pipes |
| JSON | `--output-format json` | **Ein** strukturiertes JSON-Objekt | Skript-Parsing, Auslesen von Kosten/Nutzung/Sitzungs-ID |
| Streaming JSON | `--output-format stream-json` | Ein **durch Zeilenumbrüche getrennter** JSON-Ereignisstrom | Live-Fortschritt, schrittweises Verarbeiten, lange Aufgaben |

```bash
# 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.

```bash
# 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.

```bash
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):

| Feld | Bedeutung |
|------|------|
| `result` | Der finale Antworttext |
| `total_cost_usd` | Kosten dieses Aufrufs (USD) |
| `usage` | Token-Nutzung (Input / Output / Cache usw.) |
| `session_id` | Sitzungs-ID, mit `--resume` zur Fortsetzung verwendbar |

### Parsen mit jq

Das `json`-Format ist wie gemacht für [`jq`](https://jqlang.org/):

```bash
# 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

```bash
#!/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.

```bash
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:

```bash
# 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)"'
```

```bash
# 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

```yaml
- 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)

```bash
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

```bash
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](/docs/getting-started/endpoints-and-api-paths).

---

## 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](/docs/advanced/headless) – vollständige Referenz der Headless-Flags und CI/CD-Rezepte
- [Subagents](/docs/advanced/subagents) – Claude Code Hintergrund-Agents parallel orchestrieren lassen
- [Kostenoptimierung](/docs/usage/cost-optimization) – Kosten mit `total_cost_usd` steuern
- [Endpunkte & API-Formate](/docs/getting-started/endpoints-and-api-paths) – 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](https://qcode.cc/pricing) an und wählen Sie eine Stufe, die zu Ihrem Automatisierungsvolumen passt.