Claude Code -pモードでスクリプトやパイプラインを自動化する基本

はじめにClaude Code -pモードとは

claude -p(--printの短縮形)とは、Claude Codeを対話プロンプトなしで一度きり実行するモードです。プロンプトを渡して結果を受け取り、そのまま終了します。CIパイプライン・pre-commitフック・cronジョブなど、人が画面の前にいない場所へClaude Codeを組み込むときの基本になるモードです。

対話セッションと同じツール群・エージェントループ・文脈管理をそのまま使いながら、標準入出力とプロセスの終了コードで結果をやり取りします。この記事では、コマンドの基本形からCIへの組み込みまでの土台を扱います。JSON出力の解析やストリーミングイベントの活用など、出力を別のツールに渡す踏み込んだ内容はClaude Codeの構造化出力とストリーミングをツールに組み込むで扱っています。

前提条件

-pが提供する土台は、Claude Codeの内部で使われているAgent SDKと同じです。同じツール群・同じエージェントループ・同じ文脈管理をターミナルから薄く叩けるようにしたのが-pだと捉えると、後述する各フラグの挙動が理解しやすくなります。Python・TypeScriptで型付きに組みたい場合は、CLIの-pではなくAgent SDKパッケージを直接使う選択肢もあります。

-pは通常のclaude CLIオプションとして提供され、--allowedToolsや--output-formatなど他のCLIオプションと組み合わせます。ただし全部のオプションが-pと組み合わせられるわけではありません。--bg(バックグラウンドセッション起動)と同時指定すると、Claude Codeは競合を明示するエラーで止まります。

-pセッションの既定の権限モードは、プランに関わらず常にManual(default)です。対話セッションではPro・Max・Teamプランでauto modeが既定になりますが、-pではこの既定は適用されません。ツールを自動承認するには、後述の--allowedToolsや--permission-modeを明示します。

基本の実行方法

もっとも単純な形は、プロンプトを引数で渡す方法です。

claude -p "このプロジェクトが何をするか説明して"

標準入力からのパイプ渡しにも対応します。ビルドログをそのままClaude Codeに読ませて説明させる例です。

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

パイプで渡す標準入力は10MBが上限です。超えるとエラーで終了するので、大きな入力はファイルに書き出し、プロンプト側でパスを参照させます。

claudeは成功時に終了コード0、失敗時に0以外のコードで終わります。スクリプト側は終了コードで分岐できます。無効なフラグを渡すと、実行が始まる前に標準エラー出力へエラーが出ます。認証切れのような実行中の失敗は、結果として標準出力に書き出されます。

bareモードで起動を高速化する

--bareを付けると、hooks・Skills・plugins・MCPサーバー・自動メモリー・CLAUDE.mdの自動検出をすべて省略し、起動を速くします。付けない場合、-pセッションは対話セッションと同じ文脈(作業ディレクトリやホームディレクトリの設定を含む)を読み込みます。

CIやスクリプトでは--bareが推奨です。マシンが変わっても同じ結果になることが重要な場面で効きます。

claude --bare -p "README.mdを要約して" --allowedTools "Read"

--bareを付けない-pセッションは、信頼していないフォルダーでも確認ダイアログなしでプロジェクトの.claude/settings.jsonのhooksを実行し、.mcp.jsonのMCPサーバーにも接続します。対話セッションのような承認画面が出せないためです。第三者のリポジトリを扱うスクリプトでは、この挙動を避ける意味でも--bareが安全側です。

--bareではOAuthの認証情報やシステムのキーチェーンを読みません。Anthropic APIを使うならANTHROPIC_API_KEYを環境変数で渡します。

ツールの自動承認 — 使い分け

-pセッションは既定でManualモードなので、そのままではファイル編集やBashコマンドのたびに止まってしまいます(対話画面がないため実質的に失敗します)。自動承認の設定方法は用途によって向き不向きが分かれます。

CIでテストを実行して失敗を直す例です。

claude -p "テストスイートを実行して失敗を直して" \
  --allowedTools "Bash,Read,Edit"

ロックダウンしたCIではdontAskが安全側です。許可ルールにないものはすべて拒否されるので、想定外のコマンド実行を防げます。

claude -p "npm testを実行して" \
  --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

権限モードの設計思想やサンドボックスとの関係はAIコーディングエージェント権限モデル比較で掘り下げています。

スクリプトに組み込む実例

-pはLinterやレビューアとしてビルドスクリプトへ組み込めます。package.jsonのスクリプトからmainブランチとの差分を渡し、typoを報告させる例です。

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"あなたはtypoリンターです。このdiffの各typoについてfilename:lineを1行、次の行に問題点を書いて。それ以外は何も返さないで\""
  }
}

差分をパイプで渡しているため、Claude Codeにdiffを読むためのBash権限は不要です。エスケープした二重引用符はWindowsでも動くようにしています。1件ずつでなく数百〜数千ファイルへ同じ変更を機械的に適用したい場合は、-pをシェルのforループで回す方法があります。--allowedToolsによる権限の絞り込みやリトライ設計はClaude Codeをシェルループで回して複数ファイルを一括変更するにまとめています。

ステージした変更からコミットメッセージを組み立てる例です。

claude -p "ステージした変更を見て適切なコミットを作成して" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

--allowedToolsの値は末尾の *で前方一致になります。半角スペースを*の前に入れないとgit diff*はgit diff-indexのようなコマンドにも一致してしまうので、スペースを忘れずに入れます。

会話を続けたいときは--continue(直近の会話を継続)か--resume(セッションIDを指定して継続)を使います。

claude -p "このコードベースをパフォーマンス面でレビューして"
claude -p "次はデータベースのクエリに絞って" --continue
claude -p "見つかった問題の要約を作って" --continue

GitHub Actions・GitLab CI/CDへの具体的な組み込み手順は、それぞれClaude CodeをGitHub Actionsに組み込む、Claude CodeをGitLab CI/CDに組み込むにまとめています。どちらもホスト型のCI環境向けで、自前のcronジョブやpre-commitフックのようにホストを自分で管理する場合は、本記事のコマンド例をそのまま使えます。

Skills・スラッシュコマンド・システムプロンプトの扱い

対話セッションで使うSkillsやカスタムコマンドは、-pモードでもそのまま動きます。プロンプト文字列に/skill-nameを含めれば、実行前にClaude Codeが展開します。ただし/loginのようにターミナルの対話画面が前提の組み込みコマンドは、-pモードでは使えません。

gh pr diff "$1" | claude -p \
  --append-system-prompt "あなたはセキュリティエンジニアです。脆弱性の観点でレビューして" \
  --output-format json

--append-system-promptは、Claude Codeの既定のシステムプロンプトを保ったまま指示を追加します。上の例はPRの差分をパイプで渡し、レビュー役を指定してJSON形式で結果を受け取るスクリプトです。"$1"にはシェルがコマンドライン引数を代入するので、bash review.sh 123のように実行すればPR番号123の差分をレビューできます。既定のプロンプトごと入れ替えたい場合は--system-promptを使いますが、Claude Codeの標準ふるまいまで失われる点に注意します。

バックグラウンドタスクと5秒の猶予

-p実行中にBashツールでdevサーバーやウォッチビルドのようなバックグラウンドタスクを起動すると、そのシェルはClaude Codeが最終結果を返してから約5秒後に終了します。結果直後に出力を出すタスクのための猶予です。

バックグラウンドのサブエージェントやワークフローはこの5秒の対象外です。結果自体が最終出力の一部になるため、完了までClaude Codeが待ちます。この待ち時間は既定で最大10分にキャップされ、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS環境変数で調整できます。0を指定すると無制限に待ちます。

--bgフラグで起動するバックグラウンドセッション(claude agentsで後からアタッチする方式)とは別物です。--bgと-pを同時に指定するとエラーになる仕様と、それぞれの使い分けは--bgと--printの競合エラーの解決法で扱っています。

よくあるつまずき

プロンプトを渡し忘れてエラーになる: claude -p単体で引数も標準入力もないとError: Input must be provided either through stdin or as a prompt argument when using --printで止まります。プロンプトを引数で渡すか、パイプで標準入力に流し込みます。

CIでログイン画面が出せず失敗する: -pは対話でのサインインができません。保存済みのOAuthログインが切れているとFailed to authenticate: OAuth session expired and could not be refreshedという構造化エラーになります。CIでは対話ログインに頼らず、ANTHROPIC_API_KEYかclaude setup-tokenで発行した長期トークンを使います。

空白だけのプロンプトを送ってしまう: スペースや改行だけのプロンプトは、API側が拒否する前にClaude Code側で弾かれます。動的にプロンプトを組み立てるスクリプトでは、空文字列チェックを入れておくと無駄なエラーを避けられます。

ANTHROPIC_API_KEYが意図せずサブスクリプションを上書きする: 環境変数は/loginのサブスクリプションより優先されます。シェルの設定ファイルに残ったままのANTHROPIC_API_KEYが、Pro・Maxプランのはずの実行にAPI課金として乗ってしまうことがあります。

まとめ

claude -pは、対話UIを介さずにClaude Codeを実行するもっとも手軽な手段です。CIやスクリプトに組み込むときは--bareで起動を安定させ、--allowedToolsか--permission-modeでツールを自動承認し、終了コードで成否を判定します。バックグラウンドタスクの扱いや会話の継続方法も対話セッションとは勝手が違うので、組み込む前に一通り把握しておくと想定外の待ちや失敗を避けられます。