出力フォーマット:json / text / stream-json
claude -p の --output-format でスクリプトや CI 上の Claude Code 出力を扱う — 構造化 json の解析、リアルタイムな stream-json イベントストリーム、デフォルトのプレーンテキスト、jq とパイプの実例つき
出力フォーマット:json / text / stream-json¶
スクリプトや CI/CD、自動化パイプラインで必要なのは「人間が読める」回答だけではなく、プログラムが解析できる構造化データです。Claude Code のヘッドレスモード(claude -p)は --output-format で 3 種類の出力フォーマットを提供し、Claude Code を通常の CLI ツールのようにパイプラインへ組み込めます。
これは Claude Code 自身の機能で、アップストリームには依存しません。Claude Code が公式 API を指していても QCode を指していても、
--output-formatは同じように動きます。本ページは出力フォーマットに焦点を当てます。ヘッドレスの全引数や CI テンプレートは 自動化と CI/CD を参照してください。
一、3 つのフォーマット早見¶
| フォーマット | 引数 | 出力の形 | 用途 |
|---|---|---|---|
| プレーンテキスト | --output-format text(デフォルト) |
1 つのプレーンテキストの回答 | 人間が読む、簡単なパイプ |
| JSON | --output-format json |
1 つの構造化 JSON オブジェクト | スクリプト解析、コスト/使用量/セッション ID の取得 |
| ストリーミング JSON | --output-format stream-json |
改行区切りの JSON イベントストリーム | リアルタイム進捗、逐次消費、長時間タスク |
# text がデフォルトなので、次の 2 行は等価
claude -p "冪等性を一文で説明して"
claude -p "冪等性を一文で説明して" --output-format text
二、text:デフォルトのプレーンテキスト¶
--output-format を付けないと text になり、標準出力はモデルの最終回答そのものです。そのまま読んだり、簡単なパイプに流したりするのに向いています。
# そのまま読む
claude -p "この関数を async 形式に書き換えて"
# 他のツールへパイプ
claude -p "コミットメッセージ候補を 5 つ生成して" | head -5
# ファイルへ書き出す
claude -p "このリポジトリの README 概要を書いて" > intro.txt
制限:text は「回答」しか返さず、コスト・トークン使用量・セッション ID などのメタデータは取れません。多段タスクでも途中経過と最終結果を区別できません。これらが必要なら json か stream-json に切り替えます。
三、json:1 つの構造化オブジェクト¶
--output-format json はタスク完了後に1 つの JSON オブジェクトを出力し、最終結果と一連のメタデータフィールドを含みます。スクリプトで最もよく使うフォーマットです。
claude -p "src/ 配下の TODO コメント数を数えて" --output-format json
返るオブジェクトの代表的なフィールド(実際のフィールドは利用中のバージョンの出力に従ってください):
| フィールド | 意味 |
|---|---|
result |
最終回答のテキスト |
total_cost_usd |
この呼び出しのコスト(USD) |
usage |
トークン使用量(入力 / 出力 / キャッシュなど) |
session_id |
セッション ID。--resume で継続に使える |
jq で解析する¶
json フォーマットは jq と相性抜群です:
# 最終回答だけ取り出す
claude -p "今回の変更を一文でまとめて" --output-format json | jq -r '.result'
# この呼び出しのコストを取り出す
claude -p "auth.py をレビューして" --output-format json | jq '.total_cost_usd'
# 複数フィールドをまとめて取得
claude -p "アーキテクチャを分析して" --output-format json \
| jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'
スクリプトで分岐&コスト集計¶
#!/usr/bin/env bash
set -euo pipefail
out=$(claude -p "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"
echo "今回のコスト:\$$cost"
echo "セッション ID:$sid(claude --resume $sid で継続)"
ヒント:
jsonはタスク終了後にオブジェクトを一括で吐き出すため、長時間タスクの間は何も出力されません。進捗をリアルタイムで見たい場合は下記のstream-jsonを使います。
四、stream-json:リアルタイムのイベントストリーム¶
--output-format stream-json は実行過程を改行区切りの JSON イベント(NDJSON)に分解し、1 行 1 イベントで即座に書き出します。長時間タスクのリアルタイム進捗、ストリーミング UI、出力を生成しながら消費するパイプラインに向いています。
claude -p "utils ディレクトリ全体をリファクタしてテストを追加して" \
--output-format stream-json --max-turns 20
出力は次のような形です(各行は独立した JSON。フィールドは実際のバージョンに従う):
{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}
1 行ずつ消費する¶
各行は正しい JSON なので、ストリームしながら処理できます:
# 各イベントのタイプをリアルタイムで表示
claude -p "新しい API へ移行して" --output-format stream-json \
| jq -r '.type'
# 最終イベントが出たときだけ結果とコストを取り出す
claude -p "新しい API へ移行して" --output-format stream-json \
| jq -r 'select(.type == "result") | "\(.result)\nコスト $\(.total_cost_usd)"'
# while ループで 1 行ずつ処理し、進捗をリアルタイムで返す
claude -p "リポジトリ全体のコードレビュー" --output-format stream-json | \
while IFS= read -r line; do
type=$(echo "$line" | jq -r '.type')
case "$type" in
system) echo "▶ 開始…" ;;
assistant) echo "… 思考中" ;;
result) echo "✓ 完了:$(echo "$line" | jq -r '.result')" ;;
esac
done
jsonvsstream-json:jsonはタスク終了を待って1 つの完全なオブジェクトを返すため解析が簡単。stream-jsonは全体を通して複数のイベントをストリームし、リアルタイムなフィードバックができる反面、1 行ずつの解析が必要です。CI では最終結果にjson、進捗ログにstream-jsonを使います。
五、CI / パイプライン実例¶
GitHub Actions で結果を取得してコメント投稿¶
- name: Claude レビュー
env:
ANTHROPIC_BASE_URL: https://api.qcode.cc/api
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
out=$(claude -p "この PR の diff をレビューして問題点を挙げて" \
--output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
echo "$out" | jq -r '.result' > review.md
echo "今回のレビューのコスト \$$(echo "$out" | jq -r '.total_cost_usd')"
コストゲートを設ける(予算超過なら失敗)¶
out=$(claude -p "リリースノートを生成して" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# awk で浮動小数点比較:0.5 ドルを超えたら CI を失敗させる
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
|| { echo "コスト \$$cost は予算超過"; exit 1; }
echo "$out" | jq -r '.result'
複数回の呼び出しのコストを合算¶
total=0
for f in src/*.py; do
out=$(claude -p "$f に docstring を書いて" --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"
QCode を指す:上記コマンドは公式 API でも QCode でも完全に同じです。
ANTHROPIC_BASE_URLをhttps://api.qcode.cc/api(末尾にスラッシュなしに注意)に、ANTHROPIC_AUTH_TOKENにあなたのcr_キーを設定するだけ。CN ユーザーはasia.qcode.ccを使えます。詳しくは 接続先と API フォーマット を参照。
六、よくある落とし穴¶
jsonは長時間タスク中は無音:終了時に 1 回だけ出力するので、進捗が見えないのは正常。進捗が欲しければstream-jsonを。stream-jsonを一括jqできない:NDJSON なので、複数オブジェクトは単一の JSON ドキュメントになりません。行ごとのjq、jq -c、--streamを使い、ストリーム全体にjq '.'を流さないこと。--max-turnsを忘れない:自動化ではターン数を制限し、タスクの暴走と課金の暴発を防ぐ。- BASE_URL の末尾にスラッシュを付けない:
https://api.qcode.cc/apiが正しく、余分な/は誤ったパスを作ります。 - メタデータフィールドはバージョンで変わる:自分のマシンの
claude -p ... --output-format jsonの実出力を信頼し、まずjq 'keys'で何があるか確認を。
次のステップ¶
- 自動化と CI/CD — ヘッドレスモードの全引数と CI/CD 実例
- サブエージェント — Claude Code にバックグラウンドエージェントを並列編成させる
- コスト最適化 —
total_cost_usdでコストを管理する - 接続先と API フォーマット — 4 つのドメインとプロトコルパス
Claude Code をパイプラインに組み込めば、コストは出力にそのまま表示されます —— QCode のプランと料金を見る で、あなたの自動化ボリュームに合うプランを選びましょう。