Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Agent SDK は、Claude Code を支える同じツール、エージェントループ、およびコンテキスト管理を提供します。スクリプトと CI/CD 用の CLI として、または完全なプログラムによる制御のための Python および TypeScript パッケージとして利用できます。
CLI は以前「headless mode」と呼ばれていました。-p フラグとすべての CLI オプションは同じように機能します。
-p を渡します。
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
claude -p）経由で Agent SDK を使用することについて説明しています。構造化された出力、ツール承認コールバック、およびネイティブメッセージオブジェクトを備えた Python および TypeScript SDK パッケージについては、完全な Agent SDK ドキュメント を参照してください。
基本的な使用方法
任意の claude コマンドに -p（または --print）フラグを追加して、非対話的に実行します。すべての CLI オプション は -p で機能します。以下を含みます。
この例は、コードベースについて Claude に質問し、応答を出力します。
claude -p "What does the auth module do?"
ベアモードでより高速に開始する
--bare を追加して、hooks、skills、plugins、MCP サーバー、auto memory、および CLAUDE.md の自動検出をスキップすることで、起動時間を短縮します。これがない場合、claude -p は対話型セッションと同じ コンテキスト を読み込みます。これには、作業ディレクトリまたは ~/.claude で設定されたすべてのものが含まれます。
ベアモードは、すべてのマシンで同じ結果が必要な CI とスクリプトに役立ちます。チームメイトの ~/.claude のフック、またはプロジェクトの .mcp.json の MCP サーバーは実行されません。ベアモードはそれらを読み込まないためです。明示的に渡すフラグのみが有効になります。
この例は、ベアモードで 1 回限りの要約タスクを実行し、Read ツールを事前承認して、呼び出しが許可プロンプトなしで完了するようにします。
claude --bare -p "Summarize this file" --allowedTools "Read"
| 読み込むもの | 使用するもの |
|---|
| システムプロンプト追加 | --append-system-prompt、--append-system-prompt-file |
| 設定 | --settings <file-or-json> |
| MCP サーバー | --mcp-config <file-or-json> |
| カスタムエージェント | --agents <json> |
| プラグインディレクトリ | --plugin-dir <path> |
ANTHROPIC_API_KEY または --settings に渡される JSON の apiKeyHelper から取得する必要があります。Bedrock、Vertex、および Foundry は通常のプロバイダー認証情報を使用します。
--bare はスクリプトおよび SDK 呼び出しの推奨モードであり、将来のリリースで -p のデフォルトになります。
--bare を追加して、ローカルで設定されているものを取得しないようにします。
構造化された出力を取得する
--output-format を使用して、応答がどのように返されるかを制御します。
text（デフォルト）：プレーンテキスト出力json：結果、セッション ID、およびメタデータを含む構造化 JSONstream-json：リアルタイムストリーミング用の改行区切り JSON
この例は、セッションメタデータを含む JSON としてプロジェクト概要を返し、テキスト結果は result フィールドに含まれます。
claude -p "Summarize this project" --output-format json
--output-format json を --json-schema および JSON Schema 定義と共に使用します。応答には、リクエストに関するメタデータ（セッション ID、使用状況など）が含まれ、構造化された出力は structured_output フィールドに含まれます。
この例は、auth.py から関数名を抽出し、文字列の配列として返します。
claude -p "Extract the main function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
jq などのツールを使用して応答を解析し、特定のフィールドを抽出します。# テキスト結果を抽出
claude -p "Summarize this project" --output-format json | jq -r '.result'
# 構造化された出力を抽出
claude -p "Extract function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
| jq '.structured_output'
レスポンスをストリーミングする
--output-format stream-json を --verbose および --include-partial-messages と共に使用して、生成されるトークンをリアルタイムで受け取ります。各行はイベントを表す JSON オブジェクトです。
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
-r フラグは生の文字列を出力し（引用符なし）、-j は改行なしで結合するため、トークンは継続的にストリーミングされます。
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
system/api_retry イベントを発行します。これを使用して、再試行の進行状況を表示したり、カスタムバックオフロジックを実装したりできます。
| フィールド | 型 | 説明 |
|---|
type | "system" | メッセージタイプ |
subtype | "api_retry" | これが再試行イベントであることを識別します |
attempt | 整数 | 現在の試行番号（1 から開始） |
max_retries | 整数 | 許可される再試行の合計 |
retry_delay_ms | 整数 | 次の試行までのミリ秒 |
error_status | 整数または null | HTTP ステータスコード、または HTTP レスポンスのない接続エラーの場合は null |
error | 文字列 | エラーカテゴリ：authentication_failed、oauth_org_not_allowed、billing_error、rate_limit、invalid_request、server_error、max_output_tokens、または unknown |
uuid | 文字列 | 一意のイベント識別子 |
session_id | 文字列 | イベントが属するセッション |
system/init イベントは、モデル、ツール、MCP サーバー、および読み込まれたプラグインを含むセッションメタデータを報告します。CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されていない限り、ストリームの最初のイベントです。その場合、plugin_install イベントがそれより前にあります。プラグインフィールドを使用して、プラグインが読み込まれなかった場合に CI を失敗させます。
| フィールド | 型 | 説明 |
|---|
plugins | 配列 | 正常に読み込まれたプラグイン。各プラグインは name と path を持ちます |
plugin_errors | 配列 | 満たされていない依存関係バージョンなどのプラグイン読み込み時エラー。各エラーは plugin、type、および message を持ちます。影響を受けたプラグインは降格され、plugins から削除されます。エラーがない場合、キーは省略されます |
CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されている場合、Claude Code は最初のターンの前にマーケットプレイスプラグインがインストールされている間、system/plugin_install イベントを発行します。これらを使用して、独自の UI にインストール進行状況を表示します。
| フィールド | 型 | 説明 |
|---|
type | "system" | メッセージタイプ |
subtype | "plugin_install" | これがプラグインインストールイベントであることを識別します |
status | "started"、"installed"、"failed"、または "completed" | started と completed は全体的なインストールを囲みます。installed と failed は個別のマーケットプレイスを報告します |
name | 文字列（オプション） | マーケットプレイス名。installed と failed に存在します |
error | 文字列（オプション） | 失敗メッセージ。failed に存在します |
uuid | 文字列 | 一意のイベント識別子 |
session_id | 文字列 | イベントが属するセッション |
ツールを自動承認する
--allowedTools を使用して、Claude が確認を求めずに特定のツールを使用できるようにします。この例はテストスイートを実行し、失敗を修正し、Claude が許可を求めずに Bash コマンドを実行し、ファイルを読み取り/編集できるようにします。
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit"
dontAsk は permissions.allow ルールまたは 読み取り専用コマンドセット にないものをすべて拒否します。これはロックダウンされた CI 実行に役立ちます。acceptEdits を使用すると、Claude はプロンプトなしでファイルを書き込むことができ、mkdir、touch、mv、cp などの一般的なファイルシステムコマンドも自動承認します。その他のシェルコマンドとネットワークリクエストは、--allowedTools エントリまたは permissions.allow ルールが必要です。そうでない場合、実行が試みられると実行が中止されます。
claude -p "Apply the lint fixes" --permission-mode acceptEdits
コミットを作成する
この例は、ステージされた変更を確認し、適切なメッセージを含むコミットを作成します。
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
--allowedTools フラグは パーミッションルール構文 を使用します。末尾の * はプレフィックスマッチングを有効にするため、Bash(git diff *) は git diff で始まるすべてのコマンドを許可します。スペースは重要です。スペースがない場合、Bash(git diff*) は git diff-index にも一致します。
ユーザーが呼び出した skills（/commit など）および 組み込みコマンド は、対話モードでのみ利用可能です。-p モードでは、代わりに実行したいタスクを説明してください。 システムプロンプトをカスタマイズする
--append-system-prompt を使用して、Claude Code のデフォルト動作を保持しながら指示を追加します。この例は PR diff を Claude にパイプし、セキュリティ脆弱性をレビューするよう指示します。
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
--system-prompt を含む詳細なオプションについては、システムプロンプトフラグ を参照してください。
会話を続ける
--continue を使用して最新の会話を続けるか、--resume をセッション ID と共に使用して特定の会話を続けます。この例はレビューを実行し、その後フォローアッププロンプトを送信します。
# 最初のリクエスト
claude -p "Review this codebase for performance issues"
# 最新の会話を続ける
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
次のステップ
