🛠️ 開発・MCP コミュニティ

Claude Codeヘッドレス実行

claude-code-headless

対話型UIを介さずにClaude Codeプログラムを自動実行し、CLI自動化やCI/CD環境でのスクリプト処理を可能にするためのSkill。

📜 元の英語説明(参考)

Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.

🇯🇵 日本人クリエイター向け解説

一言でいうと

対話型UIを介さずにClaude Codeプログラムを自動実行し、CLI自動化やCI/CD環境でのスクリプト処理を可能にするためのSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⚡ おすすめ: コマンド1行でインストール(60秒)

下記のコマンドをコピーしてターミナル(Mac/Linux)または PowerShell(Windows)に貼り付けてください。ダウンロード → 解凍 → 配置まで全自動。

🍎 Mac / 🐧 Linux

mkdir -p ~/.claude/skills && cd ~/.claude/skills && curl -L -o claude-code-headless.zip https://jpskill.com/download/5903.zip && unzip -o claude-code-headless.zip && rm claude-code-headless.zip

🪟 Windows (PowerShell)

$d = "$env:USERPROFILE\.claude\skills"; ni -Force -ItemType Directory $d | Out-Null; iwr https://jpskill.com/download/5903.zip -OutFile "$d\claude-code-headless.zip"; Expand-Archive "$d\claude-code-headless.zip" -DestinationPath $d -Force; ri "$d\claude-code-headless.zip"

完了後、Claude Code を再起動 → 普通に「動画プロンプト作って」のように話しかけるだけで自動発動します。

💾 手動でダウンロードしたい(コマンドが難しい人向け)

1. 下の青いボタンを押して claude-code-headless.zip をダウンロード
2. ZIPファイルをダブルクリックで解凍 → claude-code-headless フォルダができる
3. そのフォルダを C:\Users\あなたの名前\.claude\skills\(Win)または ~/.claude/skills/(Mac)へ移動
4. Claude Code を再起動

⬇ .zip でダウンロード(推奨) ⬇ .skill 形式(上級者用) 元のソース ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
- · macOS / Linux: ~/.claude/skills/
- · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →

最終更新: 2026-05-17
取得日時: 2026-05-18
同梱ファイル: 1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

Claude Code ヘッドレスモード

対話型UIなしでスクリプトから Claude Code を実行します。

クイックスタート

# Basic headless execution
claude -p "Explain this code" --allowedTools "Read,Grep"

# JSON output for parsing
claude -p "List files" --output-format json

# Continue conversation
claude -p "Start analysis" --output-format json > result.json
session=$(jq -r '.session_id' result.json)
claude --resume "$session" "Now fix the issues"

必須のCLIオプション

フラグ	説明
`-p`, `--print`	非対話型（ヘッドレス）モード
`--output-format`	text, json, stream-json
`-r`, `--resume`	セッションIDで再開
`-c`, `--continue`	最新のセッションを続行
`--allowedTools`	許可するツールのカンマ区切りリスト
`--disallowedTools`	拒否するツールのカンマ区切りリスト
`--mcp-config`	MCPサーバー設定JSONへのパス
`--verbose`	詳細ログを有効にする
`--append-system-prompt`	システムプロンプトに追加する

権限モード

モード	フラグ	効果
デフォルト	(なし)	権限をプロンプトで確認
編集を承認	`--permission-mode acceptEdits`	ファイルの変更を自動承認
バイパス	`--permission-mode bypassPermissions`	すべてのプロンプトをスキップ

出力フォーマット

テキスト (デフォルト)

claude -p "Hello"
# Outputs: Human-readable response

JSON

claude -p "Hello" --output-format json

{
  "type": "result",
  "subtype": "success",
  "result": "Hello! How can I help?",
  "session_id": "abc123",
  "total_cost_usd": 0.001,
  "duration_ms": 1234,
  "num_turns": 1
}

ストリームJSON

claude -p "Hello" --output-format stream-json
# Real-time JSONL output for each message

一般的なパターン

ツール制限付きスクリプト

claude -p "Analyze the codebase" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Write,Edit,Bash"

CI/CD統合

claude -p "Review this PR diff" \
  --permission-mode acceptEdits \
  --output-format json \
  --append-system-prompt "Focus on security issues"

複数ターンの自動化

session=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude --resume "$session" "Continue with step 2"
claude --resume "$session" "Finalize and report"

エラー処理

result=$(claude -p "Task" --output-format json)
if [[ $(echo "$result" | jq -r '.is_error') == "true' ]]; then
    echo "Error: $(echo "$result" | jq -r '.result')" >&2
    exit 1
fi

公式ドキュメント

https://code.claude.com/docs/en/headless - ヘッドレスモードのリファレンス
https://code.claude.com/docs/en/settings - 設定と権限

その他のリソース

./references/cli-options.md - 完全なCLIフラグのリファレンス
./references/output-formats.md - 出力フォーマットのスキーマ
./references/integration-patterns.md - CI/CDとスクリプトの例

参照: 自動化イベントについては claude-code-hooks、トラブルシューティングについては claude-code-debug を参照してください。

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

Claude Code Headless Mode

Run Claude Code from scripts without interactive UI.

Quick Start

# Basic headless execution
claude -p "Explain this code" --allowedTools "Read,Grep"

# JSON output for parsing
claude -p "List files" --output-format json

# Continue conversation
claude -p "Start analysis" --output-format json > result.json
session=$(jq -r '.session_id' result.json)
claude --resume "$session" "Now fix the issues"

Essential CLI Options

Flag	Description
`-p`, `--print`	Non-interactive (headless) mode
`--output-format`	text, json, stream-json
`-r`, `--resume`	Resume by session ID
`-c`, `--continue`	Continue most recent session
`--allowedTools`	Comma-separated allowed tools
`--disallowedTools`	Comma-separated denied tools
`--mcp-config`	Path to MCP server config JSON
`--verbose`	Enable verbose logging
`--append-system-prompt`	Add to system prompt

Permission Modes

Mode	Flag	Effect
Default	(none)	Prompt for permissions
Accept edits	`--permission-mode acceptEdits`	Auto-accept file changes
Bypass	`--permission-mode bypassPermissions`	Skip all prompts

Output Formats

Text (default)

claude -p "Hello"
# Outputs: Human-readable response

JSON

claude -p "Hello" --output-format json

{
  "type": "result",
  "subtype": "success",
  "result": "Hello! How can I help?",
  "session_id": "abc123",
  "total_cost_usd": 0.001,
  "duration_ms": 1234,
  "num_turns": 1
}

Stream-JSON

claude -p "Hello" --output-format stream-json
# Real-time JSONL output for each message

Common Patterns

Script with tool restrictions

claude -p "Analyze the codebase" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Write,Edit,Bash"

CI/CD integration

claude -p "Review this PR diff" \
  --permission-mode acceptEdits \
  --output-format json \
  --append-system-prompt "Focus on security issues"

Multi-turn automation

session=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude --resume "$session" "Continue with step 2"
claude --resume "$session" "Finalize and report"

Error Handling

result=$(claude -p "Task" --output-format json)
if [[ $(echo "$result" | jq -r '.is_error') == "true" ]]; then
    echo "Error: $(echo "$result" | jq -r '.result')" >&2
    exit 1
fi

Official Documentation

https://code.claude.com/docs/en/headless - Headless mode reference
https://code.claude.com/docs/en/settings - Settings and permissions

Additional Resources

./references/cli-options.md - Complete CLI flag reference
./references/output-formats.md - Output format schemas
./references/integration-patterns.md - CI/CD and scripting examples

See Also: claude-code-hooks for automation events, claude-code-debug for troubleshooting