ヘッドレスモードとは？

詳しい解説

ヘッドレスモード（非対話モード）とは、Claude Code をターミナル UI を起動せずに、シェルから単発のプロンプトとして実行するモードです。通常モードでは claude を起動すると対話型 REPL が立ち上がり、人間が逐次プロンプトを入力して応答を読みながら進めますが、ヘッドレスモードでは claude -p "プロンプト" または claude --print "プロンプト" のように、引数で渡したプロンプトを Claude が処理し、結果を標準出力に返してプロセスが終了します。これにより Bash スクリプト、Makefile、GitHub Actions、Cron ジョブ、Cloud Run Jobs といった自動化基盤に Claude Code を組み込めるようになります。 出力フォーマットは --output-format フラグで指定でき、text（既定の人間可読形式）、json（最終結果と使用トークン、コストをまとめた JSON）、stream-json（応答生成中のイベントを JSON Lines で逐次出力）の 3 種類から選べます。json 形式は jq で加工して別ジョブに引き渡す用途に最適で、stream-json はチャットボットや独自 UI から Claude Code を子プロセスとして呼び出すケースに向いています。標準入力からプロンプトを流し込むこともでき、echo "コードレビューして" | claude -p のように既存のシェル資産と組み合わせやすいのも特徴です。 認証は Claude Code 本体と共通で、ANTHROPIC_API_KEY 環境変数または OAuth で保存された SSO 資格情報を自動で参照します。CI 環境では API キーをシークレットに登録し env として注入する運用が一般的です。GitHub Actions では steps の run で claude -p を呼び出し、PR の差分レビューやリリースノート生成、Issue の自動トリアージといったワークフローが組めます。Cron + Cloud Run Jobs では夜間のドキュメント更新やテストカバレッジレポート生成にも使えます。 注意点として、ヘッドレスモードは長時間応答するとシェル側のタイムアウトに引っかかるため、CI 側で十分なタイムアウトを設定し、--output-format json で終了コードと使用コストをパースしてエラーハンドリングを行うのが安全です。--dangerously-skip-permissions と組み合わせると完全無人で動かせますが、本番リポジトリに対しては --allowedTools で実行可能ツールを絞り、ログを必ず CI のアーティファクトとして保存するのが鉄則です。会話継続が必要な場合は --resume や --session-id で既存セッションを引き継げます。

使用例

echo "コードレビューして" | claude -p --output-format json > review.json