Claude Code SDK

Claude Code SDK, Claude Code’u kendi uygulamandan veya script’inden programatik olarak çağırmanın yoludur. CLI’daki tüm yetenekler — tool’lar, hooks, subagents — SDK üzerinden de erişilir.

1. SDK ne için?

Senaryo	SDK iyi seçim mi?
CI’da otomatik kod review	✅ Evet
Issue’dan PR üreten bot	✅ Evet
Sabah cron’unda dependency upgrade taraması	✅ Evet
Chrome extension içinde “fix this” butonu	✅ Evet
Yerel günlük geliştirme	❌ CLI yeter

SDK = otomasyon, CLI = etkileşimli kullanım.

2. Yükleme

TypeScript

npm install @anthropic-ai/claude-agent-sdk

Python

pip install claude-agent-sdk

3. Minimal örnek (TypeScript)

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

const response = await query({
  prompt: "package.json'a bak ve hangi dependencies kullanılmış özetle.",
  options: {
    cwd: "/repo/path",
    permissionMode: "acceptEdits",
  },
});

for await (const event of response) {
  if (event.type === "text") {
    console.log(event.text);
  }
}

Stream halinde olay alırsın: text, tool_use, tool_result, done.

4. Minimal örnek (Python)

from claude_agent_sdk import query

async def main():
    async for event in query(
        prompt="package.json'a bak ve özetle.",
        cwd="/repo/path",
        permission_mode="acceptEdits",
    ):
        if event.type == "text":
            print(event.text)

5. Permission mode

SDK’da headless çalışırken permission seçimi kritik:

Mode	Davranış	Ne zaman
default	Her aksiyona prompt — SDK akışında kilitlenir	İnteraktif değilse kullanma
acceptEdits	Edit/Write otomatik, Bash sorulur	Çoğu otomasyon
bypassPermissions	Her şey otomatik	Sadece izole/container

6. Tool seçimi

SDK’ya hangi tool’lara izin vereceğini belirtebilirsin:

options: {
  allowedTools: ["Read", "Grep", "Glob"],
  // deniedTools: ["Bash"],
}

Read-only kod review için sadece Read/Grep/Glob açmak güvenli kalır.

7. Hook’lar SDK’da da çalışır

.claude/settings.json’daki hook’lar SDK çağrılarında da tetiklenir (cwd repo’ya bağlı olduğunda). Aynı format/lint/güvenlik kuralları otomatikleşir.

8. CI örneği — GitHub Actions

name: AI Review
on:
  pull_request:
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i -g @anthropic-ai/claude-agent-sdk
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: node scripts/ai-review.js

scripts/ai-review.js içinde SDK ile PR diff’i alıp Claude’a review prompt’u atarsın.

9. Sınırlamalar ve gotcha’lar

• API key zorunlu: SDK Claude.ai oturumunu kullanmaz, API key gerekir
• Maliyet: Her query API faturası demek — long-running senaryolarda dikkat
• Network erişimi: WebFetch açıksa SDK runner’ın internet’i olmalı
• Filesystem izolasyonu: SDK’nın cwd’sini her zaman dikkatle ver — kazara üst dizini değiştirebilir

10. SDK öğrenmek için ek kaynak

Daha derin için: Anthropic’in Building with the Claude API kursu (bu kurs kataloğunda var) SDK + tool use + caching konularına geçer. Claude Code SDK ile Anthropic SDK ortak Claude modelleri üzerinde çalışır.

Özet

• SDK = otomasyon yolu; CLI = etkileşimli
• TS ve Python sürümleri var
• Permission mode kritik; bypassPermissions sadece izole ortamda
• Hook’lar SDK’da da çalışır
• CI’da PR review veya issue → PR akışı için ideal

Sırada ne var?

Son modül: özet, sırada ne var ve sertifika.