claude-headless-mode

Claude ヘッドレスモード

スクリプト、CI、自動化で非対話的に実行するには、claude -p（または --print）を使用します。

基本的な使い方

# Simple prompt
claude -p "Summarize this repo"

# With file input
claude -p "Review this code" < file.py

# Pipe output
claude -p "List all functions" | grep "def "

出力形式

形式	フラグ	使用例
テキスト	--output-format text	人間が読みやすい形式（デフォルト）
JSON	--output-format json	単一の JSON 結果
ストリーム JSON	--output-format stream-json --verbose	リアルタイムストリーミング

テキスト出力（デフォルト）

claude -p "What is 2+2?"
# Output: 4

JSON 出力

claude -p "What is 2+2?" --output-format json

メタデータを含むラッパーを返します：

{
  "type": "result",
  "subtype": "success",
  "result": "4",
  "duration_ms": 1234,
  "total_cost_usd": 0.01,
  "session_id": "...",
  "structured_output": null
}

結果のみを抽出します：

claude -p "What is 2+2?" --output-format json | jq -r '.result'

ストリーム JSON 出力

claude -p "Long analysis" --output-format stream-json --verbose

• 実行の進行に応じて、改行区切りの JSON をストリーミングします
• ツール呼び出し、メッセージ、進捗をリアルタイムで表示します
• 最終行に結果が含まれます
• --verbose フラグが必要です

最終結果を抽出します：

claude -p "Analyze code" --output-format stream-json --verbose \
  | tee /dev/stderr \
  | tail -1 \
  | jq -r '.result'

JSON Schema による構造化出力

特定のスキーマに一致するデータを Claude に返させます：

claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "functions": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["functions"]
  }'

結果は structured_output フィールドに表示されます：

{
  "result": "...",
  "structured_output": {
    "functions": ["login", "logout", "verify_token"]
  }
}

スキーマの例

シンプルなオブジェクト：

{
  "type": "object",
  "properties": {
    "answer": { "type": "integer" }
  },
  "required": ["answer"]
}

タスクの結果（成功／失敗）：

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["success", "failure"] },
    "summary": { "type": "string" },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "error_category": { "type": "string" },
    "suggestion": { "type": "string" }
  },
  "required": ["status", "summary"]
}

スキーマ結果から抽出：

OUTPUT=$(claude -p "$PROMPT" --output-format json --json-schema "$SCHEMA")
STATUS=$(echo "$OUTPUT" | jq -r '.structured_output.status')
SUMMARY=$(echo "$OUTPUT" | jq -r '.structured_output.summary')

よく使うオプション

オプション	説明
-p, --print	ヘッドレスモード（必須）
--output-format	text、json、stream-json
--json-schema	出力スキーマを強制
--verbose	stream-json で必須
--model	モデルを選択（sonnet、opus、haiku）
--max-turns	エージェントによるターン数を制限
--permission-mode	bypassPermissions、plan など
--allowedTools	使用可能なツールを制限

権限モード

# Skip all permission prompts (trusted environments only)
claude -p "Fix all linting errors" --permission-mode bypassPermissions

# Plan mode (read-only exploration)
claude -p "Analyze architecture" --permission-mode plan

例

CI/CD との連携

# Run tests and get structured result
RESULT=$(claude -p "Run tests and report results" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"passed":{"type":"boolean"},"failures":{"type":"array","items":{"type":"string"}}},"required":["passed"]}')

if [ "$(echo $RESULT | jq '.structured_output.passed')" = "true" ]; then
  echo "Tests passed"
else
  echo "Tests failed"
  exit 1
fi

バッチ処理

for file in src/*.py; do
  claude -p "Review $file for security issues" \
    --output-format json \
    --json-schema '{"type":"object","properties":{"issues":{"type":"array"}},"required":["issues"]}' \
    | jq ".structured_output.issues"
done

新しいコンテキストでのタスク実行

# Each invocation is independent (no conversation history)
claude -p "Task 1: Create migration" --output-format json
claude -p "Task 2: Add model" --output-format json
claude -p "Task 3: Write tests" --output-format json

タスクの調整

CLAUDE_CODE_TASK_LIST_ID を使用して、ヘッドレス実行間で TaskList を共有します。

環境変数

# All invocations share the same TaskList
export CLAUDE_CODE_TASK_LIST_ID="my-project"
claude -p "Use TaskCreate to add: Setup database"
claude -p "Use TaskCreate to add: Write migrations"
claude -p "Use TaskList to show all tasks"  # Shows both tasks

パターン：オーケストレーター＋ワーカー

TASK_LIST_ID="epic-$(date +%Y%m%d)"
export CLAUDE_CODE_TASK_LIST_ID="$TASK_LIST_ID"

# Orchestrator creates tasks
claude -p "Use TaskCreate for each: Task 1, Task 2, Task 3"

# Workers execute (each sees shared TaskList)
for task_id in 1 2 3; do
  claude -p "Use TaskUpdate to mark task #$task_id as in_progress, implement it, then mark completed"
done

# Check final state
claude -p "Use TaskList to show status"

タスクツール

ツール	目的
TaskCreate	件名と説明を指定して新しいタスクを作成
TaskList	ステータスとともにすべてのタスクを一覧表示
TaskUpdate	タスクのステータス（in_progress、completed）を更新、または blockedBy を追加
TaskGet	特定のタスクの詳細をすべて取得

依存関係

# Task 2 depends on Task 1
claude -p "Use TaskUpdate on task #2 to set blockedBy: [1]"

タスクは ~/.claude/tasks/ に保存され、セッションを再起動しても維持されます。

注意事項

• -p を実行するたびに新しいコンテキストが開始されます（前回の実行のコンテキストは引き継がれません）
• プログラムで解析するには --output-format json を使用します
• structured_output フィールドにはスキーマ検証済みのデータが含まれます
• result フィールドには未加工のテキスト応答が含まれます
• ストリーム JSON には --verbose フラグが必要です
• JSON 出力でコスト情報を確認できます：total_cost_usd