Claude Code をプログラムで実行する

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

​

基本的な使用方法

• --continue は 会話を続行する ため
• --allowedTools は ツールを自動承認する ため
• --output-format は 構造化された出力を取得する ため

claude -p "What does the auth module do?"

​

bare モードで高速に開始する

claude --bare -p "Summarize README.md" --allowedTools "Read"

• MCP サーバー: コマンドラインで指定されたサーバー（例えば --mcp-config で指定したもの）のみが接続されます。対話型セッションでは、--ide を渡さない限り、Claude Code は IDE への自動接続もスキップします。
• システムリマインダー: Claude はプロンプトとツールの結果を受け取りますが、Claude Code が通常それらと一緒に追加する システムリマインダー は含まれません。例えば、以前に読み取ったファイルがディスク上で変更されても Claude には通知されず、--add-dir フォルダのスキルを含む利用可能なスキルの一覧も Claude には渡されません。
• バックグラウンドタスク: Claude はバックグラウンドコマンドやバックグラウンドサブエージェントを実行できず、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS によってオフになるその他の機能もオフになります。タイムアウト に達したコマンドは、バックグラウンドに移行する 代わりに停止します。

​

終了時のバックグラウンドタスク

• バックグラウンドコマンド: メイン会話が開始したコマンド（例えば開発サーバーやウォッチビルド）の場合、実行はコマンドが終了するか 時間制限 に達するまで待機します。その後、Claude はその結果を受けてもう 1 ターン実行します。コマンドの実行中は、10 分の上限によって待機が終了することはありません。
• バックグラウンドの サブエージェント とワークフロー: その結果は最終出力の一部であるため、実行はその作業が完了するまで開いたままになります。
• Monitor ウォッチ: 実行は、ウォッチがタイムアウトするか 10 分の上限が待機を終了するか、どちらか先に来た方まで待機します。待機中、Claude はウォッチが報告することに応答し続けます。デフォルトでは、ウォッチは Claude が開始してから 5 分後にタイムアウトします。
• 保留中のウェイクアップ: プロンプトを --input-format stream-json ではなくテキストとして渡した実行で、Claude が 自己ペースの /loop ウェイクアップ をスケジュールした場合、実行は各ウェイクアップが発生するのを待ち、ループが終了する までその反復を実行します。これは 10 分の上限を超えても続きます。

​

非対話型の実行が終了したときの MCP の作業

• MCP タスク: リモートサーバー上ではジョブが続行されます。再度追跡するには、1 回限りの claude -p "<prompt>" 実行としてではなく、そのセッションを再開 してください。
• 自動バックグラウンド化 によって移行された MCP 呼び出し: 呼び出しの結果は失われます。

​

SIGTERM で実行を停止する

• コマンドを実行中: Claude Code はコマンドをセッションで強制終了として記録します。
• 権限プロンプトへの回答を待機中: SIGTERM をプロセスに送信した場合、Claude Code はプロンプトを未回答のままにします。プログラムが Agent SDK を通じてセッションを閉じた場合、SDK はシグナルを送信する前に Claude Code の入力を終了し、Claude Code は入力が終了するとすぐにプロンプトをキャンセルします。

​

作業ディレクトリが削除された場合

​

例

​

Claude にデータをパイプする

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

​

ビルドスクリプトに Claude を追加する

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

​

構造化された出力を取得する

• text（デフォルト）：プレーンテキスト出力
• json：結果、セッション ID、メタデータを含む構造化 JSON
• stream-json：リアルタイムストリーミング用の改行区切り JSON

claude -p "Summarize this project" --output-format json

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"]}'

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
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'

​

応答をストリーミングする

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

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'

​

サブエージェントのメッセージを追跡する

• デフォルト：その実行の tool_use および tool_result ブロック。
• --forward-subagent-text または CLAUDE_CODE_FORWARD_SUBAGENT_TEXT を使用した場合：その実行のテキストブロックと思考ブロックも発行されるため、各実行のトランスクリプトを再構築できます。

• Claude がメインの会話から Skill ツールで開始するフォークされたスキル：tool_use および tool_result ブロックには v2.1.86 以降、最初の user メッセージとテキストブロックおよび思考ブロックには v2.1.265 以降
• フォークされたスキルが生成するサブエージェントのメッセージ、およびサブエージェントや別のフォークされたスキルの中で開始されたフォークされたスキルのメッセージ：v2.1.275 以降
• /<skill-name> をプロンプトとして渡して開始したフォークされたスキルのメッセージ：v2.1.287 以降

​

API の再試行を処理する

​

セッションメタデータを読む

• plugin_install イベント（CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されている場合）。
• hook_started、hook_progress、および hook_response イベント（設定された SessionStart または Setup フックが実行されている間）。これらはフックが生成するたびにストリーミングされます。

​

プラグインまたは MCP サーバーが読み込まれない場合に CI を失敗させる

​

プラグインのインストールを追跡する

​

ツールを自動承認する

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

• auto：--permission-mode auto を渡すと、ユーザーに代わって分類器がほとんどのアクションをレビューします
• dontAsk：Claude Code は、本来なら確認を求めるすべての呼び出しを拒否します。これは制限された CI 実行に役立ちますが、インストールした mod がそれらの呼び出しの一部を承認できる場合があります。mod がどの呼び出しを承認できるかを確認するには、フックで権限を拡張するを参照してください。 Manual モードで承認が不要なアクション（作業ディレクトリでのファイル読み取りや読み取り専用コマンドセットなど）は引き続き実行されます。--allowedTools エントリまたは permissions.allow ルールがカバーするアクションも実行されます。AskUserQuestion、組織が ask に設定したコネクタツール、requiresUserInteraction とマークされた MCP ツール、およびネットワークパスからの読み取りは、許可ルールが一致する場合でも拒否されます
• acceptEdits：Claude は確認なしでファイルを書き込み、Claude Code は mkdir、touch、mv、cp などの一般的なファイルシステムコマンドを自動承認します。どのモードでも自動承認されないアクションは引き続き適用されます。読み取り専用コマンドセットを除き、その他のシェルコマンドとネットワークリクエストには引き続き --allowedTools エントリまたは permissions.allow ルールが必要です。完全なリストについては acceptEdits が自動承認する内容を参照してください

claude -p "Apply the lint fixes" --permission-mode acceptEdits

​

無人実行で権限プロンプトをオフにする

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

​

コミットを作成する

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 *)"

​

システムプロンプトをカスタマイズする

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

​

会話を続ける

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
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"

​

次のステップ

• Agent SDK クイックスタート：Python または TypeScript で最初のエージェントを構築します
• CLI リファレンス：すべての CLI フラグとオプション
• GitHub Actions：GitHub ワークフローで Agent SDK を使用します
• GitLab CI/CD：GitLab パイプラインで Agent SDK を使用します