Claude Code SDK

admin

May 19, 2025 - 20:45

0 0

The Claude Code SDK allows developers to programmatically integrate Claude Code into their applications. It enables running Claude Code as a subprocess, providing a way to build AI-powered coding assistants and tools that leverage Claude’s capabilities.

The SDK currently support command line usage. TypeScript and Python SDKs are coming soon.

Basic SDK usage

The Claude Code SDK allows you to use Claude Code in non-interactive mode from your applications. Here’s a basic example:

Advanced usage

Multi-turn conversations

For multi-turn conversations, you can resume conversations or continue from the most recent session:

Custom system prompts

You can provide custom system prompts to guide Claude’s behavior:

You can also append instructions to the default system prompt:

MCP Configuration

The Model Context Protocol (MCP) allows you to extend Claude Code with additional tools and resources from external servers. Using the --mcp-config flag, you can load MCP servers that provide specialized capabilities like database access, API integrations, or custom tooling.

Create a JSON configuration file with your MCP servers:

Then use it with Claude Code:

Note: When using MCP tools, you must explicitly allow them using the --allowedTools flag. MCP tool names follow the pattern mcp____ where:

serverName is the key from your MCP configuration file
toolName is the specific tool provided by that server

This security measure ensures that MCP tools are only used when explicitly permitted.

Available CLI options

The SDK leverages all the CLI options available in Claude Code. Here are the key ones for SDK usage:

Flag	Description	Example
`--print`, `-p`	Run in non-interactive mode	`claude -p "query"`
`--output-format`	Specify output format (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Resume a conversation by session ID	`claude --resume abc123`
`--continue`, `-c`	Continue the most recent conversation	`claude --continue`
`--verbose`	Enable verbose logging	`claude --verbose`
`--max-turns`	Limit agentic turns in non-interactive mode	`claude --max-turns 3`
`--system-prompt`	Override system prompt (only with `--print`)	`claude --system-prompt "Custom instruction"`
`--append-system-prompt`	Append to system prompt (only with `--print`)	`claude --append-system-prompt "Custom instruction"`
`--allowedTools`	Comma/space-separated list of allowed tools (includes MCP tools)	`claude --allowedTools "Bash(npm install),mcp__filesystem__*"`
`--disallowedTools`	Comma/space-separated list of denied tools	`claude --disallowedTools "Bash(git commit),mcp__github__*"`
`--mcp-config`	Load MCP servers from a JSON file	`claude --mcp-config servers.json`
`--permission-prompt-tool`	MCP tool for handling permission prompts (only with `--print`)	`claude --permission-prompt-tool mcp__auth__prompt`

For a complete list of CLI options and features, see the CLI usage documentation.

Output formats

The SDK supports multiple output formats:

Text output (default)

Returns just the response text:

JSON output

Returns structured data including metadata:

Response format:

Streaming JSON output

Streams each message as it is received:

Each conversation begins with an initial init system message, followed by a list of user and assistant messages, followed by a final result system message with stats. Each message is emitted as a separate JSON object.

Message schema

Messages returned from the JSON API are strictly typed according to the following schema:

We will soon publish these types in a JSONSchema-compatible format. We use semantic versioning for the main Claude Code package to communicate breaking changes to this format.

Examples

Simple script integration

Processing files with Claude

Session management

Best practices

Use JSON output format for programmatic parsing of responses:
Handle errors gracefully - check exit codes and stderr:
Use session management for maintaining context in multi-turn conversations
Consider timeouts for long-running operations:
Respect rate limits when making multiple requests by adding delays between calls

Real-world applications

The Claude Code SDK enables powerful integrations with your development workflow. One notable example is the Claude Code GitHub Actions, which uses the SDK to provide automated code review, PR creation, and issue triage capabilities directly in your GitHub workflow.