Claude Code ヘッドレスモード解説：-p、CI、GitHub Action
Claude Code を Unix ツールのようにスクリプト化：claude -p でワンショット実行、ファイルをパイプで入力、JSON を出力してパース、セッションを ID で再開、CI では --bare、そして @claude GitHub Action が issue から機能を作るところまで — Anthropic 自身のウォークスルーに基づく解説。
要点まとめ
- claude -p "prompt" は 1 回実行して結果を出力するだけ — 対話セッションなし。どんな Unix ツールとも同じように組み合わせられます：パイプで入れ、パイプで出し、スクリプトや CI ステップに連ねる。
- --output-format json は結果に加えて session_id、コスト、メタデータを返します。stream-json はリアルタイム消費者向けに改行区切りのイベントを出します。jq でパースして、その上に構築。
- ヘッドレスはデフォルトで編集・破壊的な権限を持ちません。--allowedTools "Bash(git diff *),Edit" で必要なものだけを許可 — パーミッションルール構文、前方一致。
- @claude GitHub Action はフロントエンドつきのヘッドレスモードです：issue や PR で @claude をタグすれば、コードを読み、PR とコミットを作り、質問に答え、コードをレビュー — あなた自身の GitHub ランナー上で。
Building headless automation with Claude Code | Code w/ Claude
チャンネル: Anthropic20:59
Headless mode — official documentation
公式ドキュメント: code.claude.com/docs
Claude Code GitHub Action — official docs
公式ドキュメント: code.claude.com/docs
このページのフラグ、制限、挙動は公式のヘッドレスドキュメントに対して検証しています。上の講演は Anthropic 自身のウォークスルーで、スクリーンショットのビジュアルソースです。
スクリーンショットは各制作者に帰属し、該当タイムスタンプへ深リンクしています。登壇者と観客のショットは使用していません。
Claude Code をヘッドレスで動かす、ステップごとに
パート 1 — ヘッドレスの基本
- 1
ヘッドレスモードとは
ヘッドレスモードは対話 UI なしの Claude Code：同じエージェントをプログラムから駆動します。Anthropic はこれをエージェント型アプリケーションのシンプルな構成要素と位置づけています — スクリプトやパイプラインの中の Unix ツールとして、CI 自動化やリモート環境に、あるいは Web チャット画面のエンジンとして。
Anthropic 自身の位置づけ：SDK はヘッドレス環境の Claude Code へのプログラマティックアクセス。2:10 から視聴 - 2
claude -p でワンショット実行
-p（--print）フラグは 1 つのプロンプトを実行して終了します：claude -p "Write me a function that calculates the Fibonacci sequence"。何も開いたままになりません — 出力は stdout に、スクリプトがチェックできる終了コードとともに得られます。書き込み権限は --allowedTools で前もって付与を。
ワンショットの問い：claude -p がフィボナッチ関数を生成して終了 — TUI もフォローアップもなし。3:30 から視聴 - 3
ファイルをパイプで直接 Claude へ
stdin は普通の CLI ツールと同じように動きます：cat app.log | claude -p "summarize the most common error logs"。Anthropic のデモでは 2000 行のログを入れ、平易な英語のエラー要約が出てきます — ビルド失敗、スタックトレース、エクスポートでも同じ技が使えます。パイプされた stdin は 10MB まで。
cat とパイプ記号と claude -p：2000 行のログが 3 文の診断になります。3:55 から視聴 - 4
読みたくない出力を解読させる
同じパターンで手に負えない出力が答えに変わります：ifconfig | claude -p "what interfaces do I have configured? don't include lo"。コマンドが出力するものなら何でも — ネットワーク状態、コンパイラエラー、terraform プラン — 人間向けの要約のために Claude に通せます。
claude -p にパイプされた ifconfig：全インターフェースを解説、ループバックはリクエストどおり除外。4:15 から視聴 - 5
構造化された JSON を受け取る
--output-format json を付けると応答はパース可能なオブジェクトになります：結果テキスト、session_id、所要時間、total_cost_usd。リアルタイム消費には --output-format stream-json が出来事のたびに改行区切りのイベントを出します — 最後の行が最終結果です。
JSON モード：結果と、あとで再開できるセッション ID、そして実行コストが 1 つの塊に。4:35 から視聴
パート 2 — エンジニアのようにスクリプトする
- 6
ツールを意図的に許可する
ヘッドレスは編集・破壊的な権限なしで始まります。--allowedTools はタスクに必要なものを事前承認します。パーミッションルール構文で：--allowedTools "Bash(npm run build),Bash(npm test:*),Write"。MCP ツールも同じやり方で許可リストに載せられます — 仕事が済む最小限のセットだけ渡しましょう。
SDK 深掘り：ツール権限、構造化出力モード、カスタムシステムプロンプトを 1 枚のスライドで。11:00 から視聴 - 7
実行をまたいでコンテキストを保つ
JSON モードは session_id を返します — それを --resume "$session_id" で渡せば、後の実行や別のプロセスから同じ会話状態を続けられます。これが対話型プロダクトをその上に作る方法です：ユーザーが発言、Claude が応答、次のターンのためにセッションを保存。
- 8
権限確認を人間なしで処理する
Claude がどのツールを必要とするか予測できないなら、--permission-prompt-tool が承認の判断を実行時に MCP サーバーへ委ねます — そのツールがあなたのサービス（またはアプリ経由でユーザー）に、各アクションを許すか尋ねてくれます。全部を事前列挙する必要はありません。
- 9
CI では --bare を使う
--bare は hooks、skills、カスタムコマンド、サブエージェント、プラグイン、MCP サーバー、CLAUDE.md の自動検出をスキップして、最速の起動を実現します — スクリプトと CI に推奨で、-p のデフォルトになる見込みです。ANTHROPIC_API_KEY が必要で、コンテキストはフラグで明示的に渡します。
パート 3 — @claude GitHub Action
- 10
@claude GitHub Action と出会う
GitHub Action は SDK の上にフロントエンドを載せたヘッドレスモードです。任意の PR や issue で @claude をタグすれば、コードを読み、PR を作り、既存の PR にコミットを積み、質問に答え、変更をレビュー — すべて既存の GitHub ランナー上で動くので、世話するインフラはありません。
Action の契約：@claude をタグし、必要なものを書けば、自分のランナー上でリポジトリをこき使います。17:10 から視聴 - 11
issue を Claude にアサインする
Anthropic のライブデモでは、「@claude please implement this feature and comment on it」というコメントに対してボットがスコープされた計画 — 作るものの箇条書き — で返信し、それからブランチ、コミット、プルリクエストを作成しました。すべて Action のログで追跡できます。
実際の issue への @claude コメント：Claude はコードに触れる前にスコープされた計画を返信します。7:50 から視聴 - 12
自分のリポジトリに導入する
結果は issue 上のチェック済み実装サマリーです — 機能は追加され、todo はクローズ。そこへたどり着くには、リポジトリで Claude Code を開いて /install-github-action を実行：インタラクティブなフローが workflow YAML の入った PR を開き、API キーをリポジトリのシークレットに設定してマージします。
完了したラン：Action がデモアプリに追加した全機能を並べた、チェック済みの実装サマリー。13:30 から視聴
ヘッドレス vs 対話 vs SDK vs GitHub Action
同じエージェントを駆動する 4 つの方法 — 誰が（何が）尋ねるかで選びます：
- 1対話 CLI — TUI セッション：権限プロンプト、plan モード、/コマンド。いま目の前のタスクを進める人間に最適。
- 2ヘッドレスの claude -p — プログラマティックな 1 発：stdin と stdout、終了コード、UI なし。スクリプト、cron ジョブ、他ツールからの気軽な質問に最適。
- 3Agent SDK — 同じヘッドレスの力を型付きライブラリで：マルチターンのセッション、カスタムツール、ストリーミング。Claude をアプリ内のコンポーネントにするときに最適。
- 4@claude GitHub Action — GitHub のイベントモデル上で走るヘッドレス：あなたのランナーで issue、PR、レビュー。チーム全員が発火できるリポジトリ単位の自動化に最適。
- 5--bare のヘッドレス — CI 向けの最小起動：CLAUDE.md、hooks、skills、プラグイン、MCP の自動検出なし。コンテキストはフラグで明示、コールドスタート最速。
モデルアクセスと権限システムは共有です — ヘッドレスに許可したパーミッションルールはどこでも効く、だから --allowedTools の規律が重要になります。
ヘッドレスの挙動がおかしい？応急処置
ヘッドレス特有の 5 つの落とし穴と、それぞれの対処法：
- 1Claude が終わる前にスクリプトが抜ける。終了コードを確認：0 は成功、それ以外は失敗。SIGTERM は 143 で抜けてターンを未完了のまま置きます — 途中で止めるなら SIGINT か SDK の interrupt() で終わりましょう。
- 2パイプした入力が黙って切れる。stdin は 10MB まで — 大きなペイロードはファイルに書いて、プロンプトでそのパスを参照する方式に。
- 3「--bg rejected」や --cloud エラー。対話専用のフラグは -p には効きません：--bg はそのまま拒否され、--cloud はタスクの説明ではなくセッション ID とセットでメッセージをキューします。
- 4CI の実行が CLAUDE.md と hooks を無視する。それは --bare が仕事をしているから：自動検出をスキップしています。--settings、--mcp-config、--agents、--plugin-dir でコンテキストを明示的に渡しましょう。
- 5バックグラウンドの bash タスクが途中で死ぬ。バックグラウンドシェルは結果が届いてから約 5 秒で kill されます。サブエージェントとワークフローは最大 10 分のアイドル上限までプロセスを生かします。CI では明示的に待ち合わせを。
それ以外は --verbose を付けて stream-json のイベントを読みましょう — system/init が実際に読み込まれたモデル、ツール、MCP サーバーを名指ししてくれます。