ヘッドレス実行（-p）

claude -p は、同じツール・エージェントループ・コンテキスト管理を、スクリプトや CI/CD から使うための非対話の実行方法です。プロンプトを -p（または --print）に渡し、必要な CLI のオプションを足します。Python と TypeScript のパッケージを使う、構造化出力・ツール承認のコールバック・ネイティブのメッセージオブジェクトまで含めた制御は、Agent SDK の基本を見てください。

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

• 成功すると終了コード 0、実行が失敗すると 0 以外で終わる。スクリプトが終了状態で分岐できる
• 無効なフラグは、実行の前に標準エラー出力へエラーが出る。認証がないなど、実行の内側の失敗は、結果として標準出力に出る
• 標準入力を読むので、データをパイプで渡し、応答をリダイレクトで取り出せる
• すべての CLI オプションが -p と組み合わせられるわけではない。--bg は拒否され、タスクの説明つきの --cloud も、競合を示すエラーで拒否される（セッション ID つきの --cloud と -p は、そのクラウドのセッションにメッセージを送って終了する）

-p とよく組み合わせるフラグ#

CLI の全フラグは、CLI のコマンドとフラグを見てください。

出力形式#

--output-format で、応答の返し方を決めます。

claude -p "Summarize this project" --output-format json

• json の応答には、total_cost_usd とモデルごとのコストの内訳が入るので、スクリプトから、使用量のダッシュボードを見ずに支出を追える。--continue や --resume で続けた実行は、以前の実行の分を含む会話の合計を報告する。どちらもクライアント側の見積りで、実際の請求とは違うことがある
• 結果のテキストは result フィールドに入る

構造化出力#

特定のスキーマに従う出力を得るには、--output-format json に --json-schema と JSON Schema の定義を組み合わせます。リクエストのメタデータ（セッション ID・使用量など）とともに、構造化された出力が structured_output フィールドに入ります。

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"]}'

値が有効な JSON Schema でないと、claude は Error: --json-schema is not a valid JSON Schema と検証器の診断を出して終了します。"format": "email" のような format キーワードを使うスキーマは受け付けられますが、format は注釈として扱われ、強制されません。v2.1.205 より前は、無効なスキーマが黙って無視されて構造化されないテキストが返り、format を含むスキーマはすべて無効と扱われました。

# テキストの結果を取り出す
claude -p "Summarize this project" --output-format json | jq -r '.result'

# 構造化出力を取り出す
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

ストリーミング#

--output-format stream-json に、--verbose と --include-partial-messages を付けると、生成されたトークンを逐次受け取れます。各行は、1つのイベントを表す JSON オブジェクトです。ストリームの最後の行は、最終的な応答のテキスト・コスト・セッションのメタデータを持つ result メッセージです。

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

受け手がストリームをゆっくり読むとき、Claude Code は、キューに残る出力が流れきるのを、残りの量に応じて最大30秒まで待ってから終了します（v2.1.214 より前は、終了の待ちが約2秒までで、大きな応答の末尾が切れることがありました）。次の例は jq で、テキストの差分だけを選んでストリーミングのテキストを表示します（-r は引用符なしの生の文字列、-j は改行なしでつなぐ）。

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

コールバックとメッセージオブジェクトによるプログラムからのストリーミングは、Agent SDK のドキュメントの「Stream responses in real-time」を見てください（SDK のセッションと入出力）。

サブエージェントのメッセージを追う#

サブエージェントのメッセージは、ストリームの中で assistant と user のメッセージとして現れ、parent_tool_use_id フィールドに、サブエージェントを起こしたツール呼び出しの ID が入ります。メインの会話のメッセージは、そのフィールドが null です。前面で動くサブエージェントの最初のメッセージは、それを動かすプロンプトを持つ user メッセージです。その最初のメッセージのあと、Claude Code は次を出力します。

• 既定：サブエージェントの tool_use と tool_result のブロック
• --forward-subagent-text または CLAUDE_CODE_FORWARD_SUBAGENT_TEXT を付けたとき：サブエージェントのテキストと thinking のブロックも出る。各サブエージェントのトランスクリプトを組み立て直せる（v2.1.211 以降）

どちらかを有効にすると、Claude Code は、あらゆる入れ子の深さのサブエージェントのメッセージを転送します（Agent ツールで起こしたものでも、フォークしたスキルとして始まったものでも）。フォークしたスキルが起こすサブエージェントや、サブエージェントや別のフォークしたスキルの中で始まったフォークしたスキルのメッセージには、v2.1.275 以降が必要です。入れ子のサブエージェントのメッセージは、parent_tool_use_id に、それを始めた Agent か Skill のツール呼び出しの ID が入るので、入れ子の全体を組み立て直せます。サブエージェントで動かすスキルも、ストリームに同じように現れます。フォークしたスキルの最初のメッセージは、実行を動かすスキルの内容を持つ user メッセージです。どちらかのオプションを有効にすると、フォークしたスキルのテキストと thinking のブロックもストリームに出ます（v2.1.265 より前は、フォークしたスキルの tool_use と tool_result のブロックだけが出ました）。

API のリトライを扱う#

再試行できるエラーで API のリクエストが失敗すると、Claude Code は再試行の前に system/api_retry イベントを出します。v2.1.246 以降は、apiKeyHelper の資格情報が 401 か 403 で拒否されたとき、最初の2回の再試行はイベントなしで静かに行い、3回連続の再試行からイベントを通常どおり出します（静かな再試行も attempt に数えられます）。イベントを使って、自分の画面に再試行の進み具合を出せます。

セッションのメタデータを読む#

system/init イベントは、モデル・ツール・MCP サーバー・読み込まれたプラグインを含むセッションのメタデータを報告します。起動時のイベントが先に来る場合を除き、ストリームの最初のイベントです。先に来るのは次のものです。

• plugin_install イベント（CLAUDE_CODE_SYNC_PLUGIN_INSTALL を設定しているとき）
• 設定した SessionStart や Setup フックが動く間の hook_started・hook_progress・hook_response イベント。フックが出力するのに合わせて流れる。v2.1.169〜v2.1.203 では、フックの完了後にまとめて届いた（それでも system/init の前）。v2.1.204 でリアルタイムの配信に戻った

イベントには、この Claude Code のバージョンが実装するプロトコルの動作の名前（interrupt_receipt_v1・interrupt_cancel_queued_v1 など）を並べた、任意の capabilities の文字列の配列もあります。バージョン文字列を比べる代わりに、これで機能の有無を判定し、知らない値は無視します（v2.1.205 以降で、それより前のバージョンにはありません）。

プラグインや MCP サーバーが読み込まれなければ CI を失敗させる#

system/init イベントのプラグインのフィールドで、読み込まれなかったプラグインを検出します。

--plugin-dir のディレクトリやアーカイブ自体が読み込みに失敗したとき、その plugin_errors の項目には、解決された絶対パスが path として入ります。複数の --plugin-dir のうち、どれが失敗したかが分かります（path フィールドは v2.1.283 以降）。MCP サーバーのフィールドも同じように使います。

• -p と --mcp-config を渡すと、Claude Code は、最初のターンの前に、まだ保留中のサーバーを、起動のタイムアウトの MCP_TIMEOUT（既定は30秒）まで待つ。キャッシュされたツール一覧を持つリモートサーバーは、待ちを飛ばし、system/init では pending と出て、最初のツール呼び出しで接続する。待つのは v2.1.221 以降
• Claude Code は、起動時に各 --mcp-config の項目を検証し、検証に失敗した項目（type のない url の項目など）は飛ばす。実行は続き、正常に終了するので、読み込まれなかったサーバーを見つけるにはこれらのフィールドを調べる

端末で手でコマンドを動かすときは、Claude Code は Warning: 1 MCP server skipped due to invalid config: のような起動の警告を標準エラー出力に出し、飛ばした項目ごとの理由を続けます。標準エラー出力をリダイレクトしたときや、CI のランナー・SDK のホストなどのプログラムが取り込むときは、警告を出さず、飛ばした項目は mcp_server_errors フィールドだけで報告されます（警告は v2.1.219 以降）。

プラグインのインストールを追う#

CLAUDE_CODE_SYNC_PLUGIN_INSTALL を設定すると、最初のターンの前にマーケットプレイスのプラグインがインストールされる間、Claude Code は system/plugin_install イベントを出します。自分の画面にインストールの進み具合を出すのに使えます。

bare モードで速く起動する#

--bare を付けると、フック・スキル・カスタムコマンド・サブエージェント・インストール済みのプラグイン・MCP サーバー・自動メモリ・CLAUDE.md の自動検出を飛ばして、起動を速くします。付けない claude -p は、作業ディレクトリや ~/.claude の設定を含め、対話セッションと同じコンテキストを読み込みます。

bare モードは、どのマシンでも同じ結果が要る CI やスクリプトで役立ちます。チームメイトの ~/.claude のフックや、プロジェクトの .mcp.json の MCP サーバーは、bare モードが読まないので動きません。--add-dir で指定したディレクトリは部分的な例外です。bare モードはその .claude/skills/ のスキルは読み込みますが、.claude/commands/ と .claude/agents/ は飛ばします。

次の例は、bare モードで1回きりの要約を行い、Read ツールを事前に承認して、権限プロンプトなしで呼び出しを終えます。bare モードはサブスクリプションのログインを使わないので、実行前に ANTHROPIC_API_KEY を設定してください。

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

bare モードでは、Claude Code は OAuth の資格情報もシステムのキーチェーンも読みません。Anthropic API では、Claude Console で作ったキーを環境の ANTHROPIC_API_KEY に設定するか、--settings の JSON に apiKeyHelper を渡します。Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry は、通常どおり自分のプロバイダーの資格情報を読み続けます。bare モードで Claude が使えるのは、Bash・ファイルの読み取り・ファイルの編集のツールです。必要な文脈はフラグで渡します。

bare モードは、セッションの実行中の動作も制限します。

• MCP サーバー：コマンドラインで渡したサーバー（--mcp-config など）だけが接続する。対話セッションでも、--ide を渡さないかぎり IDE への自動接続を飛ばす
• システムリマインダー：Claude は、Claude Code が通常は添えるシステムリマインダーなしで、プロンプトとツールの結果を受け取る。たとえば、以前読んだファイルがディスク上で変わっても Claude に伝わらず、--add-dir のフォルダのスキルを含む、使えるスキルの一覧も渡らない
• バックグラウンドタスク：動かない。タイムアウトに達したコマンドは、バックグラウンドへ移らず止まる

v2.1.286 より前は、これらの制限は部分的にしか効きませんでした。対話の --bare セッションは通常のセッションと同じ MCP サーバーに接続し、--bare のセッションはどれもシステムリマインダーを送り、バックグラウンドタスクも使えました。

権限を自動で扱う#

ツールを自動で承認する#

--allowedTools で、特定のツールを確認なしで使わせます。Read と Edit を並べると、許可を求めずにファイルを読み書きできます。Bash を並べると、シェルコマンドも同じになります。ただし、auto モードで始まる実行では、Claude Code は、素の Bash の項目を広い allow ルールとして落とし、auto モードが各コマンドを評価します。次の例は、この3つのツールを並べて、テストスイートを動かして失敗を直します。

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

個々のツールを並べる代わりに、セッション全体の基準を決めるには、権限モードを渡します。何も権限モードを設定しない実行は、組み込みの開始時の権限モードになり、これは auto のことがあるので、欲しいものを明示します。

claude -p "Apply the lint fixes" --permission-mode acceptEdits

--allowedTools は権限ルールの構文を使います。末尾の * が前方一致を有効にするので、Bash(git diff *) は git diff で始まるすべてのコマンドを許可します。* の前の空白は大事です。空白がない Bash(git diff*) は git diff-index にも合います。

無人の実行で権限プロンプトを切る#

スケジュールされたジョブのように、権限プロンプトに答えられる人がいないときは、--permission-prompts none を渡します（v2.1.259 以降。それより前のバージョンは、不明なオプションのエラーで拒否する）。このフラグがとくに効くのは、実行に権限のホストがあるとき、つまり canUseTool コールバックを持つ Agent SDK のアプリや、--permission-prompt-tool で渡した MCP ツールがあるときです。フラグがなければ、実行は、各権限の要求に、そのホストが答えるのを待ちます。

• フラグがあると、実行はホストに問い合わせず、待たない。プロンプトが出るはずのものは、PermissionRequest フックが許可しない限り拒否され、Claude は、誰も承認できないので再試行しないよう伝えられて、実行は続く
• ホストのない -p の実行では、これらの要求はどちらにしても拒否されるが、フラグは、再試行しないことも Claude に伝える
• 権限ルール・PermissionRequest フック・設定した権限モードが、まずすべての呼び出しを決める。Claude Code が拒否するのは、ほかに何も決められなかった要求だけ
• AskUserQuestion のように人の答えが要るツールは取り除かれ、Claude は呼べない。Elicitation フックが答えない MCP の入力要求はキャンセルされる
• --output-format stream-json では、拒否が permission_denied のシステムメッセージとして出て、最終的な結果のメッセージの permission_denials に並ぶ

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

使用例#

コマンドが auth.py や build-error.txt のようなファイルを挙げるところは、自分のプロジェクトのファイルに置き換えてください。

データをパイプで渡す#

非対話モードは標準入力を読みます。ほかのコマンドラインのツールと同じように、データをパイプで渡し、応答をリダイレクトで取り出せます。次の例は、ビルドのログを Claude に渡して、説明をファイルへ書きます。

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

標準入力を読めないとき（起動したプロセスが、その端を切り離したなど）は、Claude Code は標準エラー出力に警告を出し、コマンドラインのプロンプトで続けます（v2.1.211 より前は、Windows で標準入力が読めないとセッションがクラッシュするか、出力なしで静かに終了しました）。

ビルドのスクリプトに Claude を入れる#

非対話の呼び出しをスクリプトで包むと、Claude をプロジェクト固有のリンターやレビュアーとして使えます。次の package.json のスクリプトは、main との差分を Claude にパイプで渡し、タイポを報告させます。差分をパイプで渡せば、Claude にそれを読む Bash の権限が要りません。エスケープした二重引用符は、スクリプトを Windows でも動かせるようにします。

{
  "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.\""
  }
}

npm run lint:claude で実行します。

コミットを作る#

次の例は、ステージ済みの変更を見て、適切なメッセージでコミットを作ります。

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

システムプロンプトをカスタマイズする#

--append-system-prompt で、Claude Code の既定の動作を保ったまま指示を足します。次の例は、PR の差分を Claude にパイプで渡し、セキュリティの脆弱性をレビューするよう指示します。たとえば review.sh というシェルスクリプトとして保存します。

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

スクリプトの "$1" は、コマンドラインで渡す最初の引数です。bash review.sh 123 を実行すると、シェルが "$1" を 123 に置き換え、スクリプトは PR 123 の差分を取ります。Claude Code は、レビューを JSON で出力し、テキストは result フィールドに入ります。既定のプロンプトを丸ごと置き換える --system-prompt を含む、そのほかのオプションは、CLI のコマンドとフラグのシステムプロンプトのフラグを見てください。

会話を続ける#

直近の会話を続けるには --continue、特定の会話を続けるにはセッション ID つきの --resume を使います。v2.1.257 以降は、--continue を渡すと、Claude Code は、終わったバックグラウンドセッションは開きますが、まだ動いているものは開きません。次の例は、レビューを実行してから、続きのプロンプトを送ります。

# 最初のリクエスト
claude -p "Review this codebase for performance issues"

# 直近の会話を続ける
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

複数の会話を動かすときは、セッション ID を取っておいて、特定のものを再開します。

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

2つのコマンドは別のディレクトリから実行できます。Claude Code は、このマシンのどのプロジェクトからでも、ID でセッションを見つけます。v2.1.223 より前は、現在のプロジェクトのディレクトリとその git worktree の中だけで ID を探したので、同じディレクトリから両方を実行する必要がありました。セッション ID の代わりに、セッションの .jsonl のトランスクリプトファイルの絶対パスを --resume に渡すと、そのファイルに保存された会話が続けられます。

終了時の動作#

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

claude -p の実行中に、Claude がバックグラウンドの Bash タスク（開発サーバーや watch ビルドなど）を始めると、Claude が最終的な結果を返し、標準入力が閉じてから約5秒後に、そのシェルは終了されます。猶予の間に、結果の直後に終わるタスクも出力を届けられます。

• Claude がバックグラウンドのサブエージェントやワークフローを始めると、claude -p は、その結果が最終出力の一部なので、作業が終わるまで開いたままになる
• 待ちは、既定では連続したアイドルの待ちが10分で終わるので、止まったサブエージェントやワークフローがプロセスを無期限に開いたままにしない。そのとき Claude Code は、まだ動いているものを止め、部分的な結果を捨てる。上限を変えるには CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS を設定し、0 にすると上限なしで待つ
• claude -p の実行中に、Claude が Monitor の監視を始めると、Claude Code は、監視がタイムアウトするか、10分の上限で待ちが終わるか、早いほうまで待つ。待つ間、Claude は監視が報告する内容に応答し続ける。既定では、監視は Claude が始めて5分でタイムアウトする

SIGTERM で実行を止める#

kill やプロセスの監視ツールなどで、claude -p の実行を SIGTERM で止めると、Claude Code は終了コード 143 で終わります。進行中のターンは未完のままで、結果は記録されません。代わりにターンを終わらせるには、プロセスを止める前に、SIGINT を送るか、Agent SDK の interrupt() を呼びます。

SIGTERM を受けると、Claude Code は、まだ動いている Bash コマンドのプロセスツリーを終了させ、SessionEnd フックを動かして終了します。終了の間、Claude Code は、新しいツール呼び出しも、新しいモデルのリクエストも始めず、SessionEnd 以外のフックも動かしません。シグナルが届いたとき、実行がコマンドの途中か権限プロンプトの待ちだった場合の扱いは次のとおりです。

• コマンドの実行中：Claude Code は、そのコマンドを、セッションで終了されたものとして記録する
• 権限プロンプトへの答えを待っていた：プロセスに SIGTERM を送ったなら、プロンプトは答えのないまま残る。Agent SDK でプログラムがセッションを閉じるときは、SDK がシグナルを送る前に Claude Code の入力を終わらせ、Claude Code は入力が終わるとすぐプロンプトをキャンセルする

セッションを再開すると、Claude Code は中断されたターンをそのままにし、次のプロンプトが会話を進めます。再開時に、中断されたターンを続けさせるには、CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1 を設定します。

作業ディレクトリが削除されたとき#

claude -p や Agent SDK のセッションの作業ディレクトリがセッション中に削除されても、セッションは動き続けます。ディレクトリがない間にターンが始まると、Claude Code は stream-json の出力に警告メッセージを出し、シェルコマンドは、ディレクトリが再び存在するまで失敗します。

関連：Agent SDK のクイックスタート（Agent SDK の基本）、GitHub Actions と GitLab CI/CD で Agent SDK を使う方法も見てください。