Run Claude Code programmatically

概要

claude -p（--print）で Claude Code を非対話実行する方法。スクリプトや CI/CD から Agent SDK の CLI として使う。Python / TypeScript のパッケージは別ページが扱う。

仕様

基本

任意の claude コマンドに -p（または --print）を付けると非対話実行になる
成功時は終了コード 0、失敗時は 0 以外で終了する
不正なフラグを渡した場合、実行開始前に stderr へエラーを報告する
実行中の失敗（認証情報が無いなど）は結果として stdout に出力される
-p と組み合わせられないオプションがある。--bg は拒否され、--cloud にタスク説明を付けた形も拒否され、衝突を示すエラーになる。--cloud にセッション ID を付けた -p は、そのクラウドセッションにメッセージをキューイングして終了する
よく併用するオプション: --continue / --allowedTools / --output-format

bare モード

--bare を付けると hooks / skills / plugins / MCP サーバー / auto memory / CLAUDE.md の自動探索を飛ばし、起動時間を短縮する
付けない場合、claude -p は対話セッションと同じコンテキストを読み込む（作業ディレクトリや ~/.claude の設定を含む）
bare モードでは OAuth 認証情報もシステムキーチェーンも読まない。Anthropic API を使う場合は環境変数 ANTHROPIC_API_KEY を設定するか、--settings の JSON で apiKeyHelper を渡す。Amazon Bedrock / Google Cloud's Agent Platform / Microsoft Foundry は従来どおり各プロバイダの認証情報を読む
bare モードで Claude が使えるのは Bash、ファイル読み取り、ファイル編集のツール

読み込ませたいもの	フラグ
システムプロンプトへの追記	`--append-system-prompt`, `--append-system-prompt-file`
Settings	`--settings <file-or-json>`
MCP サーバー	`--mcp-config <file-or-json>`
カスタム agent	`--agents <json>`
plugin	`--plugin-dir <path>`, `--plugin-url <url>`

--bare はスクリプト・SDK 呼び出しの推奨モードで、将来のリリースで -p の既定になる。

終了時のバックグラウンドタスク

claude -p の実行中に開始したバックグラウンド Bash タスクのシェルは、Claude が最終結果を返して stdin が閉じた約 5 秒後に終了させられる
バックグラウンドの subagent とワークフローは結果が最終出力の一部なのでこの 5 秒の猶予の対象外で、claude -p は完了を待つ。v2.1.182 以降、その待ち時間は既定で 10 分が上限。上限は CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS で変更でき、0 で無制限になる
v2.1.163 より前は、終了しないバックグラウンドプロセスが claude -p の呼び出しを無期限に保持していた
SIGTERM で停止した場合、進行中のターンを中断し、実行中の Bash コマンドのプロセスツリーを終了させ、SessionEnd hook を実行して終了コード 143 で終了する

stdin / パイプ

非対話モードは stdin を読むため、他のコマンドラインツールと同様にパイプ・リダイレクトできる
パイプした stdin の上限は 10MB。超えるとエラーを出して 0 以外のステータスで終了する。より大きな入力はファイルに書き、プロンプトでそのパスを参照する
stdin を読めない場合は stderr に警告を出し、コマンドラインのプロンプトで続行する。v2.1.211 より前は、Windows で読めない stdin がセッションをクラッシュさせるか、出力なしで静かに終了させていた

出力形式

--output-format の値:

値	内容
`text`（既定）	プレーンテキスト
`json`	結果・セッション ID・メタデータを含む構造化 JSON
`stream-json`	リアルタイムストリーミング用の改行区切り JSON

--output-format json のペイロードには total_cost_usd とモデル別のコスト内訳が含まれる。いずれもクライアント側の推定値で実際の請求と異なりうる
特定スキーマに沿った出力を得るには --output-format json と --json-schema に JSON Schema 定義を渡す。構造化出力は structured_output フィールドに入る
スキーマが不正な場合、Error: --json-schema is not a valid JSON Schema に続けてバリデータの診断を出して終了する。format キーワード（"format": "email" など）を含むスキーマは受け付けるが、format は注釈として扱い強制しない。v2.1.205 より前は不正なスキーマを黙って無視して非構造化テキストを返し、format を含むスキーマをすべて不正と扱っていた

ストリーミング

--output-format stream-json に --verbose と --include-partial-messages を付けると、生成中のトークンをイベントとして受け取る。各行が JSON オブジェクト
ストリーム最終行は result メッセージで、最終応答テキスト・コスト・セッションメタデータを含む
消費側の読み取りが遅い場合、キューに残る出力を吐き出すまで待ってから終了する。待ち時間は残量に応じてスケールし、上限 30 秒。v2.1.214 より前は上限が約 2 秒で、大きな応答の末尾が切れることがあった

subagent のメッセージ

subagent のメッセージは assistant / user メッセージとして流れ、parent_tool_use_id に subagent を生成したツール呼び出しの ID が入る。メイン会話のメッセージはこのフィールドが null
既定では subagent の tool_use と tool_result ブロックのみを出力する。--forward-subagent-text フラグまたは CLAUDE_CODE_FORWARD_SUBAGENT_TEXT を設定すると subagent のテキストと thinking ブロックも出力する。v2.1.211 以降が必要
有効にすると、あらゆるネスト深度の subagent のメッセージが転送される。ネストした subagent のメッセージはそれを生成した Agent ツール呼び出しの ID を parent_tool_use_id に持つ。v2.1.219 より前はネストした subagent のメッセージがストリームに現れなかった

`system/api_retry` イベント

再試行可能なエラーで API リクエストが失敗すると、再試行前に system/api_retry イベントを出力する。

フィールド	型	内容
`type`	`"system"`	メッセージ種別
`subtype`	`"api_retry"`	retry イベントであることを示す
`attempt`	integer	現在の試行番号（1 始まり）
`max_retries`	integer	許可される再試行回数
`retry_delay_ms`	integer	次の試行までのミリ秒
`error_status`	integer または null	HTTP ステータスコード。HTTP 応答の無い接続エラーでは `null`
`error`	string	エラー分類: `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown`
`uuid`	string	イベント識別子
`session_id`	string	属するセッション

`system/init` イベント

モデル、ツール、MCP サーバー、読み込まれた plugin などのセッションメタデータを報告する。通常はストリーム最初のイベント
ただし先行しうる起動イベントがある
- CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されているときの plugin_install イベント
- SessionStart / Setup hook 実行中の hook_started / hook_progress / hook_response イベント。v2.1.169〜v2.1.203 は hook 完了後に一括配信していたが、v2.1.204 でライブ配信に戻った
任意の capabilities 配列を持ち、この Claude Code バージョンが実装するプロトコル挙動（interrupt_receipt_v1、interrupt_cancel_queued_v1 など）を示す。バージョン文字列の比較ではなくこれで機能検出する。認識できない値は無視する。v2.1.205 以降が必要で、それ以前には存在しない

plugin 関連のフィールド:

フィールド	型	内容
`plugins`	array	正常に読み込まれた plugin。各要素は `name` と `path`
`plugin_errors`	array	plugin の読み込み時エラー。各要素は `plugin` / `type` / `message`。依存バージョン未充足や `--plugin-dir` の読み込み失敗（パス欠落、不正なアーカイブ）を含む。該当 plugin は降格され `plugins` に現れない。エラーが無いときはキー自体が省略される

MCP 関連のフィールド:

フィールド	型	内容
`mcp_servers`	array	セッション内の MCP サーバー。各要素は `name` と `status`
`mcp_server_errors`	array	設定検証でスキップされた `--mcp-config` エントリ。各要素は `name` / `type` / `message`。`type` は `unknown_type` / `url_missing_type` / `invalid_config` / `reserved_name` などのスキップ分類。該当サーバーは `mcp_servers` に現れない。エラーが無いときはキーが省略されるため、非空配列で CI を落とせる。v2.1.219 以降が必要

-p で --mcp-config を渡した場合、最初のターンの前に保留中のサーバーを MCP_TIMEOUT の起動タイムアウト（既定 30 秒）まで待つ。ツール一覧をキャッシュ済みのリモートサーバーは待たずに system/init で pending を示し、最初のツール呼び出し時に接続する。この待機は v2.1.221 以降が必要
起動時に各 --mcp-config エントリを検証し、検証に失敗したもの（type の無い url エントリなど）はスキップする。実行は継続して正常終了する
端末で手動実行した場合は Warning: 1 MCP server skipped due to invalid config: のような起動警告を stderr に出す。stderr をリダイレクトした場合や CI ランナー・SDK ホストが捕捉した場合は警告を出さず、mcp_server_errors にのみ報告する。この警告は v2.1.219 以降が必要

`system/plugin_install` イベント

CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されているとき、最初のターンの前に marketplace plugin をインストールしながら出力する。

フィールド	型	内容
`type`	`"system"`	メッセージ種別
`subtype`	`"plugin_install"`	plugin インストールイベント
`status`	`"started"` / `"installed"` / `"failed"` / `"completed"`	`started` と `completed` が全体を囲み、`installed` と `failed` は個々の marketplace を報告する
`name`	string（任意）	marketplace 名。`installed` と `failed` に付く
`error`	string（任意）	失敗メッセージ。`failed` に付く
`uuid`	string	イベント識別子
`session_id`	string	属するセッション

ツールの自動承認

--allowedTools に列挙したツールはプロンプトなしで使える。構文は permission rule syntax に従う
- 末尾の * は前方一致。Bash(git diff *) は git diff で始まる任意のコマンドを許可する。* の前のスペースが重要で、無い場合 Bash(git diff*) は git diff-index にもマッチする
セッション全体の基準を決めるには permission mode を渡す
- dontAsk は permissions.allow ルールにも read-only コマンド集合にも該当しないものを拒否する
- AskUserQuestion、組織が ask に設定した connector ツール、requiresUserInteraction が付いた MCP ツールは、allow ルールに一致しても拒否される
- acceptEdits はプロンプトなしのファイル書き込みを許し、mkdir / touch / mv / cp などの一般的なファイルシステムコマンドも自動承認する。それ以外のシェルコマンドとネットワークリクエストには --allowedTools エントリか permissions.allow ルールが必要で、無い場合は実行しようとした時点で run が中断する

システムプロンプトのカスタマイズ

--append-system-prompt で Claude Code の既定挙動を保ったまま指示を追加する
既定プロンプトを完全に置き換える --system-prompt などは cli-reference の system prompt flags を参照

会話の継続

--continue で直近の会話を継続、--resume <session-id> で特定の会話を継続する
2 つのコマンドは別ディレクトリから実行してよい。Claude Code はこのマシン上のどのプロジェクトからでも ID でセッションを見つける。v2.1.223 より前は現在のプロジェクトディレクトリとその git worktree しか探さなかった

設定

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
claude --bare -p "Summarize README.md" --allowedTools "Read"
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
claude -p "Summarize this project" --output-format json
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
claude -p "Apply the lint fixes" --permission-mode acceptEdits

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

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

制約・注意点

ユーザーが呼び出す skill やカスタムコマンドは -p モードでも動く。プロンプト文字列に /skill-name を含めると展開される
/login のようにターミナル UI でしか動かない組み込みコマンドは -p モードでは使えない
/model / /effort / /fast / /color / /rename は値を引数として受け取る（例: /model sonnet）。/mcp を引数なしで渡すとサーバー状態のテキスト要約を出力する。これらの形式は v2.1.205 以降が必要で、各コマンド自身の可用性の注記にも従う（例: /fast は --settings で fast mode を有効にして起動したセッションでのみ動く）
-p から設定を変えるには /config に key=value を渡す（例: /config thinking=false）