スポンサーリンク

headlessモードとは：対話なしでClaude Codeを動かす

claudeコマンドに-p（--print）を付けると、対話画面を開かずに一度きりの指示を実行して結果を返すheadlessモードになります。標準入力・標準出力を扱う一般的なCLIツールと同じように、パイプやリダイレクトと組み合わせられます。

# 基本形
claude -p "このプロジェクトの認証まわりの実装を要約して"

# 標準入力を渡す
cat build-error.txt | claude -p "このビルドエラーの原因を簡潔に説明して" > output.txt

cronやCI、自作スクリプトから呼び出す用途にはこのheadlessモードを使います。

定期実行の前に：–bareモードを使う

-pだけだと、対話セッションと同じくフックやMCPサーバー、CLAUDE.mdなどのプロジェクト設定を自動で読み込みます。これは定期実行では罠になりがちです。誰かが後から追加したフックや、たまたまローカルに設定されたMCPサーバーが、cronジョブの動作を予期せず変えてしまうことがあります。

claude --bare -p "このファイルを要約して" --allowedTools "Read"

--bareを付けると、フック・スキル・プラグイン・MCPサーバー・自動メモリ・CLAUDE.mdの自動読み込みをすべてスキップし、渡したフラグだけで動く再現性の高い実行になります。公式ドキュメントも「CI・スクリプト用途には--bareを推奨」としており、将来的には-pのデフォルト挙動になる予定です。

権限設計：定期実行では dontAsk が基本

cronジョブは誰も画面を見ていない状態で動くため、確認プロンプトが出ても誰も答えられません。権限モードはdontAskを基本にするのが安全です（他のモードとの違いは権限モード完全ガイドで解説しています）。

claude --bare -p "テストを実行して失敗があれば修正して" \
  --permission-mode dontAsk \
  --allowedTools "Bash(npm test),Read,Edit"

dontAskモードでは、--allowedToolsやpermissions.allowルールに一致しない操作は確認ではなく自動拒否されます。セッションが入力待ちで止まったまま次のcron実行とかち合う、という事故を防げます。

実践：ログを分析してSlackに日次レポート

構造化出力（--output-format json）を使うと、結果をスクリプトで扱いやすくなり、コストの追跡も同時にできます。

#!/usr/bin/env bash
set -euo pipefail

RESULT=$(claude --bare -p "今日のアプリケーションログ（/var/log/app.log）を分析し、
エラー件数・主な原因・対応が必要な項目を3行以内で要約して" \
  --allowedTools "Read" \
  --output-format json)

SUMMARY=$(echo "$RESULT" | jq -r '.result')
COST=$(echo "$RESULT" | jq -r '.total_cost_usd')

curl -X POST -H 'Content-type: application/json' \
  --data "{\"text\":\"📋 今日のログサマリー\n${SUMMARY}\n(cost: \$${COST})\"}" \
  "$SLACK_WEBHOOK_URL"

--output-format jsonのレスポンスにはresult（本文）に加えてtotal_cost_usd（実行コスト）が含まれるため、実行のたびにコストをログへ残す運用が簡単にできます。日々の定期実行が積み重なるとコストも積み重なるので、この可視化は早い段階でやっておくべきです。

JSON Schemaで出力形式を固定する

Slack投稿やDB保存など、後続処理が特定のフィールドを期待する場合は--json-schemaで出力を強制できます。

claude --bare -p "今日のエラーログから、エラーメッセージの配列を抽出して" \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}},"required":["errors"]}' \
  | jq '.structured_output'

cron・launchdへの登録

Linux・Mac共通：crontab

# crontab -e で編集
# 毎朝9時に実行し、ログをファイルに残す
0 9 * * * /usr/local/bin/claude-daily-report.sh >> /var/log/claude-cron.log 2>&1

Macでより確実に動かす：launchd

Macでは、スリープ復帰後の実行漏れに強いlaunchdもおすすめです。

<!-- ~/Library/LaunchAgents/com.example.claude-daily.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.claude-daily</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/claude-daily-report.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>9</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.example.claude-daily.plist

Macを定期実行のホストにする場合、スリープしていると当然ジョブも実行されません。蓋を閉じたまま動かし続ける設定はこちらのスリープ対策ガイドを参照してください。

エラーハンドリングとタイムアウト

無人実行では、失敗を検知して次のアクションにつなげる仕組みが欠かせません。

# タイムアウト付き実行 + 終了コードでの分岐
if ! timeout 300 claude --bare -p "$PROMPT" --allowedTools "Read,Bash(npm test)" > result.json; then
  echo "Claude Codeの実行が失敗またはタイムアウトしました" | \
    curl -X POST -d @- "$SLACK_WEBHOOK_URL"
  exit 1
fi

会話を継続する定期実行（差分レポートなど）

「昨日の続きから今日の分だけ確認する」といった継続的なタスクには、--continueや--resumeが使えます。

# セッションIDを記録しながら実行
SESSION_ID=$(claude -p "今週のPRレビューを開始" --output-format json | jq -r '.session_id')
echo "$SESSION_ID" > /var/tmp/claude-weekly-session.txt

# 翌日、同じセッションを継続
claude -p "昨日の続きから、新しく増えたPRだけレビューして" \
  --resume "$(cat /var/tmp/claude-weekly-session.txt)"

セッションIDの検索範囲はカレントディレクトリ（とそのgit worktree）に紐づくため、cronジョブは常に同じディレクトリから実行するようにしてください。

よくある質問

まとめ

まずは1つ、リスクの低い「要約して通知するだけ」のジョブから試してみてください。--bareとdontAskを基本形にしておけば、範囲が広がっても安全に運用しやすくなります。