Claude Code SDK memungkinkan menjalankan Claude Code sebagai subprocess, menyediakan cara untuk membangun asisten coding bertenaga AI dan alat yang memanfaatkan kemampuan Claude.

SDK tersedia untuk penggunaan command line, TypeScript, dan Python.

Autentikasi

Claude Code SDK mendukung beberapa metode autentikasi:

Kunci API Anthropic

Untuk menggunakan Claude Code SDK secara langsung dengan API Anthropic, kami merekomendasikan membuat kunci API khusus:

  1. Buat kunci API Anthropic di Anthropic Console
  2. Kemudian, atur variabel environment ANTHROPIC_API_KEY. Kami merekomendasikan menyimpan kunci ini dengan aman (misalnya, menggunakan Github secret)

Kredensial API pihak ketiga

SDK juga mendukung penyedia API pihak ketiga:

  • Amazon Bedrock: Atur variabel environment CLAUDE_CODE_USE_BEDROCK=1 dan konfigurasikan kredensial AWS
  • Google Vertex AI: Atur variabel environment CLAUDE_CODE_USE_VERTEX=1 dan konfigurasikan kredensial Google Cloud

Untuk instruksi konfigurasi terperinci untuk penyedia pihak ketiga, lihat dokumentasi Amazon Bedrock dan Google Vertex AI.

Penggunaan dasar SDK

Claude Code SDK memungkinkan Anda menggunakan Claude Code dalam mode non-interaktif dari aplikasi Anda.

Command line

Berikut adalah beberapa contoh dasar untuk SDK command line:

# Jalankan satu prompt dan keluar (mode print)
$ claude -p "Write a function to calculate Fibonacci numbers"

# Menggunakan pipe untuk menyediakan stdin
$ echo "Explain this code" | claude -p

# Output dalam format JSON dengan metadata
$ claude -p "Generate a hello world function" --output-format json

# Stream output JSON saat tiba
$ claude -p "Build a React component" --output-format stream-json

TypeScript

SDK TypeScript disertakan dalam paket utama @anthropic-ai/claude-code di NPM:

import { query, type SDKMessage } from "@anthropic-ai/claude-code";

const messages: SDKMessage[] = [];

for await (const message of query({
  prompt: "Write a haiku about foo.py",
  abortController: new AbortController(),
  options: {
    maxTurns: 3,
  },
})) {
  messages.push(message);
}

console.log(messages);

SDK TypeScript menerima semua argumen yang didukung oleh SDK command line, serta:

ArgumenDeskripsiDefault
abortControllerAbort controllernew AbortController()
cwdDirektori kerja saat iniprocess.cwd()
executableRuntime JavaScript mana yang akan digunakannode saat berjalan dengan Node.js, bun saat berjalan dengan Bun
executableArgsArgumen untuk diteruskan ke executable[]
pathToClaudeCodeExecutablePath ke executable Claude CodeExecutable yang dikirim dengan @anthropic-ai/claude-code

Python

SDK Python tersedia sebagai claude-code-sdk di PyPI:

pip install claude-code-sdk

Prasyarat:

  • Python 3.10+
  • Node.js
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

Penggunaan dasar:

import anyio
from claude_code_sdk import query, ClaudeCodeOptions, Message

async def main():
    messages: list[Message] = []
    
    async for message in query(
        prompt="Write a haiku about foo.py",
        options=ClaudeCodeOptions(max_turns=3)
    ):
        messages.append(message)
    
    print(messages)

anyio.run(main)

SDK Python menerima semua argumen yang didukung oleh SDK command line melalui kelas ClaudeCodeOptions:

from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path

options = ClaudeCodeOptions(
    max_turns=3,
    system_prompt="You are a helpful assistant",
    cwd=Path("/path/to/project"),  # Bisa berupa string atau Path
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode="acceptEdits"
)

async for message in query(prompt="Hello", options=options):
    print(message)

Penggunaan lanjutan

Dokumentasi di bawah ini menggunakan SDK command line sebagai contoh, tetapi juga dapat digunakan dengan SDK TypeScript dan Python.

Percakapan multi-turn

Untuk percakapan multi-turn, Anda dapat melanjutkan percakapan atau melanjutkan dari sesi terbaru:

# Lanjutkan percakapan terbaru
$ claude --continue

# Lanjutkan dan berikan prompt baru
$ claude --continue "Now refactor this for better performance"

# Lanjutkan percakapan tertentu berdasarkan ID sesi
$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# Lanjutkan dalam mode print (non-interaktif)
$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Lanjutkan dalam mode print (non-interaktif)
$ claude -p --continue "Add error handling"

System prompt kustom

Anda dapat menyediakan system prompt kustom untuk memandu perilaku Claude:

# Override system prompt (hanya bekerja dengan --print)
$ claude -p "Build a REST API" --system-prompt "You are a senior backend engineer. Focus on security, performance, and maintainability."

# System prompt dengan persyaratan khusus
$ claude -p "Create a database schema" --system-prompt "You are a database architect. Use PostgreSQL best practices and include proper indexing."

Anda juga dapat menambahkan instruksi ke system prompt default:

# Tambahkan system prompt (hanya bekerja dengan --print)
$ claude -p "Build a REST API" --append-system-prompt "After writing code, be sure to code review yourself."

Konfigurasi MCP

Model Context Protocol (MCP) memungkinkan Anda memperluas Claude Code dengan alat dan sumber daya tambahan dari server eksternal. Menggunakan flag --mcp-config, Anda dapat memuat server MCP yang menyediakan kemampuan khusus seperti akses database, integrasi API, atau tooling kustom.

Buat file konfigurasi JSON dengan server MCP Anda:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/files"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Kemudian gunakan dengan Claude Code:

# Muat server MCP dari konfigurasi
$ claude -p "List all files in the project" --mcp-config mcp-servers.json

# Penting: Alat MCP harus secara eksplisit diizinkan menggunakan --allowedTools
# Alat MCP mengikuti format: mcp__$serverName__$toolName
$ claude -p "Search for TODO comments" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# Gunakan alat MCP untuk menangani prompt izin dalam mode non-interaktif
$ claude -p "Deploy the application" \
  --mcp-config mcp-servers.json \
  --allowedTools "mcp__permissions__approve" \
  --permission-prompt-tool mcp__permissions__approve

Saat menggunakan alat MCP, Anda harus secara eksplisit mengizinkannya menggunakan flag --allowedTools. Nama alat MCP mengikuti pola mcp__<serverName>__<toolName> dimana:

  • serverName adalah kunci dari file konfigurasi MCP Anda
  • toolName adalah alat spesifik yang disediakan oleh server tersebut

Langkah keamanan ini memastikan bahwa alat MCP hanya digunakan ketika secara eksplisit diizinkan.

Jika Anda hanya menentukan nama server (yaitu, mcp__<serverName>), semua alat dari server tersebut akan diizinkan.

Pola glob (misalnya, mcp__go*) tidak didukung.

Alat prompt izin kustom

Secara opsional, gunakan --permission-prompt-tool untuk memasukkan alat MCP yang akan kami gunakan untuk memeriksa apakah pengguna memberikan izin kepada model untuk memanggil alat tertentu. Ketika model memanggil alat, hal berikut terjadi:

  1. Kami pertama memeriksa pengaturan izin: semua file settings.json, serta --allowedTools dan --disallowedTools yang diteruskan ke SDK; jika salah satu dari ini mengizinkan atau menolak panggilan alat, kami melanjutkan dengan panggilan alat
  2. Jika tidak, kami memanggil alat MCP yang Anda berikan dalam --permission-prompt-tool

Alat MCP --permission-prompt-tool diberikan nama alat dan input, dan harus mengembalikan payload yang di-JSON-stringify dengan hasilnya. Payload harus berupa salah satu dari:

// panggilan alat diizinkan
{
  "behavior": "allow",
  "updatedInput": {...}, // input yang diperbarui, atau hanya kembalikan input asli
}

// panggilan alat ditolak
{
  "behavior": "deny",
  "message": "..." // string yang dapat dibaca manusia menjelaskan mengapa izin ditolak
}

Misalnya, implementasi alat prompt izin MCP TypeScript mungkin terlihat seperti ini:

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simulate a permission check - approve if the input contains "allow", otherwise deny',
  {
    tool_name: z.string().describe("The tool requesting permission"),
    input: z.object({}).passthrough().describe("The input for the tool"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permission denied by test approval_prompt tool",
                }
          ),
        },
      ],
    };
  }
);

Untuk menggunakan alat ini, tambahkan server MCP Anda (misalnya dengan --mcp-config), kemudian panggil SDK seperti ini:

claude -p "..." \
  --permission-prompt-tool mcp__test-server__approval_prompt \
  --mcp-config my-config.json

Catatan penggunaan:

  • Gunakan updatedInput untuk memberi tahu model bahwa prompt izin mengubah inputnya; jika tidak, atur updatedInput ke input asli, seperti dalam contoh di atas. Misalnya, jika alat menunjukkan diff edit file kepada pengguna dan memungkinkan mereka mengedit diff secara manual, alat prompt izin harus mengembalikan edit yang diperbarui tersebut.
  • Payload harus di-JSON-stringify

Opsi CLI yang tersedia

SDK memanfaatkan semua opsi CLI yang tersedia di Claude Code. Berikut adalah yang utama untuk penggunaan SDK:

FlagDeskripsiContoh
--print, -pJalankan dalam mode non-interaktifclaude -p "query"
--output-formatTentukan format output (text, json, stream-json)claude -p --output-format json
--resume, -rLanjutkan percakapan berdasarkan ID sesiclaude --resume abc123
--continue, -cLanjutkan percakapan terbaruclaude --continue
--verboseAktifkan logging verboseclaude --verbose
--max-turnsBatasi turn agentik dalam mode non-interaktifclaude --max-turns 3
--system-promptOverride system prompt (hanya dengan --print)claude --system-prompt "Custom instruction"
--append-system-promptTambahkan ke system prompt (hanya dengan --print)claude --append-system-prompt "Custom instruction"
--allowedToolsDaftar alat yang diizinkan dipisahkan spasi, atau

string daftar alat yang diizinkan dipisahkan koma
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsDaftar alat yang ditolak dipisahkan spasi, atau

string daftar alat yang ditolak dipisahkan koma
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configMuat server MCP dari file JSONclaude --mcp-config servers.json
--permission-prompt-toolAlat MCP untuk menangani prompt izin (hanya dengan --print)claude --permission-prompt-tool mcp__auth__prompt

Untuk daftar lengkap opsi CLI dan fitur, lihat dokumentasi referensi CLI.

Format output

SDK mendukung beberapa format output:

Output teks (default)

Mengembalikan hanya teks respons:

$ claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

Output JSON

Mengembalikan data terstruktur termasuk metadata:

$ claude -p "How does the data layer work?" --output-format json

Format respons:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

Output JSON streaming

Streaming setiap pesan saat diterima:

$ claude -p "Build an application" --output-format stream-json

Setiap percakapan dimulai dengan pesan sistem init awal, diikuti oleh daftar pesan pengguna dan asisten, diikuti oleh pesan sistem result akhir dengan statistik. Setiap pesan dipancarkan sebagai objek JSON terpisah.

Skema pesan

Pesan yang dikembalikan dari JSON API diketik secara ketat sesuai dengan skema berikut:

type SDKMessage =
  // Pesan asisten
  | {
      type: "assistant";
      message: Message; // dari Anthropic SDK
      session_id: string;
    }

  // Pesan pengguna
  | {
      type: "user";
      message: MessageParam; // dari Anthropic SDK
      session_id: string;
    }

  // Dipancarkan sebagai pesan terakhir
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Dipancarkan sebagai pesan terakhir, ketika kita telah mencapai jumlah maksimum turn
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Dipancarkan sebagai pesan pertama di awal percakapan
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Kami akan segera menerbitkan tipe-tipe ini dalam format yang kompatibel dengan JSONSchema. Kami menggunakan semantic versioning untuk paket Claude Code utama untuk mengkomunikasikan perubahan breaking pada format ini.

Tipe Message dan MessageParam tersedia di SDK Anthropic. Misalnya, lihat SDK Anthropic TypeScript dan Python.

Format input

SDK mendukung beberapa format input:

Input teks (default)

Teks input dapat diberikan sebagai argumen:

$ claude -p "Explain this code"

Atau teks input dapat di-pipe melalui stdin:

$ echo "Explain this code" | claude -p

Input JSON streaming

Stream pesan yang disediakan melalui stdin dimana setiap pesan mewakili turn pengguna. Ini memungkinkan beberapa turn percakapan tanpa meluncurkan ulang binary claude dan memungkinkan memberikan panduan kepada model saat sedang memproses permintaan.

Setiap pesan adalah objek JSON ‘User message’, mengikuti format yang sama dengan skema pesan output. Pesan diformat menggunakan format jsonl dimana setiap baris input adalah objek JSON lengkap. Input JSON streaming memerlukan -p dan --output-format stream-json.

Saat ini ini terbatas pada pesan pengguna khusus teks.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Contoh

Integrasi script sederhana

#!/bin/bash

# Fungsi sederhana untuk menjalankan Claude dan memeriksa kode keluar
run_claude() {
    local prompt="$1"
    local output_format="${2:-text}"

    if claude -p "$prompt" --output-format "$output_format"; then
        echo "Success!"
    else
        echo "Error: Claude failed with exit code $?" >&2
        return 1
    fi
}

# Contoh penggunaan
run_claude "Write a Python function to read CSV files"
run_claude "Optimize this database query" "json"

Memproses file dengan Claude

# Proses file melalui Claude
$ cat mycode.py | claude -p "Review this code for bugs"

# Proses beberapa file
$ for file in *.js; do
    echo "Processing $file..."
    claude -p "Add JSDoc comments to this file:" < "$file" > "${file}.documented"
done

# Gunakan Claude dalam pipeline
$ grep -l "TODO" *.py | while read file; do
    claude -p "Fix all TODO items in this file" < "$file"
done

Manajemen sesi

# Mulai sesi dan tangkap ID sesi
$ claude -p "Initialize a new project" --output-format json | jq -r '.session_id' > session.txt

# Lanjutkan dengan sesi yang sama
$ claude -p --resume "$(cat session.txt)" "Add unit tests"

Praktik terbaik

  1. Gunakan format output JSON untuk parsing programatis respons:

    # Parse respons JSON dengan jq
    result=$(claude -p "Generate code" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  2. Tangani error dengan baik - periksa kode keluar dan stderr:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Error occurred:" >&2
        cat error.log >&2
        exit 1
    fi
    
  3. Gunakan manajemen sesi untuk mempertahankan konteks dalam percakapan multi-turn

  4. Pertimbangkan timeout untuk operasi yang berjalan lama:

    timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
    
  5. Hormati batas rate saat membuat beberapa permintaan dengan menambahkan delay antara panggilan

Aplikasi dunia nyata

Claude Code SDK memungkinkan integrasi yang kuat dengan alur kerja pengembangan Anda. Salah satu contoh yang menonjol adalah Claude Code GitHub Actions, yang menggunakan SDK untuk menyediakan review kode otomatis, pembuatan PR, dan kemampuan triase issue langsung dalam alur kerja GitHub Anda.

Sumber daya terkait