Claude Codeは対話ターミナルの顔が有名ですが、-p フラグを1つ付けるだけで「プロンプトを渡すと結果を標準出力に返して終了する、ただのCLIコマンド」になります。これがヘッドレスモードです。grepやjqと同じ列に並べてパイプで繋げる。CIやcronから呼べる。ここまでは1分で試せます。
ただし本題はその先です。対話モードでは「危ない操作の前に人間へ確認する」ことが安全装置として機能しますが、ヘッドレスには確認に答える人間がいません。だからヘッドレス化の実作業は、コマンドを覚えることではなく、許可するツール・権限モード・ターン数の上限を、実行前にすべて決め切ることになります。この記事は、基本の使い方から、その「先に決め切る」設計までを一次情報ベースで整理します。
想定読者は、Claude Codeを対話で使っていて「これを定時実行やCIに組み込みたい」と考え始めた人。コマンドと仕様は執筆時点のClaude Code公式CLIリファレンスとヘッドレスモードのドキュメントを正としています。フラグの追加・変更は頻繁にあるので、組み込む前に最新の公式を確認してください。
ヘッドレスモードの基本: claude -p
-p（--print）を付けると、Claude Codeは対話UIを起動せず、プロンプトを処理して結果を出力し、終了します。
# 最小の形
claude -p "このリポジトリのTODOコメントを洗い出して一覧にして"
# 標準入力も渡せる。ログ解析などはこの形が便利
cat error.log | claude -p "このログから障害の根本原因を推定して"
ポイントは、ヘッドレスでも中身は同じエージェントだということです。単発のテキスト生成ではなく、ファイルを読み、コマンドを実行し、複数ターンの試行錯誤をしてから答えを返します。「1回のAPI呼び出し」ではなく「1回のエージェント実行」を起動している、と捉えるのが正確です。
セッションの継続も対話モードと同じ仕組みで使えます。直前のセッションを続けるなら --continue、特定のセッションIDに戻るなら --resume です。バッチ処理を段階に分けて、前段の文脈を引き継いで後段を実行する、といった構成が組めます。
出力をプログラムで受ける: --output-format json
自動化に組み込むなら、出力はテキストのままでは扱いにくい。--output-format json を付けると、最終結果がメタデータ付きの構造化データで返ります。
claude -p "変更されたファイルの要約を作って" --output-format json
返ってくるJSONには、結果本文のほかに、エラーかどうかのフラグ、消費ターン数、コスト、セッションIDといった実行のメタデータが含まれます（フィールドの正確な構成は前掲のCLIリファレンスを正としてください）。自動化の観点で価値が大きいのは次の3つです。
- エラーフラグ: 後続処理を進めてよいかを機械判定できる
- コストとターン数: 実行ごとの費用を記録し、異常な実行を検知できる
- セッションID: 失敗時の調査や
--resumeでの再開に使える
シェルからの扱いは、jqと組み合わせるのが定番です。
out=$(claude -p "変更されたファイルの要約を作って" --output-format json)
# エラーなら後続を止める
if [ "$(echo "$out" | jq -r '.is_error')" = "true" ]; then
echo "claude job failed" >&2
exit 1
fi
# 結果本文とコストを取り出す
echo "$out" | jq -r '.result' > summary.md
echo "$out" | jq -r '.total_cost_usd' >> cost.log
もうひとつ、出力の「形」を安定させたいときは --append-system-prompt が使えます。既定のシステムプロンプトを保ったまま指示を追記できるので、「出力はMarkdownの表のみ。前置きを書かない」のような出力契約をプロンプト本文と分離して固定できます。ワンショットの指示より、パイプラインの部品としての再現性が上がります。
さらに --output-format stream-json にすると、実行中のイベントが逐次JSON Linesで流れてきます。長時間のバッチで進行をログに残したい場合や、途中経過を監視したい場合はこちらです。逆に、シェルスクリプトで結果文字列だけ欲しいなら既定のテキスト出力で十分。「後で読むのは人間かプログラムか」で選べば迷いません。
権限を先に決め切る: --allowedTools と権限モード
ここからがヘッドレス設計の本体です。対話モードのClaude Codeは、ファイル書き込みやBash実行の前に確認を求めてきます。ヘッドレスでは、この確認に答える人がいません。確認が必要な操作に出会うと、実行はそこで進めなくなります。
つまり対話とヘッドレスでは、権限の考え方が反転します。**対話は「その場で聞かれて答える」、ヘッドレスは「先に列挙して渡す」。**先に渡す手段が --allowedTools です。
# 読み取り系だけを許可した調査ジョブ
claude -p "依存パッケージの更新可否を調査して" \
--allowedTools "Read" "Grep" "Glob" "Bash(npm outdated:*)"
# 書き込みまで許可するなら、対象を絞って明示する
claude -p "CHANGELOGの下書きを更新して" \
--allowedTools "Read" "Edit" "Bash(git log:*)"
Bash(npm outdated:*) のように、Bashはコマンド単位のパターンで絞れます。ジョブの目的に必要な最小集合だけを列挙するのが原則です。「とりあえず全部許可」の誘惑には --dangerously-skip-permissions という専用フラグが用意されていますが、名前が警告しているとおり、エージェントの判断ミスや、読み込んだ外部テキストに紛れた指示がそのまま実行に繋がる構成です。使うなら、壊れてよい隔離環境（コンテナなど）に限定すべきです。
もうひとつの軸が --permission-mode です。たとえば plan を指定すると、エージェントは計画の提案までで止まり、実行はしません。「変更案だけを毎朝生成させて、適用は人間が対話モードで行う」という半自動の構成は、書き込み権限を渡し切る前の中間段階として実用的です。
このあたりの権限レイヤーの全体像は、別記事で詳しく書いています。
Claude Codeの権限設定4層ガイド｜denyを厚くするだけでは守れないClaude Codeの権限設定を「渡さない・許す・止める・外側で強制」の4層で設計する方法を解説します。allowルールのワイルドカード警告や--restrictedフラグなど直近の公式アップデートを根拠に、hooksによる禁止だけでは塞げない穴と、各層の使い分けを実運用の構成で整理します。www.tentspace.net
暴走と費用に上限を掛ける: --max-turns
権限と並ぶもうひとつの上限が、実行量です。エージェントは試行錯誤するので、うまくいかないタスクでは想定よりターン数が伸びることがあります。人間が見ていれば途中で止めますが、ヘッドレスでは誰も見ていません。
--max-turnsでエージェントのターン数に上限を設ける- 呼び出し側（cronやCI）でジョブ全体のタイムアウトを掛ける
--output-format jsonで返るコストを毎回記録し、平常値から外れた実行を通知する
この3点をセットにしておくと、「気づいたら夜通し回っていた」類の事故を構造的に防げます。定時実行のコストはプロンプトキャッシュの効き方でも大きく変わるので、費用の観測と設計はこちらの記事も参考になるはずです。
Claude Codeのプロンプトキャッシュ入門｜エージェント運用のコストを観測して設計するClaude Codeを定時実行で運用するときのAPIコストを左右するプロンプトキャッシュの仕組みを解説します。キャッシュが静かに切れる箇所、2026年8月末に追加された/costのキャッシュ行やエージェント別cacheTtlなどの観測・制御手段、日次運用での設計判断をまとめます。www.tentspace.net
実戦形: cronに載せる最小構成
ここまでの部品を1本に組むと、cronジョブの雛形はこうなります。読み取り専用の日次調査ジョブの例です。
#!/usr/bin/env bash
set -euo pipefail
cd /path/to/repo
out=$(timeout 900 claude -p "昨日のコミットを読んで、ドキュメント更新が必要な箇所を列挙して" \
--allowedTools "Read" "Grep" "Glob" "Bash(git log:*)" "Bash(git diff:*)" \
--max-turns 20 \
--append-system-prompt "出力はMarkdownの箇条書きのみ。前置きと結びを書かない" \
--output-format json)
if [ "$(echo "$out" | jq -r '.is_error')" = "true" ]; then
notify "daily-doc-check failed: $(echo "$out" | jq -r '.result' | head -c 200)"
exit 1
fi
echo "$out" | jq -r '.result' > /var/log/doc-check/$(date +%F).md
echo "$(date +%F) $(echo "$out" | jq -r '.total_cost_usd')" >> /var/log/doc-check/cost.log
構成要素はここまでに出たものだけです。timeout でジョブ全体の上限、--allowedTools は読み取り系とgitの参照コマンドだけ、--max-turns でエージェントの試行回数を制限、出力契約は --append-system-prompt に分離、結果とコストはJSONから機械的に取り出して記録。失敗時は結果の先頭だけ通知して人間の調査に回します。
注意点をひとつ。ヘッドレスジョブが読むデータ（ログ、Issue本文、外部から来たテキスト）には、指示のように見える文字列が紛れ込むことがあります。エージェントは読んだテキストに影響され得るので、外部入力を扱うジョブほど、--allowedTools の最小化と書き込み権限を渡さない構成が効いてきます。権限設計は「行儀の問題」ではなく「外部入力への防御」でもある、と捉えておくのが安全です。
どこに組み込むか——向く仕事と向かない仕事
ヘッドレスが向くのは、入力と成功条件が定義できて、失敗してもリトライか破棄で済む仕事です。
- CI: PRの差分要約、規約チェックの一次レビュー、テスト失敗ログの原因候補出し
- cron: 日次のログ解析、依存更新の調査レポート、ドキュメントと実装の乖離チェック
- パイプラインの1段: 非構造化テキスト（問い合わせ、ログ、議事録）を構造化して次のツールへ渡す
逆に向かないのは、成功条件が曖昧で、結果の良し悪しを人間の目でしか判定できない仕事です。たとえば「リファクタリングして良くしておいて」をヘッドレスの書き込み権限付きで無人実行するのは、レビューの負債を自動生成する構成になりがちです。判断基準として使えるのは、「機械的に検証できる合格条件（テスト、lint、スキーマ検証）」が用意できるかどうか。書き込みを伴うヘッドレスジョブは合格条件とセットのときだけ、合格条件が書けないタスクは plan 止まりにするか対話モードに残す。この線引きを先に決めておくと、ヘッドレス化の判断で迷う場面がかなり減ります。
なお、GitHub上での自動実行にはClaude Code公式のGitHub Actions統合が別途あります。CIでの利用が主目的なら、素の claude -p を自前で組む前にこちらを確認する方が早いです。
まとめ
ヘッドレスモードの入口は claude -p の1フラグですが、実体は「人間の確認という安全装置を外した状態で、同じエージェントを走らせる」実行形態です。だから設計の中心はプロンプトではなく上限になります。ツールは --allowedTools で最小列挙、実行量は --max-turns とタイムアウト、結果は --output-format json で機械判定、書き込みを渡すなら機械的な合格条件とセット。ここまで決めて初めて、grepの隣に並べられる部品になります。
まずは読み取り専用の調査ジョブから始めるのがおすすめです。権限を絞ったヘッドレス実行を1本動かしてみると、「先に決め切る」感覚の輪郭がつかめるはずです。