Claude Code は対話UIを立ち上げずに、コマンドとして一度だけ実行することもできます。これがヘッドレス（非対話）モードで、claude -p（print モード）で使います。スクリプトや CI（継続的インテグレーション）、他のプログラムから Claude Code を呼び出したいときに便利です。これは Anthropic 公式の Claude Code に実在する機能です。
ヘッドレスモードとは
通常の claude は対話的なセッションを開き、あなたと往復しながら作業します。これに対しヘッドレスモードは、プロンプトを1回渡して結果を受け取り、そのまま終了する使い方です。人が画面の前にいなくても動くため、定期実行のジョブや自動化パイプライン、他のツールからの呼び出しに向いています。
claude -p でワンショット実行
-p（または --print）フラグにプロンプトを渡すと、対話UIを開かずに一度だけ実行して結果を標準出力に返します。
# プロンプトを1回渡して結果を受け取る
claude -p "READMEの概要を3行に要約して"
# パイプで入力を渡すこともできる
cat error.log | claude -p "このログの原因を推測して"結果はそのまま標準出力に出るので、リダイレクトで保存したり、別のコマンドに渡したりできます。
出力フォーマットを指定する
プログラムから扱いやすいように、出力形式を --output-format で指定できます。既定はプレーンテキストですが、json を指定すると結果をメタ情報付きの JSON として受け取れ、後段のスクリプトでパースしやすくなります。
# 結果をJSONで受け取る
claude -p "package.jsonのdependenciesを一覧にして" --output-format json
# ストリーミングJSONで逐次受け取る
claude -p "大きめの調査タスク" --output-format stream-jsonJSON 出力には応答本文に加えて実行に関する情報が含まれるため、成否の判定やログ記録に使えます。
スクリプトやCIに組み込む
ヘッドレス実行はシェルスクリプトや CI から呼び出せます。例えばプルリクエストの差分に対して要約やチェックを行い、その結果を後続の処理に渡す、といった使い方ができます。
#!/usr/bin/env bash
set -euo pipefail
summary=$(git diff origin/main | claude -p "この差分の要点を箇条書きで")
echo "$summary"権限プロンプトで止まらないよう、非対話環境では 権限設定 で許可するツールを事前に絞り込んでおくのが実務的です。
注意点とベストプラクティス
- 非対話では確認プロンプトに答えられないため、必要なツールは permissions の allow で事前許可し、危険な操作は deny で禁止する。
- 後段でパースするなら
--output-format jsonを使い、テキストの体裁に依存しない。 - 秘密情報を標準出力やログに残さないよう、扱うデータと出力先に注意する。
- より本格的にプログラムへ組み込むなら、公式の Claude Agent SDK の利用も検討する。
関連記事: 設定と権限の管理 / GitHub Actions で使う