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

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

# 基本形\nclaude -p "このプロジェクトの認証まわりの実装を要約して"\n\n# 標準入力を渡す\ncat 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 "テストを実行して失敗があれば修正して" \\\n  --permission-mode dontAsk \\\n  --allowedTools "Bash(npm test),Read,Edit"

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

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

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

#!/usr/bin/env bash\nset -euo pipefail\n\nRESULT=$(claude --bare -p "今日のアプリケーションログ（/var/log/app.log）を分析し、\nエラー件数・主な原因・対応が必要な項目を3行以内で要約して" \\\n  --allowedTools "Read" \\\n  --output-format json)\n\nSUMMARY=$(echo "$RESULT" | jq -r '.result')\nCOST=$(echo "$RESULT" | jq -r '.total_cost_usd')\n\ncurl -X POST -H 'Content-type: application/json' \\\n  --data "{\\"text\\":\\"📋 今日のログサマリー\\n${SUMMARY}\\n(cost: \\$${COST})\\"}" \\\n  "$SLACK_WEBHOOK_URL"

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

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

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

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

cron・launchdへの登録

Linux・Mac共通：crontab

# crontab -e で編集\n# 毎朝9時に実行し、ログをファイルに残す\n0 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 -->\n<?xml version="1.0" encoding="UTF-8"?>\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>com.example.claude-daily</string>\n  <key>ProgramArguments</key>\n  <array>\n    <string>/usr/local/bin/claude-daily-report.sh</string>\n  </array>\n  <key>StartCalendarInterval</key>\n  <dict>\n    <key>Hour</key><integer>9</integer>\n    <key>Minute</key><integer>0</integer>\n  </dict>\n</dict>\n</plist>

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

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

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

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

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

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

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

# セッションIDを記録しながら実行\nSESSION_ID=$(claude -p "今週のPRレビューを開始" --output-format json | jq -r '.session_id')\necho "$SESSION_ID" > /var/tmp/claude-weekly-session.txt\n\n# 翌日、同じセッションを継続\nclaude -p "昨日の続きから、新しく増えたPRだけレビューして" \\\n  --resume "$(cat /var/tmp/claude-weekly-session.txt)"

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

よくある質問

まとめ

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