0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code の headless モード(-p / --output-format json)でCI/CDに組み込む実装手順 — セッション再開と権限まわりの3つのハマりどころ【2026】

0
Posted at

はじめに / 対象と前提

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 の保存を忘れずに
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?