Claude Code を claude -p でスクリプトから動かす方法(ヘッドレス実行)

公開: 2026年10月17日 ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

claude -p でできること

公式ドキュメントによると、claude コマンドに -p(または --print)を付けると非対話で実行できます。すべての CLI オプションが -p と組み合わせられるわけではなく、たとえば --bg はエラーで拒否されます。よく組み合わせるのは、会話を続ける --continue、ツールを自動承認する --allowedTools、構造化出力の --output-format です。

claude -p "What does the auth module do?"

成功時の終了コードは 0、実行が失敗したときは 0 以外なので、スクリプトで終了ステータスによる分岐ができます。無効なフラグはstderr にエラーが出ますが、認証が無いなど実行中の失敗は、結果として stdout に出力されます。監視を組むときは両方を意識してください。

出典: Run Claude Code programmatically

CI 向けの --bare と認証

--bare を付けると、hooks、skills、カスタムコマンド、サブエージェント、プラグイン、MCP サーバー、auto memory、CLAUDE.md の自動検出を省き、起動が速くなります。付けない claude -p は、対話セッションと同様に、作業ディレクトリや ~/.claude の設定まで読み込みます。

同僚の ~/.claude にある hook や、プロジェクトの .mcp.json にある MCP サーバーは、bare モードでは読まれず動きません。公式ドキュメントでは、--bare はスクリプトや SDK 呼び出しで推奨され、将来のリリースで -p の既定になる予定とされています。

claude --bare -p "Summarize README.md" --allowedTools "Read"

bare モードはサブスクリプションのログインを使わないため、実行前に ANTHROPIC_API_KEY の設定が必要です。OAuth 資格情報やシステムのキーチェーンも読みません。

注意点: --bare なしの -p は、一度も信頼していないフォルダでも、プロジェクトの .claude/settings.json の hooks を実行し、.mcp.json のサーバーへ接続します。ワークスペース信頼のダイアログも、サーバーごとの承認プロンプトも出ません。外部のリポジトリを扱う場合は、公式ドキュメントで何が動くかを確認してください。

出典: Run Claude Code programmatically

入力のパイプと出力形式

非対話モードは標準入力を読むので、ログをパイプで渡し、結果をファイルへ出力できます。

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

パイプで渡せる入力は 10MB が上限で、超えるとエラーと 0 以外のステータスで終了します。大きな入力は、ファイルに書き出してパスをプロンプトで指す方法が案内されています。

--output-format には、プレーンテキストの text(既定)、結果・セッション ID・メタデータを含む json、リアルタイム向けの stream-json があります。json ではテキストの結果が result フィールドに入るため、jq で取り出せます。

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

--output-format json と --json-schema で JSON Schema を渡すと、structured_output フィールドに構造化された結果が入ります。format キーワードは注釈として扱われ、強制されません。また json 出力には total_cost_usd が含まれますが、クライアント側の推定値で、実際の請求とは異なることがあります。

出典: Run Claude Code programmatically

無人実行の権限設定

--allowedTools に挙げたツールは、確認なしで使われます(ただし Read を挙げても、ネットワークパスからの読み取りは除きます)。ただし、auto mode で始まる実行では、素の Bash は広い許可ルールとして外され、auto mode が各コマンドを評価します。

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

権限モードを何も指定しないと、組み込みの開始モードになり、それが auto の場合もあります。意図するモードを明示してください。

• auto: --permission-mode auto で、分類器が多くの操作をレビューします。
• dontAsk: 本来プロンプトが出る呼び出しを拒否します。ロックダウンした CI 向きです。ただし承認不要の操作や、--allowedTools などで許可した操作は実行されます。
• acceptEdits: ファイル書き込みを確認なしで行い、mkdir、touch、mv、cp などを自動承認します。他のシェルコマンドやネットワークリクエストには許可の指定が必要です。

誰も承認できないスケジュールジョブなどでは --permission-prompts none を使います。プロンプトになる操作は、PermissionRequest hook が許可しない限り拒否され、実行は続きます。このフラグは Claude Code v2.1.259 以降が必要で、それ以前は unknown-option error になります。

出典: Run Claude Code programmatically

会話の継続と停止時の注意

--continue は直近の会話を続けます。複数の会話を扱うときは、セッション ID を控えて --resume に渡します。同じマシンなら、別のディレクトリからでも ID でセッションを見つけられます。

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

SIGTERM で止めると終了コードは 143 になり、進行中のターンは未完了のまま結果も記録されません。ターンを終わらせたい場合は、停止前に SIGINT を送るか、Agent SDK の interrupt() を呼びます。

メイン会話が始めたバックグラウンドコマンドが実行中でない限り、既定では連続 10 分の待機後に、まだ動いている処理を停止し、途中結果は破棄されます。上限は CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS で変えられます。なお、執筆時点(2026年10月)の公式ドキュメントでは、機能ごとに必要な Claude Code のバージョンが示されています。社内に配る前に、手元のバージョンを確認してください。

出典: Run Claude Code programmatically

参考(執筆時点)

• Run Claude Code programmatically(公式ドキュメント)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。