はじめに / 対象と前提
Claude Code を対話用途だけでなく、シェルスクリプトや CI パイプラインから叩きたいことがある。PR の自動レビューや定型作業のバッチ処理など、人間が画面の前にいない状況で動かすケースだ。
-
対象読者: Claude Code を対話的に使ったことはあるが
-p(headless)は未経験の人 - 前提環境: Claude Code v2.x、Node.js 22.x、macOS/Linux
-
やりたいこと:
claude -pをスクリプトから呼び、JSON をパースして後続処理に渡す
TL;DR
-
claude -p "<prompt>" --output-format jsonで非対話実行でき、stdout に構造化 JSON が1つ返る - 確認プロンプトは
--permission-mode/--allowedToolsを明示しないと 非TTY 環境ではハングする - セッションを跨いだ文脈維持には
--resume <session_id>が必要。保存を忘れると毎回文脈が切れる
手順 / 動かし方
1. 最小の headless 実行
claude -p "このディレクトリのファイル数を数えて教えて" --output-format json
stdout に以下のような JSON が1つ返る(簡略化)。
{
"type": "result",
"session_id": "8f2c1a90-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"result": "このディレクトリには 42 個のファイルがあります。",
"is_error": false,
"total_cost_usd": 0.0031
}
jq で本文だけ取り出せる。
RESULT=$(claude -p "..." --output-format json | jq -r '.result')
2. ツール実行を許可して自動化する
デフォルトでは Bash や Write などに確認プロンプトが出る。headless では誰も押せないので明示的に許可する。
claude -p "package.json の version を patch 上げて" \
--output-format json \
--allowedTools "Read,Edit" \
--permission-mode acceptEdits
--allowedTools で使えるツールを絞り、--permission-mode acceptEdits で編集系の確認を自動承認する。CI では「何ができるか」を絞ったほうが事故が少ない。
3. セッションを継続する
1回の -p はその場限りの会話で終わる。複数ステップに跨る処理は session_id を保存し --resume で渡す。
RES1=$(claude -p "src/ 配下の未使用 export を探して" --output-format json)
SESSION_ID=$(echo "$RES1" | jq -r '.session_id')
echo "$SESSION_ID" > /tmp/claude_session.txt
claude -p "さっき見つけたやつを1つ削除して" \
--output-format json \
--resume "$(cat /tmp/claude_session.txt)"
ハマりどころ
① 非TTY環境でプロンプト待ちのままハングする
--permission-mode を指定せずに Write / Bash 等の確認が要る操作を指示すると、対話モードなら出るはずの確認プロンプトが 非TTY環境(cron・CI・launchd 経由)では表示できず、プロセスが応答なしで止まる。
回避策: headless前提のスクリプトは必ず --allowedTools と --permission-mode を明示する。「対話で動いたから CI でもそのまま動くはず」という思い込みが一番多いハマりパターンだった。
② JSON パース時に stderr のログが混ざる
--output-format json は stdout に JSON だけを出す設計だが、2>&1 でリダイレクトを合成してから jq に渡すと、途中に混ざった警告ログで JSON パースが壊れる。
# NG
claude -p "..." --output-format json 2>&1 | jq '.result'
# → jq: parse error: Invalid literal at line 1, column 0
回避策: stdout と stderr を分離し、ログは別ファイルへ逃がす。
claude -p "..." --output-format json 2>/tmp/claude_stderr.log | jq -r '.result'
③ --resume の session_id を保存し忘れて文脈が切れる
--resume は「直前の会話」ではなく明示的に渡した session_id の会話を復元する。1回目の結果に含まれる session_id を保存し忘れると、2回目以降は毎回新規セッションとして起動される。
厄介なのは エラーにならず、ただ黙って文脈がリセットされる点。ログに session_id を必ず出力し、実行のたびに前回との差分がないか確認するのが安全策。
まとめ
-
claude -p ... --output-format jsonで Claude Code を非対話実行でき、CI やバッチ処理に組み込める - 非TTY環境では確認プロンプトがハングの原因になるため
--allowedTools/--permission-modeは必須 - JSON パースは stdout と stderr を分離してから行う
- 会話を跨ぐ処理は
session_idの保存を忘れずに