The Claude Code SDK

What is the Claude Code SDK?

The Claude Code SDK is a programmatic interface that lets you use Claude Code's full tool capabilities from your own scripts, CI pipelines, and automation workflows. It's available as a CLI tool, a TypeScript library, and a Python library -- all providing the same powerful tool set you use interactively in the terminal.

ℹ️

Same Tools, Programmatic Access

The SDK gives you the same file reading, writing, searching, and command execution tools available in the interactive terminal -- but callable from your code. This makes it possible to embed Claude Code intelligence into any automated workflow.

Interface	Best For	Example Usage
CLI	Shell scripts, CI/CD pipelines	claude-code query 'analyze this PR'
TypeScript SDK	Node.js apps, hooks, custom tools	import { query } from '@anthropic-ai/claude-code'
Python SDK	Data pipelines, Jupyter notebooks	from claude_code import query

Three ways to access the Claude Code SDK

Permissions and Security

By default, the SDK operates in read-only mode -- it can read files, search directories, and run grep operations, but cannot write to files or execute destructive commands. Write permissions must be explicitly enabled, providing a safe-by-default approach for automated workflows.

typescriptRead-only by default, write access is opt-in

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

// Read-only by default (safe for automated pipelines)
const analysis = await query({
  prompt: 'Analyze the auth module for security issues',
  cwd: '/path/to/project'
});

// Explicitly enable write tools when needed
const fix = await query({
  prompt: 'Fix the type errors in src/auth/',
  cwd: '/path/to/project',
  allowTools: ['edit', 'write']  // Opt-in to write access
});

⚠️

Security Best Practice

Only enable write permissions when your workflow specifically requires it. For review, analysis, and reporting tasks, the default read-only mode is sufficient and safer -- especially in CI/CD environments where unintended writes could cause issues.

Integration Patterns

The SDK is designed to add intelligence to existing workflows, not replace them. The most effective patterns involve embedding SDK calls into scripts, hooks, and CI pipelines where Claude Code can analyze context and provide feedback.

1.Hook helpers: Use the SDK inside post-tool hooks to launch a second Claude instance that reviews changes for duplicates or quality issues
2.CI/CD analysis: Add SDK calls to your pipeline to analyze PRs, detect PII exposure, or validate architecture decisions
3.Code generation: Automate boilerplate generation with SDK scripts that read your patterns and produce consistent code
4.Documentation: Generate or update documentation by having the SDK analyze code changes and produce summaries

typescriptUsing the SDK inside a hook for duplicate detection

// Example: Hook that uses SDK to check for duplicates
import { query } from '@anthropic-ai/claude-code';

const toolInput = JSON.parse(await readStdin());
const filePath = toolInput.input?.file_path;

if (filePath?.startsWith('src/queries/')) {
  const result = await query({
    prompt: `Check if ${filePath} duplicates any 
    existing query in src/queries/. If so, report 
    which file it duplicates.`,
    cwd: process.cwd()
  });
  
  if (result.includes('duplicate')) {
    console.error(result);
    process.exit(2);  // Block the edit
  }
}

✨

Best Practice

The SDK works best as a helper embedded in existing workflows -- not as a standalone application. Think of it as adding an intelligent layer to your scripts, hooks, and CI pipelines rather than building entirely new tools around it.

Key Takeaways

✓The Claude Code SDK provides programmatic access via CLI, TypeScript, and Python -- same tools as the interactive terminal
✓Default is read-only for safety; write permissions require explicit opt-in via allowTools
✓Best used as intelligent middleware: embedding SDK calls into hooks, CI pipelines, and automation scripts
✓Key pattern: use SDK inside hooks to launch a second Claude instance for quality checks and duplicate detection
✓Always prefer read-only access in CI/CD; only enable writes when the workflow specifically requires it

Check Your Understanding

Test what you learned in this lesson.

Q1.What permissions does the Claude Code SDK have by default?

Q2.Which SDK interface would you choose for a CI/CD pipeline script?

Q3.How do you enable write permissions in the TypeScript SDK?

Q4.A hook needs to check for duplicate code by launching a second Claude instance. Which approach is correct?

Another Useful Hook

Quiz on Claude Code