TypeScript

Prasyarat

Node.js 18+

Instalasi

Instal @anthropic-ai/claude-code dari NPM:

npm install -g @anthropic-ai/claude-code

Untuk melihat kode sumber TypeScript SDK, kunjungi halaman @anthropic-ai/claude-code di NPM.

Penggunaan dasar

Antarmuka utama melalui TypeScript SDK adalah fungsi query, yang mengembalikan async iterator yang mengalirkan pesan saat mereka tiba:

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

for await (const message of query({
  prompt: "Analisis performa sistem",
  abortController: new AbortController(),
  options: {
    maxTurns: 5,
    systemPrompt: "Anda adalah seorang insinyur performa",
    allowedTools: ["Bash", "Read", "WebSearch"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Opsi konfigurasi

Argumen	Tipe	Deskripsi	Default
`abortController`	`AbortController`	Abort controller untuk membatalkan operasi	`new AbortController()`
`additionalDirectories`	`string[]`	Direktori tambahan untuk disertakan dalam sesi	`undefined`
`allowedTools`	`string[]`	Daftar alat yang diizinkan digunakan Claude	Semua alat diaktifkan secara default
`appendSystemPrompt`	`string`	Teks untuk ditambahkan ke system prompt default	`undefined`
`canUseTool`	`CanUseTool`	Fungsi izin kustom untuk penggunaan alat	`undefined`
`continue`	`boolean`	Lanjutkan sesi terbaru	`false`
`customSystemPrompt`	`string`	Ganti system prompt default sepenuhnya	`undefined`
`cwd`	`string`	Direktori kerja saat ini	`process.cwd()`
`disallowedTools`	`string[]`	Daftar alat yang tidak diizinkan digunakan Claude	`undefined`
`env`	`Dict<string>`	Variabel lingkungan untuk diatur	`undefined`
`executable`	`'bun' \| 'deno' \| 'node'`	Runtime JavaScript mana yang akan digunakan	`node` saat menjalankan dengan Node.js, `bun` saat menjalankan dengan Bun
`executableArgs`	`string[]`	Argumen untuk diteruskan ke executable	`[]`
`fallbackModel`	`string`	Model untuk digunakan jika model utama gagal	`undefined`
`maxThinkingTokens`	`number`	Token maksimum untuk proses berpikir Claude	`undefined`
`maxTurns`	`number`	Jumlah maksimum giliran percakapan	`undefined`
`mcpServers`	`Record<string, McpServerConfig>`	Konfigurasi server MCP	`undefined`
`model`	`string`	Model Claude untuk digunakan	Menggunakan default dari konfigurasi CLI
`pathToClaudeCodeExecutable`	`string`	Path ke executable Claude Code	Executable yang dikirim dengan `@anthropic-ai/claude-code`
`permissionMode`	`PermissionMode`	Mode izin untuk sesi	`"default"` (opsi: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`)
`permissionPromptToolName`	`string`	Nama alat MCP untuk prompt izin	`undefined`
`resume`	`string`	ID sesi untuk dilanjutkan	`undefined`
`stderr`	`(data: string) => void`	Callback untuk output stderr	`undefined`
`strictMcpConfig`	`boolean`	Paksa validasi konfigurasi MCP yang ketat	`undefined`

Percakapan multi-turn

Untuk percakapan multi-turn, Anda memiliki dua opsi.

Anda dapat menghasilkan respons dan melanjutkannya, atau Anda dapat menggunakan mode input streaming yang menerima async/generator untuk array pesan. Untuk saat ini, mode input streaming adalah satu-satunya cara untuk melampirkan gambar melalui pesan.

Lanjutkan dengan manajemen sesi

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

// Lanjutkan percakapan terbaru
for await (const message of query({
  prompt: "Sekarang refaktor ini untuk performa yang lebih baik",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Lanjutkan sesi spesifik
for await (const message of query({
  prompt: "Perbarui tes",
  options: {
    resume: "550e8400-e29b-41d4-a716-446655440000",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Mode input streaming

Mode input streaming memungkinkan Anda menyediakan pesan sebagai async iterable alih-alih string tunggal. Ini memungkinkan percakapan multi-turn, lampiran gambar, dan generasi pesan dinamis:

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

// Buat async generator untuk streaming pesan
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Mulai menganalisis codebase ini"
    }
  };
  
  // Tunggu kondisi tertentu atau input pengguna
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Sekarang fokus pada modul autentikasi"
    }
  };
}

// Gunakan input streaming
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Input streaming dengan gambar

Mode input streaming adalah satu-satunya cara untuk melampirkan gambar melalui pesan:

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* messagesWithImage() {
  // Kirim gambar dengan teks
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Analisis screenshot ini dan sarankan perbaikan"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("screenshot.png", "base64")
          }
        }
      ]
    }
  };
}

for await (const message of query({
  prompt: messagesWithImage()
})) {
  if (message.type === "result") console.log(message.result);
}

System prompt kustom

System prompt mendefinisikan peran, keahlian, dan perilaku agen Anda:

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

// Agen respons insiden SRE
for await (const message of query({
  prompt: "API down, investigasi",
  options: {
    systemPrompt: "Anda adalah ahli SRE. Diagnosis masalah secara sistematis dan berikan solusi yang dapat ditindaklanjuti.",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

// Tambahkan ke system prompt default
for await (const message of query({
  prompt: "Refaktor fungsi ini",
  options: {
    appendSystemPrompt: "Selalu sertakan penanganan error yang komprehensif dan unit test.",
    maxTurns: 2
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Alat kustom melalui MCP

Model Context Protocol (MCP) memungkinkan Anda memberikan agen Anda alat dan kemampuan kustom:

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

// Agen SRE dengan alat monitoring
for await (const message of query({
  prompt: "Investigasi gangguan layanan pembayaran",
  options: {
    mcpConfig: "sre-tools.json",
    allowedTools: ["mcp__datadog", "mcp__pagerduty", "mcp__kubernetes"],
    systemPrompt: "Anda adalah SRE. Gunakan data monitoring untuk mendiagnosis masalah.",
    maxTurns: 4
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Alat kustom menggunakan MCP

Anda dapat mengimplementasikan alat kustom menggunakan MCP, misalnya berikut adalah cara membuat alat penanganan izin kustom.

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

server.tool(
  "approval_prompt",
  'Simulasikan pemeriksaan izin - setujui jika input mengandung "allow", jika tidak tolak',
  {
    tool_name: z.string().describe("Nama alat yang meminta izin"),
    input: z.object({}).passthrough().describe("Input untuk alat"),
    tool_use_id: z.string().optional().describe("ID permintaan penggunaan alat yang unik"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Izin ditolak oleh alat approval_prompt test",
                }
          ),
        },
      ],
    };
  }
);

// Gunakan dalam SDK
import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Analisis codebase",
  options: {
    permissionPromptTool: "mcp__test-server__approval_prompt",
    mcpConfig: "my-config.json",
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Format output

Output teks (default)

// Output teks default
for await (const message of query({
  prompt: "Jelaskan file src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Output: Ini adalah komponen React yang menampilkan...
  }
}

Output JSON

// Kumpulkan semua pesan untuk akses seperti JSON
const messages = [];
for await (const message of query({
  prompt: "Bagaimana cara kerja data layer?"
})) {
  messages.push(message);
}

// Akses pesan hasil dengan metadata
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

Format input

// Prompt langsung
for await (const message of query({
  prompt: "Jelaskan kode ini"
})) {
  if (message.type === "result") console.log(message.result);
}

// Dari variabel
const userInput = "Jelaskan kode ini";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

Contoh integrasi agen

Agen respons insiden SRE

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

// Agen respons insiden otomatis
async function investigateIncident(
  incidentDescription: string,
  severity = "medium"
) {
  const messages = [];

  for await (const message of query({
    prompt: `Insiden: ${incidentDescription} (Tingkat keparahan: ${severity})`,
    options: {
      systemPrompt: "Anda adalah ahli SRE. Diagnosis masalah, nilai dampak, dan berikan item tindakan segera.",
      maxTurns: 6,
      allowedTools: ["Bash", "Read", "WebSearch", "mcp__datadog"],
      mcpConfig: "monitoring-tools.json"
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Penggunaan
const result = await investigateIncident("Payment API mengembalikan error 500", "high");
console.log(result.result);

Review keamanan otomatis

import { query } from "@anthropic-ai/claude-code";
import { execSync } from "child_process";

async function auditPR(prNumber: number) {
  // Dapatkan diff PR
  const prDiff = execSync(`gh pr diff ${prNumber}`, { encoding: 'utf8' });

  const messages = [];
  for await (const message of query({
    prompt: prDiff,
    options: {
      systemPrompt: "Anda adalah insinyur keamanan. Review PR ini untuk kerentanan, pola tidak aman, dan masalah kepatuhan.",
      maxTurns: 3,
      allowedTools: ["Read", "Grep", "WebSearch"]
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Penggunaan
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

Asisten hukum multi-turn

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

async function legalReview() {
  // Mulai sesi review hukum
  let sessionId: string;

  for await (const message of query({
    prompt: "Mulai sesi review hukum",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
  }

  // Review multi-langkah menggunakan sesi yang sama
  const steps = [
    "Review contract.pdf untuk klausul tanggung jawab",
    "Periksa kepatuhan dengan persyaratan GDPR",
    "Buat ringkasan eksekutif risiko"
  ];

  for (const step of steps) {
    for await (const message of query({
      prompt: step,
      options: { resume: sessionId, maxTurns: 2 }
    })) {
      if (message.type === "result") {
        console.log(`Langkah: ${step}`);
        console.log(message.result);
      }
    }
  }
}

Skema pesan

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

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

  // Pesan pengguna (input)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // dari Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Pesan pengguna (output/replay dengan UUID yang diperlukan)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // dari Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Dipancarkan sebagai pesan terakhir saat berhasil
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Dipancarkan sebagai pesan terakhir saat error atau max turns
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

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

  type SDKPermissionDenial = {
    tool_name: string;
    tool_use_id: string;
    tool_input: Record<string, unknown>;
  }

Tipe pendukung tambahan:

Tipe Message, MessageParam, dan Usage tersedia di Anthropic TypeScript SDK.

Sumber daya terkait

Penggunaan CLI dan kontrol - Dokumentasi CLI lengkap
Integrasi GitHub Actions - Otomatisasi workflow GitHub Anda dengan Claude
Workflow umum - Panduan langkah demi langkah untuk kasus penggunaan umum

Memulai

Bangun dengan Claude Code

Claude Code SDK

Deployment

Administrasi

Konfigurasi

Referensi

Sumber Daya

Prasyarat

Instalasi

Penggunaan dasar

Opsi konfigurasi

Percakapan multi-turn

Lanjutkan dengan manajemen sesi

Mode input streaming

Input streaming dengan gambar

System prompt kustom

Alat kustom melalui MCP

Alat kustom menggunakan MCP

Format output

Output teks (default)

Output JSON

Format input

Contoh integrasi agen

Agen respons insiden SRE

Review keamanan otomatis

Asisten hukum multi-turn

Skema pesan

Sumber daya terkait

Memulai

Bangun dengan Claude Code

Claude Code SDK

Deployment

Administrasi

Konfigurasi

Referensi

Sumber Daya

​Prasyarat

​Instalasi

​Penggunaan dasar

​Opsi konfigurasi

​Percakapan multi-turn

​Lanjutkan dengan manajemen sesi

​Mode input streaming

​Input streaming dengan gambar

​System prompt kustom

​Alat kustom melalui MCP

​Alat kustom menggunakan MCP

​Format output

​Output teks (default)

​Output JSON

​Format input

​Contoh integrasi agen

​Agen respons insiden SRE

​Review keamanan otomatis

​Asisten hukum multi-turn

​Skema pesan

​Sumber daya terkait

Prasyarat

Instalasi

Penggunaan dasar

Opsi konfigurasi

Percakapan multi-turn

Lanjutkan dengan manajemen sesi

Mode input streaming

Input streaming dengan gambar

System prompt kustom

Alat kustom melalui MCP

Alat kustom menggunakan MCP

Format output

Output teks (default)

Output JSON

Format input

Contoh integrasi agen

Agen respons insiden SRE

Review keamanan otomatis

Asisten hukum multi-turn

Skema pesan

Sumber daya terkait