Struct Client 

pub struct Client { /* private fields */ }

A stateful Claude Code client that manages a persistent session.

Lifecycle

1. Create with Client::new(config) or Client::with_transport(config, transport)
2. Call connect() to spawn the CLI and read the init message
3. Use send() to send prompts and stream responses
4. Call close() to shut down cleanly

Implementations

impl Client

pub fn new(config: ClientConfig) -> Result<Self>

Create a new client with the given configuration.

This does NOT start the CLI — call connect() next. Validates the config (e.g., cwd existence) and discovers the CLI binary.

Errors

Returns Error::CliNotFound if the CLI binary cannot be discovered, or Error::Config if the configuration is invalid.

pub fn with_transport( config: ClientConfig, transport: Arc<dyn Transport>, ) -> Result<Self>

Create a client with a custom transport (useful for testing).

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

Connect to the CLI and return the session info from the init message.

This spawns the CLI process (or connects to the mock transport) and starts the background reader task. The entire connect sequence (transport connect + init message read) is subject to connect_timeout.

pub fn send( &self, prompt: impl Into<String>, ) -> Result<impl Stream<Item = Result<Message>> + '_>

Send a text prompt and return a stream of response messages.

The stream yields messages until a Result message is received (which terminates the turn).

pub fn send_content( &self, content: Vec<UserContent>, ) -> Result<impl Stream<Item = Result<Message>> + '_>

Send structured content blocks (text + images) and return a stream of response messages.

This is the multi-modal equivalent of send(). Content is serialised as a JSON user message and written to the CLI’s stdin.

Errors

Returns Error::Config if content is empty, or Error::NotConnected if the client is not connected.

pub fn receive_messages( &self, ) -> Result<impl Stream<Item = Result<Message>> + '_>

Return a stream of all incoming messages (without sending a prompt).

Useful for consuming messages from a resumed session.

pub async fn write_to_stdin(&self, text: &str) -> Result<()>

Write raw text to the CLI’s stdin without creating a response stream.

Use this only when [receive_messages()] is already consuming responses. Do not call this while a [send()] turn is in progress — doing so interleaves writes on the same stdin handle and produces undefined protocol behaviour.

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

Send an interrupt signal to the CLI (SIGINT).

pub async fn respond_to_permission( &self, request_id: &str, decision: PermissionDecision, ) -> Result<()>

Respond to a permission request from the CLI.

When the CLI asks for permission to use a tool, this method sends the decision back via the control protocol.

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

Dynamically change the model used for subsequent turns.

Pass None to revert to the session’s default model.

Errors

Returns an error if the CLI rejects the model change or the control protocol fails.

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

Dynamically change the permission mode for the current session.

Errors

Returns an error if the CLI rejects the mode change or the control protocol fails.

pub fn read_timeout(&self) -> Option<Duration>

Returns the configured read timeout.

pub fn session_id(&self) -> Option<&str>

Returns the session ID if connected.

pub fn is_connected(&self) -> bool

Returns true if the client is connected.

pub async fn close(&mut self) -> Result<Option<i32>>

Close the client and shut down the CLI process.

Returns the CLI process exit code if available. After calling this, the Drop warning will not fire.

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.