Crate claude_sdk_rs

Source
Expand description

§claude-sdk-rs - Rust SDK for Claude Code

A comprehensive, type-safe, async-first Rust SDK that provides both programmatic access to Claude AI and CLI interactive features. This crate transforms the Claude Code CLI tool into a powerful library while also offering standalone CLI capabilities.

§Features

claude-sdk-rs is designed with modularity in mind, using feature flags to provide only the functionality you need:

§Core Features (Always Available)

  • Async-first API: Built on tokio for high-performance async operations
  • Type-safe responses: Structured data types for all API responses
  • Multiple response formats: Text, JSON, and streaming JSON support
  • Session management: Persistent conversation contexts
  • Error handling: Comprehensive error types with detailed messages
  • Configuration: Flexible configuration with builder pattern

§Optional Features

§cli - Command Line Interface

Enables the CLI binary and interactive features:

[dependencies]
claude-sdk-rs = { version = "1.0", features = ["cli"] }
  • Interactive command-line interface
  • Command parsing and execution
  • Configuration management
  • Session switching and management
§analytics - Usage Analytics and Metrics

Includes the CLI feature plus analytics capabilities:

[dependencies]
claude-sdk-rs = { version = "1.0", features = ["analytics"] }
  • Usage tracking and metrics collection
  • Cost analysis and reporting
  • Performance monitoring
  • Interactive dashboards
  • Data export capabilities
§mcp - Model Context Protocol

Enables MCP server and client functionality:

[dependencies]
claude-sdk-rs = { version = "1.0", features = ["mcp"] }
  • MCP server implementation
  • Tool integration capabilities
  • External service connections
  • Protocol message handling
§sqlite - SQLite Storage Backend

Adds SQLite support for persistent storage:

[dependencies]
claude-sdk-rs = { version = "1.0", features = ["sqlite"] }
  • Persistent session storage
  • Query history and analytics
  • Configuration persistence
§full - All Features Enabled

Convenience feature that enables everything:

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

§Architecture Overview

The SDK is organized into several core modules:

§Core Module (core)

Contains fundamental types and configuration:

  • Config - SDK configuration with builder pattern
  • Error - Comprehensive error handling
  • Message - Request/response message types
  • Session - Conversation session management
  • StreamFormat - Response format configuration

§Runtime Module (runtime)

Handles Claude Code CLI interaction:

§CLI Module (cli) - Feature Gated

Command-line interface implementation:

  • Interactive shell and command processing
  • Configuration management utilities
  • Session switching and management

§MCP Module (mcp) - Feature Gated

Model Context Protocol implementation:

  • Server and client implementations
  • Tool integration framework
  • External service connections

§Quick Start Examples

§Basic SDK Usage

use claude_sdk_rs::{Client, Config};

#[tokio::main]
async fn main() -> Result<(), claude_sdk_rs::Error> {
    // Create client with default configuration
    let client = Client::new(Config::default());
     
    // Send a simple query
    let response = client
        .query("Write a hello world program in Rust")
        .send()
        .await?;
     
    println!("Claude's response: {}", response);
    Ok(())
}

§Advanced Configuration

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

#[tokio::main]
async fn main() -> Result<(), claude_sdk_rs::Error> {
    // Build custom configuration
    let config = Config::builder()
        .model("claude-3-sonnet-20240229")
        .system_prompt("You are a helpful coding assistant.")
        .timeout_secs(60)
        .stream_format(StreamFormat::Json)
        .build();

    let client = Client::new(config);
     
    // Get full response with metadata
    let response = client
        .query("Explain Rust ownership")
        .send_full()
        .await?;
     
    println!("Response: {}", response.content);
    if let Some(metadata) = response.metadata {
        println!("Cost: ${:.6}", metadata.cost_usd.unwrap_or(0.0));
        println!("Session: {}", metadata.session_id);
    }
    Ok(())
}

§Streaming Responses

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

#[tokio::main]
async fn main() -> Result<(), claude_sdk_rs::Error> {
    let client = Client::builder()
        .stream_format(StreamFormat::StreamJson)
        .build();
     
    let mut stream = client
        .query("Write a short story about a robot")
        .stream()
        .await?;

    // Process streaming response
    while let Some(message) = stream.next().await {
        match message {
            Ok(msg) => {
                if let Some(content) = msg.content {
                    print!("{}", content);
                }
                if msg.stop_reason.is_some() {
                    break;
                }
            }
            Err(e) => eprintln!("Stream error: {}", e),
        }
    }
    Ok(())
}

§Session Management

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

#[tokio::main]
async fn main() -> Result<(), claude_sdk_rs::Error> {
    let client = Client::builder()
        .stream_format(StreamFormat::Json) // Needed for session metadata
        .build();
     
    // Start a conversation
    let response1 = client
        .query("Hello! My name is Alice and I'm learning Rust.")
        .send_full()
        .await?;
     
    println!("Response 1: {}", response1.content);
     
    // Continue in the same session - Claude remembers context
    let response2 = client
        .query("What's my name?")
        .send_full()
        .await?;
     
    println!("Response 2: {}", response2.content);
    // Should respond with "Alice"
    Ok(())
}

§Error Handling

The SDK provides comprehensive error handling with the Error enum:

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

#[tokio::main]
async fn main() {
    let client = Client::new(Config::default());
     
    match client.query("Hello").send().await {
        Ok(response) => println!("Success: {}", response),
        Err(Error::ProcessError(e)) => {
            eprintln!("Claude CLI process error: {}", e);
        }
        Err(Error::SerializationError(e)) => {
            eprintln!("JSON parsing error: {}", e);
        }
        Err(Error::BinaryNotFound) => {
            eprintln!("Claude CLI not found. Please install from https://claude.ai/code");
        }
        Err(Error::Timeout) => {
            eprintln!("Request timed out. Consider increasing timeout_secs in Config");
        }
        Err(e) => eprintln!("Other error: {}", e),
    }
}

§CLI Usage

When the cli feature is enabled, you can use the binary:

# Install with CLI features
cargo install claude-sdk-rs --features cli

# Interactive mode
claude-sdk-rs

# Direct query
claude-sdk-rs query "What is Rust?"

# With analytics (requires 'analytics' feature)
claude-sdk-rs analytics dashboard

§Performance and Best Practices

§Configuration Optimization

  • Use appropriate timeout values for your use case
  • Choose the right StreamFormat for your needs:
    • Text: Fastest, raw output
    • Json: Structured data with metadata
    • StreamJson: Real-time streaming with metadata

§Error Handling

  • Always handle Error::BinaryNotFound to guide users to install Claude CLI
  • Implement retry logic for transient failures
  • Use appropriate timeout values

§Memory Management

  • Reuse Client instances when possible
  • Process streaming responses incrementally for large outputs
  • Use Config::builder() to avoid unnecessary allocations

§Security Considerations

  • Never log or store API responses containing sensitive data
  • Use environment variables for configuration in production
  • Validate user input before sending to Claude

§Compatibility and Requirements

  • Rust Version: 1.70 or later (MSRV)
  • Claude Code CLI: Must be installed and authenticated
  • Runtime: Requires tokio async runtime
  • Platforms: Linux, macOS, Windows

§Examples

For more comprehensive examples, see the examples/ directory:

  • basic_usage.rs - Simple SDK usage patterns
  • streaming.rs - Real-time streaming responses
  • error_handling.rs - Comprehensive error handling
  • configuration.rs - Advanced configuration options
  • session_management.rs - Multi-turn conversations
  • cli_interactive.rs - CLI interactive features (requires cli feature)
  • cli_analytics.rs - Analytics and metrics (requires analytics feature)

Re-exports§

pub use crate::core::ClaudeResponse;
pub use crate::core::Config;
pub use crate::core::Cost;
pub use crate::core::Error;
pub use crate::core::Message;
pub use crate::core::MessageMeta;
pub use crate::core::MessageType;
pub use crate::core::ResponseMetadata;
pub use crate::core::Result;
pub use crate::core::Session;
pub use crate::core::SessionId;
pub use crate::core::SessionManager;
pub use crate::core::StreamFormat;
pub use crate::core::TokenUsage;
pub use crate::core::ToolPermission;
pub use crate::runtime::Client;
pub use crate::runtime::MessageStream;
pub use crate::runtime::QueryBuilder;

Modules§

cli
Interactive CLI for managing multiple Claude sessions and agents in parallel.
core
Core types, configuration, and error handling for the Claude AI SDK.
prelude
Prelude module for convenient imports
runtime
Runtime execution and process management for the Claude AI SDK.