Claude Code JSON 出力

claude -p の --output-format で json / stream-json / text を使い分ける方法と jq の実例（2026年）。

API キーが必要ですか？ 登録する →·エンドポイントと Base URL →

最終確認：2026-10-20 · 📄 公式ドキュメント準拠（Claude Code の CLI リファレンスとヘッドレスドキュメントを 2026-10-20 に確認）

claude -p --output-format json はタスク終了後に JSON オブジェクトを 1 つ返し、--output-format stream-json は実行中に改行区切りの JSON イベントを返します。フラグを省略した場合は text が既定です。

スクリプトや CI/CD、自動化パイプラインで必要なのは「人間が読める」回答だけではなく、プログラムが解析できる構造化データです。Claude Code のヘッドレスモード（claude -p）は --output-format で 3 種類の出力フォーマットを提供し、Claude Code を通常の CLI ツールのようにパイプラインへ組み込めます。

これは Claude Code 自身の機能で、接続先のサービスには依存しません。Claude Code が公式 API を指していても QCode を指していても、--output-format は同じように動きます。本ページは出力フォーマットに焦点を当てます。ヘッドレスの全引数や CI テンプレートは 自動化と CI/CD を参照してください。

一、3 つのフォーマット早見¶

# 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

返るオブジェクトの代表的なフィールド（実際のフィールドは利用中のバージョンの出力に従ってください）：

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-schema で構造化出力を得る¶

--output-format json に --json-schema と JSON Schema の定義を組み合わせると、構造化された結果は structured_output フィールドに入り、セッション ID や使用量などのメタデータもあわせて返ります。次の例は関数名を文字列の配列として抽出し、jq で構造化部分だけを残します：

claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

| jq '.structured_output' を外すと、メタデータを含む応答全体が出力されます。値が有効な JSON Schema でない場合、claude は Error: --json-schema is not a valid JSON Schema に続けてバリデータの診断を出して終了します。

ヒント：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

トークン単位のイベントとサブエージェント¶

• --include-partial-messages：--output-format stream-json --verbose と組み合わせると、生成されるそばからトークンを受け取れます。各行はイベントを表す JSON オブジェクトです。
• --include-hook-events：hook のライフサイクルイベントを出力ストリームに含めます（--output-format stream-json が必要です）。
• --forward-subagent-text：ネストしたサブエージェントのテキストを stream-json の出力ストリームへ転送します（--print と --output-format stream-json が必要、Claude Code v2.1.211 以降）。
• --input-format stream-json：プロンプトをテキストではなく JSON のストリームとして print モードに渡します。

json vs stream-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 フォーマット — 3 つのドメインとプロトコルパス

Claude Code をパイプラインに組み込めば、コストは出力にそのまま表示されます —— QCode のプランと料金を見る で、あなたの自動化ボリュームに合うプランを選びましょう。

企業版 →