[Claude Code #14] claude -p ヘッドレス：AIをパイプに組み込む

Claude Codeをチャット画面だけで使っているなら、機能の半分しか使っていません。ターミナルのパイプラインに組み込めば、grepやjqのようなUnixツールとして使えます。

ポイントは-p（または--print）フラグです。対話画面なしで1つのプロンプトを処理し、結果だけを出力して終了します。

claude -p "auth このモジュールの役割を説明して"

Claude Code 第13回までがセッション内の話だとすれば、今回はセッションの外から使う方法です。

パイプで入力し、ファイルで受け取る

公式ドキュメントを基準にすると、-pモードは標準入力を読み取ります。データをパイプで渡して結果をリダイレクトすれば、ほかのCLIツールと同じです。

cat build-error.txt | claude -p 'このビルドエラーの根本原因を簡潔に説明して' > output.txt

公式ドキュメントを基準に、成功時は終了コード0、失敗時は0以外で終了するため、スクリプトで分岐できます。パイプ入力は10MBまでなので、それを超える場合はプロンプトにファイルパスを書いて回避します。

package.jsonのスクリプトに追加すれば、プロジェクト専用のリンターも作れます。diffをパイプで渡し、誤字だけを報告させるといった使い方です。

JSONで受け取り、プログラムから利用する

--output-format jsonを付けると、セッションIDやコストなどのメタデータとともに、結果が構造化されて返ります。

claude -p "このプロジェクトを要約して" --output-format json | jq -r '.result'

特定のスキーマに合わせた出力が必要なら、--output-format jsonに--json-schemaを追加します。レスポンスはstructured_outputフィールドに検証済みの構造で返ります。

トークン単位のリアルタイムストリーミングには--output-format stream-json --verbose --include-partial-messagesの組み合わせを使います。

権限は事前に開いておく

-pモードには承認ボタンを押す人がいません。必要なツールは事前に許可しておく必要があります。

claude -p "テストを実行して失敗を修正して" --allowedTools "Bash,Read,Edit"

--allowedToolsは権限ルールの構文をそのまま使います。Bash(git diff *)のように絞り込めます。アスタリスクの前の空白が重要です。空白がないとgit diff-indexまでマッチしてしまいます。

--permission-mode acceptEditsを指定すると、ファイル書き込みとmkdir・mvのような一般的なファイルシステムコマンドが自動承認されます。それ以外のシェルコマンドやネットワークリクエストには、引き続き--allowedToolsが必要です。

会話を続ける

1回の呼び出しで終わらない作業は、セッションを続ければ対応できます。

claude -p "このコードベースのパフォーマンス問題をレビューして"
claude -p "ここから DB クエリに集中して" --continue

複数の会話を並行して進める場合は、JSON出力のsession_idを保存し、--resumeで特定の会話を指定して再開します。

CIでは–bareが定石

スクリプトやCI用途なら、--bareも併用するのがおすすめです。フック・スキル・プラグイン・MCP・CLAUDE.mdの自動読み込みをスキップするため起動が速くなり、どのマシンでも同じ結果になります。

セキュリティ上の理由もあります。-pセッションではワークスペースの信頼確認画面を表示できないため、--bareがないと、見慣れないリポジトリのフックやMCPサーバーまでそのまま実行されます。公式ドキュメントも、スクリプト呼び出しには--bareを推奨モードとして明記しています。今後は-pのデフォルトになる予定とも説明されています。

--bareでは、サブスクリプションログインの代わりにANTHROPIC_API_KEY環境変数を使う必要がある点だけ覚えておいてください。

まとめ

claude -pはClaude CodeをUnixツールに変えます。パイプで入力し、JSONで受け取り、終了コードで分岐しましょう。

権限は--allowedToolsで事前に開き、CIでは--bareで決定的かつ安全に実行します。

次回は対話画面に戻り、!シェルモードとCtrl+Oなどの特殊入力・ショートカットを総まとめします。

出典と確認基準

• Claude Code公式ドキュメント — Run Claude Code programmatically（Anthropic、2026-08-14確認）

あわせて読みたい

Claude Codeシリーズ

• 前回：[Claude Code #2] /plan計画モード：変更前に設計を合意する
• 前回：[Claude Code #1] /init、CLAUDE.mdの自動生成で始める

関連トピック

• [エージェント設計 #1] ハーネスエンジニアリングとは？プロンプトの次に来るもの