Struct ClaudeSDKClient 

pub struct ClaudeSDKClient { /* private fields */ }

Interactive client for bidirectional communication with Claude

ClaudeSDKClient provides a stateful, interactive interface for communicating with Claude Code CLI. Unlike the simple query function, this client supports:

• Bidirectional communication
• Multiple sessions
• Interrupt capabilities
• State management
• Follow-up messages based on responses

Example

use cc_sdk::{ClaudeSDKClient, ClaudeCodeOptions, Message, Result};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<()> {
    let options = ClaudeCodeOptions::builder()
        .system_prompt("You are a helpful assistant")
        .model("claude-3-opus-20240229")
        .build();

    let mut client = ClaudeSDKClient::new(options);

    // Connect with initial prompt
    client.connect(Some("Hello!".to_string())).await?;

    // Receive initial response
    let mut messages = client.receive_messages().await;
    while let Some(msg) = messages.next().await {
        match msg? {
            Message::Result { .. } => break,
            msg => println!("{:?}", msg),
        }
    }

    // Send follow-up
    client.send_request("What's 2 + 2?".to_string(), None).await?;

    // Receive response
    let mut messages = client.receive_messages().await;
    while let Some(msg) = messages.next().await {
        println!("{:?}", msg?);
    }

    // Disconnect
    client.disconnect().await?;

    Ok(())
}

Implementations

impl ClaudeSDKClient

pub fn new(options: ClaudeCodeOptions) -> Self

Create a new client with the given options

pub fn with_transport( options: ClaudeCodeOptions, transport: Box<dyn Transport + Send>, ) -> Self

Create a new client with a custom transport implementation

This allows users to provide their own Transport implementation instead of using the default SubprocessTransport. Useful for testing, custom CLI paths, or alternative communication mechanisms.

Arguments

• options - Configuration options for the client
• transport - Custom transport implementation

Example

let options = ClaudeCodeOptions::default();
let transport = SubprocessTransport::with_cli_path(options.clone(), "/custom/path/claude-code");
let client = ClaudeSDKClient::with_transport(options, Box::new(transport));

pub async fn connect(&mut self, initial_prompt: Option<String>) -> Result<()>

Connect to Claude CLI with an optional initial prompt

pub async fn send_user_message(&mut self, prompt: String) -> Result<()>

Send a user message to Claude

pub async fn send_request( &mut self, prompt: String, _session_id: Option<String>, ) -> Result<()>

Send a request to Claude (alias for send_user_message with optional session_id)

pub async fn receive_messages( &mut self, ) -> impl Stream<Item = Result<Message>> + use<>

Receive messages from Claude

Returns a stream of messages. The stream will end when a Result message is received or the connection is closed.

pub async fn interrupt(&mut self) -> Result<()>

Send an interrupt request

pub async fn is_connected(&self) -> bool

Check if the client is connected

pub async fn get_sessions(&self) -> Vec<String>

Get active session IDs

pub async fn receive_response( &mut self, ) -> Pin<Box<dyn Stream<Item = Result<Message>> + Send + '_>>

Receive messages until and including a ResultMessage

This is a convenience method that collects all messages from a single response. It will automatically stop after receiving a ResultMessage.

pub async fn get_server_info(&self) -> Option<Value>

Get server information

Returns initialization information from the Claude Code server including:

• Available commands
• Current and available output styles
• Server capabilities

pub async fn set_permission_mode(&mut self, mode: &str) -> Result<()>

Set permission mode dynamically

Changes the permission mode during an active session. Requires control protocol to be enabled (via can_use_tool, hooks, or mcp_servers).

Arguments

• mode - Permission mode: “default”, “acceptEdits”, “plan”, or “bypassPermissions”

Example

let mut client = ClaudeSDKClient::new(ClaudeCodeOptions::default());
client.connect(None).await?;

// Switch to accept edits mode
client.set_permission_mode("acceptEdits").await?;

pub async fn set_model(&mut self, model: Option<String>) -> Result<()>

Set model dynamically

Changes the active model during an active session. Requires control protocol to be enabled (via can_use_tool, hooks, or mcp_servers).

Arguments

• model - Model identifier (e.g., “claude-3-5-sonnet-20241022”) or None to use default

Example

let mut client = ClaudeSDKClient::new(ClaudeCodeOptions::default());
client.connect(None).await?;

// Switch to a different model
client.set_model(Some("claude-3-5-sonnet-20241022".to_string())).await?;

pub async fn query( &mut self, prompt: String, session_id: Option<String>, ) -> Result<()>

Send a query with optional session ID

This method is similar to Python SDK’s query method in ClaudeSDKClient

pub async fn disconnect(&mut self) -> Result<()>

Disconnect from Claude CLI

pub async fn get_usage_stats(&self) -> TokenUsageTracker

Get token usage statistics

Returns the current token usage tracker with cumulative statistics for all queries executed by this client.

pub async fn set_budget_limit( &self, limit: BudgetLimit, on_warning: Option<BudgetWarningCallback>, )

Set budget limit with optional warning callback

Arguments

• limit - Budget limit configuration (cost and/or token caps)
• on_warning - Optional callback function triggered when usage exceeds warning threshold

Example

use cc_sdk::{ClaudeSDKClient, ClaudeCodeOptions};
use cc_sdk::token_tracker::{BudgetLimit, BudgetWarningCallback};
use std::sync::Arc;

let mut client = ClaudeSDKClient::new(ClaudeCodeOptions::default());

// Set budget with callback
let cb: BudgetWarningCallback = Arc::new(|msg: &str| println!("Budget warning: {}", msg));
client.set_budget_limit(BudgetLimit::with_cost(5.0), Some(cb)).await;

pub async fn clear_budget_limit(&self)

Clear budget limit and reset warning state

pub async fn reset_usage_stats(&self)

Reset token usage statistics to zero

Clears all accumulated token and cost statistics. Budget limits remain in effect.

pub async fn is_budget_exceeded(&self) -> bool

Check if budget has been exceeded

Returns true if current usage exceeds any configured limits

Trait Implementations

impl Drop for ClaudeSDKClient

fn drop(&mut self)

Executes the destructor for this type.