Claude Code SDK

TL;DR

• SDK 是 Claude Code 不開 interactive UI 也能用的方式——當函式庫塞進你自己的程式裡。
• 適用：CI 上自動跑、一次處理一堆任務、把 Claude 當 pipeline 的一站。
• 跟互動式 Claude Code 共用 hooks / MCP / .claude/ settings，只是換了入口而已。

一個情境：在 GitHub Action 上自動 review PR

你想做這件事：每次有人開 PR，自動跑 Claude 看一輪、留 comment 指出問題。

互動式 Claude Code 卡住了：

• CLI 是給人坐在 terminal 前敲的，沒辦法 cron、沒辦法被另一個程式呼叫
• GitHub Action runner 上沒人按 enter
• 你要的不是「跟它聊」，是「程式呼叫一次、拿結果、繼續往下」

這就是 SDK 存在的理由——把同一個 agent loop 包成函式庫，讓你的 script 直接 import 它。

一個極簡範例

Node 版（package 是 @anthropic-ai/claude-agent-sdk）：

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = "找出 src/queries/ 底下重複的 query";

for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

跑起來會吐一串 JSON 訊息——跟你在 CLI 看到的對話事件一樣（tool call、tool result、Claude 的文字回覆）。最後一則會是 final response。

概念上跟 CLI 一模一樣，差別只在「結果是 stream of JSON 給程式讀」而不是「畫面上排版好給人看」。

SDK vs 互動式 Claude Code

	互動式 Claude Code	SDK
UI	terminal TUI	沒有，stream JSON
觸發	人坐在 terminal 前	程式 / cron / webhook
適用	寫程式、debug	CI、批次、pipeline 一站
工具集	全開	預設保守，可用 allowedTools 收緊
Hooks / MCP / .claude/	吃	一樣吃

最後一列是重點：換的是入口，不是底層。同一份 .claude/settings.json、同一組 MCP servers、同一批 hooks，SDK 跑起來都繼續生效。

三個典型 use case

1. CI 自動 review PR：GitHub Action trigger，SDK 跑 Claude 看 diff、把 comment 貼回 PR。整個流程沒人類介入。
2. 批次任務：「這 100 個 issue 幫我各自分類、加 label」。寫個迴圈，每個 issue 餵一次 SDK，收結果寫回。互動式 CLI 不可能做這個。
3. agentic pipeline：Claude 是 pipeline 中的一站——前面有別的程式準備資料、後面有別的程式接續。Claude 負責中間需要「讀懂、判斷、改寫」的那一段。

共通點：呼叫者是程式不是人。任何「給我一串 input、拿到 output、繼續流程」的場景，SDK 才接得住。

共用 settings 怎麼吃

SDK 跑起來會去找你 repo 的 .claude/ 資料夾，跟互動式 CLI 一樣：

• Hooks：你寫的 PreToolUse / PostToolUse 照常觸發
• MCP servers：.claude/settings.json 裡列的 servers 一樣連
• Permissions：預設保守（read 居多），要寫檔得用 allowedTools 或 settings 開

意思是你不用為了 SDK 重新設定一次。前面 Section 3 寫的 hooks、Section 2 接的 MCP，直接被 SDK 繼承。

接下來

進入 Section 4，從 Subagents 開始——同一個 Claude Code 怎麼長出「分身」幫你並行處理任務。