MENU
  1. ホーム
  2. Claude Code
  3. Claude Code -p フラグの使い方 – スクリプトから呼ぶJSON出力と再開

Claude Code -p フラグの使い方 – スクリプトから呼ぶJSON出力と再開

Claude Code
Claude Code -p フラグの使い方 - スクリプトから呼ぶJSON出力と再開 | mohablog

Anthropic 公式ドキュメントの “Run Claude Code programmatically” に、-p フラグで Claude Code をスクリプトから呼び出す方法が並びます。検索すると日本語記事の多くは「ヘッドレスモード」と表記しますが、ページ冒頭の Note には “The CLI was previously called ‘headless mode.’ The -p flag and all CLI options work the same way.” とあり、現行ドキュメントの正式呼称ではありません。CI や cron に組み込むときに実際に使うフラグと出力形式をまとめます。

目次

claude -p の正体 – 旧 headless モードの今

-p は --print の省略形で、対話 UI を起動せず stdout に結果を返すモードです。Claude Code v2.1.128 のリリースで、パイプ経由の stdin に 10MB の上限が入りました。スクリプト用途で公式に固められた挙動と読めます。

-p で何が変わるか

対話モードで動いていた挙動が次のように変わります。

  • ターミナル UI を立ち上げず、stdout に結果を返す
  • ツール承認のプロンプトが出ない（事前にフラグで許可リストを渡す前提）
  • --max-turns が効く（CLI reference に “print mode only” と明記）

公式ドキュメントの呼称変更

公式ページのタイトルは “Run Claude Code programmatically”。”headless mode” は本文の Note に旧称として一度だけ登場します。Google で「Claude Code ヘッドレス」を検索すると古い記事が混ざるので、原典を引く場合は code.claude.com/docs/en/headless を直接見るのが確実です。

–print と省略形 -p

claude --print "このリポジトリの README を 1 行で要約"
# 上と同等
claude -p "このリポジトリの README を 1 行で要約"

実行結果:

TypeScript で書かれた小さな HTTP クライアント。retry と timeout を内蔵。

出力フォーマットを切り替える

claude -p "プロジェクトを 1 行で説明" --output-format json | jq -r '.result'

実行結果:

TypeScript の HTTP クライアントです。retry/timeout を持つ。

このように --output-format の値で出力構造が決まります。公式ドキュメントの “Get structured output” セクションに 3 値が並んでいます。

text / json / stream-json の違い

値用途含まれる主なフィールド
text人間が読む結果テキストのみ
json1 回の応答とメタ情報result, session_id, total_cost_usd, per-model cost breakdown
stream-json逐次処理type ごとに改行区切りの JSON（system/init, assistant, result など）

--json-schema を併用すると、応答に structured_output フィールドが追加され、指定スキーマに準拠したデータが入ります。

–output-format json で結果を jq に渡す

session_id とコストを後続の処理で使うパターンです。

result=$(claude -p "src/api ディレクトリの公開関数を列挙" --output-format json)
echo "$result" | jq -r '.session_id'
echo "$result" | jq -r '.total_cost_usd'

実行結果:

7c91e1f2-b3d4-4a85-9c1d-0e2f4a6b8c11
0.00742

stream-json でリアルタイムに受け取る

公式 “Examples” の長いコマンドそのまま。delta テキストだけを取り出して進捗表示に使えます。

claude -p "短い俳句を 1 句" --output-format stream-json --verbose \
  --include-partial-messages \
  | jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

実行結果（標準出力に文字単位で流れる）:

古池や 蛙飛び込む 水の音

セッションを継続する仕組み

1 ターンで完結しない作業を -p で進めるには、前回の会話履歴を引き継ぐ仕組みが要ります。Claude Code には --continue / --resume / --session-id / --fork-session の 4 つが用意されています。

–continue で直近会話を引き継ぐ

CLI reference の説明は “Load the most recent conversation in the current directory.”。同じディレクトリで最後に動かしたセッションを引き継げます。

claude -p "TODO コメントを抽出して、ファイルとパスを列挙"
claude --continue -p "その中から優先度が高そうな 3 件を選び、理由を 1 行ずつ"

実行結果:

1. src/auth/jwt.ts L42: 署名アルゴリズム alg=none を弾くチェックが未実装
2. src/api/order.ts L88: 在庫減算がトランザクション外で走っている
3. db/migrations/0042.sql L15: NOT NULL 追加にデフォルトが無く本番投入で失敗する

–resume で session ID を指定する

JSON 出力から session_id を取り出して次のコマンドに渡す。並行で複数会話を走らせるときに使います。

session_id=$(claude -p "src/api 配下のレビュー開始" --output-format json | jq -r '.session_id')
echo "session: $session_id"
claude -p "先ほどの観点で db/ 配下も見てください" --resume "$session_id"

実行結果:

session: 4d8a1b2c-9e3f-4a87-b1cd-23e4f5a6b7c8
db/migrations/0042.sql に追加された NOT NULL 列に default が無い。
backfill ステップを別マイグレーションに分けるべき。

–session-id と –fork-session

--session-id は UUID v4 を自分で発行して固定値で管理する用途。--fork-session は resume 時に新しい session ID を発行し、履歴を分岐させます。複数のレビュー方針を同時に試したいときに使えます。

ツール承認をスクリプト向けに固める

無設定で -p を投げると、Bash や Edit が必要な指示でツール承認待ちが起きます。CI ではプロンプトが返らないので失敗するか、ターン消化のまま結果が空になる場合があります。

# アンチパターン: 何も指定せず -p に投げる
claude -p "テストを走らせて落ちたら直して"

# OK: 必要なツールを明示
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

実行結果（OK 側）:

PASS  src/utils.test.ts (3 tests)
PASS  src/api/order.test.ts (5 tests)
Fixed: src/api/order.ts L88 - 在庫減算を transaction 内に移動
Tests: 8 passed, 0 failed

–allowedTools で実行ツールを限定

CLI reference の説明は “Tools that execute without prompting for permission.”。値はカンマ区切りで Bash, Read, Edit, Write, Glob, Grep などを並べます。さらに Bash(git diff *) のように特定パターンに絞れます。

–permission-mode の値

ドキュメント記載の値は default / acceptEdits / plan / auto / dontAsk / bypassPermissions。CI で全許可したい場合は bypassPermissions、ただし --allowedTools で範囲を絞るほうが事故を減らせます。

–max-turns でループを止める

説明文は “Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default”。コスト爆発の保険として常に付けています。値の目安は単発タスク 5、マルチステップ修正 15 程度。

–bare で起動を軽くする

公式ドキュメントの “Start faster with bare mode” セクションに、--bare でスキップされる読み込み対象が並んでいます。

切れる対象意味
hooksSessionStart などの開始/終了フックを実行しない
skillsSKILL.md の trigger を評価しない
pluginsmarketplace.json 経由のプラグインを読まない
MCP serversMCP サーバーを起動しない
auto memoryプロジェクト memory の自動読込を行わない
CLAUDE.md自動検出を切る（必要なら --system-prompt-from-file で個別指定）

Note には “This will be the default behavior in claude -p in a future release.” とあり、近い将来 -p のデフォルトに --bare 相当の挙動が入ります。先に --bare を明示しておけば、デフォルト切替で hooks や auto memory が突然読み込まれなくなる差分でハマらずに済みます。

実例 – CI とスクリプトに組み込む

公式 “Examples” 節をベースに、自分のリポジトリに入れている組み込み方の代表例を載せます。どれも --bare + --allowedTools + --max-turns をセットで付けるのが定番です。

差分から typo を指摘する linter

package.json の scripts に書く形。プルリク前のセルフチェックに回しています。

{
  "scripts": {
    "lint:claude": "git diff main | claude -p --bare --max-turns 3 \"レビューして typo のみ報告。修正コードは出力しない。typo がなければ何も出さない。\""
  }
}

実行結果:

$ npm run lint:claude
src/utils.ts L24: "responce" → "response"
src/api/auth.ts L88: "recieve" → "receive"

git diff main の変更量が 200 行を超えると --max-turns 3 では途中で打ち切られることが増えました。そのときは 5 まで上げる運用に切り替えています。

自動コミットを作るスクリプト

ステージ済み変更からコミットメッセージだけ生成して投げる例。Examples の “Create a commit” の形そのまま。

claude -p --bare --max-turns 5 \
  "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

実行結果:

[main 4b1c2d8] refactor(api): GraphQL resolver の引数バリデーションを共通関数へ
 3 files changed, 42 insertions(+), 27 deletions(-)

Bash(git commit *) のようにサブコマンド単位で許可することで、想定外のシェル操作を弾けます。

パイプで build error を解析する

CI ログの最終 200 行を流し込んで根本原因だけを返してもらう構成。

tail -n 200 build-error.txt | claude -p --bare --max-turns 1 \
  "concisely explain the root cause of this build error" \
  --output-format json | jq -r '.result' > root-cause.txt

実行結果:

$ cat root-cause.txt
root cause: tsconfig.json の paths に @api/* を登録しているが、
baseUrl が未設定のため tsc が node_modules を解決できていない。
baseUrl: "." を追加すれば通る。

v2.1.128 の 10MB 上限を踏まえ、巨大なビルドログをそのまま流すのは避けて tail -n や grep -A で絞ってから渡すのが要件です。

まとめ

  • -p は --print の省略形で、ヘッドレスモードは旧称
  • --output-format json の応答には result, session_id, total_cost_usd が含まれる
  • 会話の継続は --continue / --resume / --session-id / --fork-session の 4 つ
  • スクリプト用途では --allowedTools と --max-turns を必ず付ける
  • --bare は将来 -p のデフォルト挙動になる

公式ドキュメント “Run Claude Code programmatically” を一次情報として参照してください。CLI reference の “CLI flags” 表に全フラグが並びます。

Claude Code
AI開発 Claude Code 自動化
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次