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

📦 Installation

Prerequisites

1. Install Claude Code CLI (required for SDK operation):

   # Visit https://claude.ai/code for installation
   # Or use the official installer:
   curl -fsSL https://claude.ai/install.sh | sh
   
   # Authenticate with your Claude account
   claude auth
   

2. 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

💡 Usage Examples

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();

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 from https://claude.ai/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
• 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

# 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

• GitHub Repository
• Crates.io Package
• API Documentation
• Claude Code CLI
• Issue Tracker