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 get_account_info(&mut self) -> Result<String>

Get account information

This method attempts to retrieve Claude account information through multiple methods:

1. From environment variable ANTHROPIC_USER_EMAIL
2. From Claude CLI config file (if accessible)
3. By querying the CLI with /status command (interactive mode)

Returns

A string containing the account information, or an error if unavailable.

Example

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

match client.get_account_info().await {
    Ok(info) => println!("Account: {}", info),
    Err(_) => println!("Account info not available"),
}

Note

Account information may not always be available in SDK mode. Consider setting the ANTHROPIC_USER_EMAIL environment variable for reliable account identification.

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, mcp_servers, or file checkpointing).

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, mcp_servers, or file checkpointing).

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 rewind_files(&mut self, user_message_id: &str) -> Result<()>

Rewind tracked files to their state at a specific user message

Requires enable_file_checkpointing to be enabled in ClaudeCodeOptions. This method allows you to undo file changes made during the session by reverting them to their state at any previous user message checkpoint.

Arguments

• user_message_id - UUID of the user message to rewind to. This should be the uuid field from a message received during the conversation.

Example

let options = ClaudeCodeOptions::builder()
    .enable_file_checkpointing(true)
    .build();
let mut client = ClaudeSDKClient::new(options);
client.connect(None).await?;

// Ask Claude to make some changes
client.send_request("Make some changes to my files".to_string(), None).await?;

// ... later, rewind to a checkpoint
// client.rewind_files("user-message-uuid-here").await?;

Errors

Returns an error if:

• The client is not connected
• The query handler is not initialized (control protocol required)
• File checkpointing is not enabled
• The specified user_message_id is invalid

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.