claude-sdk-rs 🦀

A type-safe, async-first Rust SDK that wraps the Claude Code CLI to provide a powerful programmatic API for interacting with Claude AI. Build AI-powered applications with confidence using Rust's safety guarantees.

📋 Table of Contents

Key Features
Installation
Quick Start
Documentation
Usage Examples
Architecture
Examples
Contributing
Performance
Security
Requirements
License

✨ Key Features

🔒 Type-Safe API - Strongly typed requests and responses with compile-time guarantees
⚡ Async/Await - Built on Tokio for efficient concurrent operations
🔄 Multiple Response Modes - Simple text, full metadata, or streaming responses
💾 Session Management - Persistent conversations with automatic context preservation
🛠️ Tool Integration - Support for MCP (Model Context Protocol) tools and external services
📊 Rich Metadata - Access token usage, costs, session IDs, and timing information
🎯 Comprehensive Error Handling - Detailed error types with actionable messages
⚙️ Flexible Configuration - Builder patterns for intuitive setup
🔐 Granular Permissions - Fine-grained tool access control with Bash(command) and MCP support
🎯 Conversation Control - Limit turns and extend system prompts dynamically
🛡️ Security Features - Configurable permission prompts and tool restrictions

📦 Installation

Prerequisites

Install Claude Code CLI (required for SDK operation):

# Install via npm (recommended)
npm install -g @anthropic-ai/claude-code

# Or install via Homebrew on macOS
brew install claude-code

# Authenticate with your Claude account
claude auth

Verify Installation:

claude --version  # Should show the CLI version
claude auth status  # Should show authentication status

Add to Your Project

Add claude-sdk-rs to your Cargo.toml:

[dependencies]
claude-sdk-rs = "1.0"
tokio = { version = "1.40", features = ["full"] }

Feature Flags

The SDK uses feature flags to provide only the functionality you need:

# Core SDK only (default) - minimal dependencies
claude-sdk-rs = "1.0"

# With CLI binary - adds command-line interface
claude-sdk-rs = { version = "1.0", features = ["cli"] }

# With analytics - usage metrics and performance tracking
claude-sdk-rs = { version = "1.0", features = ["analytics"] }

# With MCP support - Model Context Protocol for tools
claude-sdk-rs = { version = "1.0", features = ["mcp"] }

# With SQLite storage - persistent session management
claude-sdk-rs = { version = "1.0", features = ["sqlite"] }

# Everything enabled - all features
claude-sdk-rs = { version = "1.0", features = ["full"] }

Install CLI Binary

To install the claude-sdk-rs CLI tool globally:

cargo install claude-sdk-rs --features cli

🚀 Quick Start

Basic Usage

use claude_sdk_rs::{Client, Config};

#[tokio::main]
async fn main() -> Result<(), claude_sdk_rs::Error> {
    // Create a client with default configuration
    let client = Client::new(Config::default());
    
    // Send a query and get the response
    let response = client
        .query("Explain Rust ownership in simple terms")
        .send()
        .await?;
    
    println!("Claude says: {}", response);
    Ok(())
}

📚 Documentation

🚀 Quick Start Guide - Get up and running in minutes
🔧 Development Setup - Build from source and contribute
📖 API Documentation - Complete API reference
📂 Examples - Working code examples
🏗️ Architecture - Technical design and internals
🔄 NVM Compatibility - Using with Node Version Manager

💡 Usage Examples

API Patterns: Two Ways to Send Queries

The SDK provides two patterns for sending queries to Claude:

1. Builder Pattern (Recommended for new code)

let response = client.query("Your message").send().await?;
let full_response = client.query("Your message").send_full().await?;
let stream = client.query("Your message").stream().await?;

2. Direct Methods (Backward compatible)

let response = client.send("Your message").await?;
let full_response = client.send_full("Your message").await?;

When to use each pattern:

Use Builder Pattern for new applications - it's more flexible and supports additional configuration per query
Use Direct Methods for simple use cases or when migrating existing code
The builder pattern allows per-query customization (session IDs, output formats, etc.)

Custom Configuration

use claude_sdk_rs::{Client, Config, StreamFormat};

let client = Client::builder()
    .model("claude-3-sonnet-20240229")
    .system_prompt("You are a helpful Rust programming assistant")
    .timeout_secs(60)
    .stream_format(StreamFormat::Json)
    .build();

Enhanced Configuration Options

The SDK now supports advanced configuration features for better control:

use claude_sdk_rs::{Client, ToolPermission};

// Configure with system prompt extension and tool permissions
let client = Client::builder()
    .append_system_prompt("Additionally, be concise in your responses.")
    .max_turns(5)  // Limit conversation turns
    .disallowed_tools(vec![
        "Bash(rm)".to_string(),          // Block specific bash commands
        "mcp__dangerous__delete".to_string(), // Block MCP tools
    ])
    .skip_permissions(false)  // Require permission prompts
    .build();

// Tool-specific permissions
let tools_client = Client::builder()
    .allowed_tools(vec![
        ToolPermission::bash("git").to_cli_format(),
        ToolPermission::mcp("filesystem", "read").to_cli_format(),
        ToolPermission::All.to_cli_format(), // Allow all tools
    ])
    .build();

Get Full Response Metadata

// Get response with metadata
let response = client
    .query("Write a haiku about Rust")
    .send_full()
    .await?;

println!("Response: {}", response.content);
if let Some(metadata) = response.metadata {
    println!("Cost: ${:.6}", metadata.cost_usd.unwrap_or(0.0));
    println!("Tokens: {:?}", metadata.tokens_used);
    println!("Session: {}", metadata.session_id);
}

Streaming Responses

use futures::StreamExt;

let mut stream = client
    .query("Write a short story about a robot")
    .stream()
    .await?;

while let Some(chunk) = stream.next().await {
    match chunk {
        Ok(message) => {
            if let Some(content) = message.content {
                print!("{}", content);
            }
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

Session Management

// Sessions are automatically managed - context is preserved
let client = Client::builder()
    .stream_format(StreamFormat::Json)
    .build();

// First message
let response1 = client
    .query("My name is Alice and I love Rust programming")
    .send_full()
    .await?;

// Claude remembers the context
let response2 = client
    .query("What's my favorite programming language?")
    .send()
    .await?;
// Response: "Based on our conversation, your favorite programming language is Rust!"

Error Handling

use claude_sdk_rs::Error;

match client.query("Hello").send().await {
    Ok(response) => println!("Success: {}", response),
    Err(Error::BinaryNotFound) => {
        eprintln!("Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code");
    }
    Err(Error::ProcessError(msg)) => {
        eprintln!("Process error: {}", msg);
    }
    Err(Error::Timeout) => {
        eprintln!("Request timed out");
    }
    Err(e) => eprintln!("Other error: {}", e),
}

🏗️ Architecture

The SDK is built as a single crate with modular organization and feature flags:

claude-sdk-rs/
├── src/
│   ├── lib.rs          # Main SDK public API
│   ├── core/           # Core types, config, errors
│   ├── runtime/        # Process execution and streaming
│   ├── mcp/            # Model Context Protocol (feature: mcp)
│   └── cli/            # CLI interface (feature: cli)
├── examples/           # Working examples
├── tests/              # Integration tests
└── benches/            # Performance benchmarks

Feature Flags

Default: Core SDK functionality with no extra dependencies
cli: Adds command-line interface and interactive features
mcp: Enables Model Context Protocol for tool integration
sqlite: Adds SQLite-based session persistence
analytics: Enables usage analytics (requires cli)
full: Enables all features

🧪 Examples

Explore the examples/ directory for complete working examples:

basic_usage.rs - Simple queries and configuration
streaming.rs - Real-time streaming responses
session_management.rs - Multi-turn conversations
error_handling.rs - Comprehensive error handling
configuration.rs - Advanced configuration options
system_prompts.rs - System prompt extension and conversation control NEW
advanced_permissions.rs - Granular tool permissions and security NEW
session_persistence.rs - SQLite-based session storage (requires sqlite feature)
cli_interactive.rs - Interactive CLI usage (requires cli feature)

Run examples:

# Basic examples
cargo run --example basic_usage
cargo run --example streaming

# New features - advanced configuration
cargo run --example system_prompts
cargo run --example advanced_permissions

# Examples requiring features
cargo run --example session_persistence --features sqlite
cargo run --example cli_interactive --features cli

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repository
git clone https://github.com/bredmond1019/claude-sdk-rust.git
cd claude-sdk-rust

# Build the crate
cargo build

# Build with all features
cargo build --all-features

# Run tests
cargo test

# Run tests with all features
cargo test --all-features

# Run linter
cargo clippy --all-features

# Format code
cargo fmt

# Run benchmarks
cargo bench

📈 Performance

The SDK is designed for minimal overhead:

Zero-cost abstractions over the Claude CLI
Efficient streaming with backpressure handling
Connection pooling for concurrent requests
Optimized JSON parsing with serde

🔒 Security

Never logs sensitive data or API responses
Secure process execution with proper isolation
Input validation and sanitization
See SECURITY.md for security policy

📋 Requirements

Rust: 1.70 or later
Claude Code CLI: Must be installed and authenticated
Operating Systems: Linux, macOS, Windows
Architecture: x86_64, ARM64

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

🚀 Quick Start • 🔧 Dev Setup • 📖 API Docs • 💬 Discussions

Made with ❤️ for the Rust community

claude-sdk-rs 1.0.0

claude-sdk-rs 🦀

📋 Table of Contents

✨ Key Features

📦 Installation

Prerequisites

Add to Your Project

Feature Flags

Install CLI Binary

🚀 Quick Start

Basic Usage

📚 Documentation

💡 Usage Examples

API Patterns: Two Ways to Send Queries

Custom Configuration

Enhanced Configuration Options

Get Full Response Metadata

Streaming Responses

Session Management

Error Handling

🏗️ Architecture

Feature Flags

🧪 Examples

🤝 Contributing

Development

📈 Performance

🔒 Security

📋 Requirements

📜 License

🔗 Links