claude-cli-sdk

English | 简体中文 | 日本語 | 한국어 | Español

Strongly-typed, async-first Rust SDK for building agents on the Claude Code CLI.

Features

• One-shot queries — query() sends a prompt and collects all response messages
• Streaming — query_stream() yields messages as they arrive
• Multi-turn sessions — Client with send() / receive_messages() for persistent conversations
• Multimodal input — send images (URL or base64) alongside text via query_with_content()
• Permission callbacks — CanUseToolCallback for programmatic per-tool approval/denial
• 8 lifecycle hooks — PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification
• Extended thinking — max_thinking_tokens to enable chain-of-thought reasoning
• Fallback model — fallback_model for automatic model failover
• Dynamic control — set_model() and set_permission_mode() mid-session
• Cooperative cancellation — CancellationToken for graceful early termination
• Message callback — observe, transform, or filter messages before they reach your code
• Stderr callback — capture CLI debug output for logging/diagnostics
• MCP server config — attach external Model Context Protocol servers
• Testing framework — MockTransport, ScenarioBuilder, and message builders for unit tests without a live CLI
• Cross-platform — macOS, Linux, and Windows

Quick Start

[dependencies]
claude-cli-sdk = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use claude_cli_sdk::{query, ClientConfig};

#[tokio::main]
async fn main() -> claude_cli_sdk::Result<()> {
    let config = ClientConfig::builder()
        .prompt("What is Rust?")
        .build();

    let messages = query(config).await?;

    for msg in &messages {
        if let Some(text) = msg.assistant_text() {
            println!("{text}");
        }
    }
    Ok(())
}

Architecture

┌──────────┐    ┌──────────────┐    ┌───────────┐    ┌─────────────┐    ┌───────────┐
│ Your Code │───▶│ ClientConfig │───▶│  Client   │───▶│  Transport  │───▶│ Claude    │
│           │    │              │    │           │    │ (CliTransport│    │ Code CLI  │
│ query()   │    │ model        │    │ connect() │    │  or Mock)   │    │           │
│ query_    │    │ hooks        │    │ send()    │    │             │    │ NDJSON    │
│  stream() │    │ permissions  │    │ close()   │    │ stdin/stdout│───▶│ stdio     │
│ Client    │    │ callbacks    │    │ set_model()│   │ NDJSON      │    │ protocol  │
└──────────┘    └──────────────┘    └───────────┘    └─────────────┘    └───────────┘
                                          │                                    │
                                          ▼                                    ▼
                                    Background task               Claude API (Anthropic)
                                    routes: hooks,
                                    permissions,
                                    callbacks

Examples

All examples are runnable with cargo run --example <name>. They require a working Claude Code CLI installation.

Core API

One-shot query

use claude_cli_sdk::{query, ClientConfig};

let config = ClientConfig::builder()
    .prompt("List the files in /tmp")
    .build();

let messages = query(config).await?;

Streaming

use claude_cli_sdk::{query_stream, ClientConfig};
use tokio_stream::StreamExt;

let config = ClientConfig::builder()
    .prompt("Explain ownership in Rust")
    .model("claude-opus-4-6")
    .build();

let stream = query_stream(config).await?;
tokio::pin!(stream);

while let Some(msg) = stream.next().await {
    let msg = msg?;
    if let Some(text) = msg.assistant_text() {
        print!("{text}");
    }
}

Multi-turn sessions

use claude_cli_sdk::{Client, ClientConfig, Message};
use tokio_stream::StreamExt;

let config = ClientConfig::builder()
    .prompt("Start a Rust project")
    .build();

let mut client = Client::new(config)?;
let session_info = client.connect().await?;
println!("Session: {}", session_info.session_id);

// First turn (prompt sent via config).
{
    let stream = client.receive_messages()?;
    tokio::pin!(stream);
    while let Some(msg) = stream.next().await {
        let msg = msg?;
        if let Some(text) = msg.assistant_text() {
            print!("{text}");
        }
        if matches!(msg, Message::Result(_)) {
            break;
        }
    }
}

// Subsequent turns.
{
    let stream = client.send("Now add a test suite")?;
    tokio::pin!(stream);
    while let Some(msg) = stream.next().await {
        if let Some(text) = msg?.assistant_text() {
            print!("{text}");
        }
    }
}

client.close().await?;

Advanced Features

Permission callbacks

use claude_cli_sdk::{ClientConfig, PermissionDecision, PermissionContext};
use std::sync::Arc;

let config = ClientConfig::builder()
    .prompt("Edit main.rs")
    .can_use_tool(Arc::new(|tool_name: &str, _input: &serde_json::Value, _ctx: PermissionContext| {
        let tool_name = tool_name.to_owned();
        Box::pin(async move {
            if tool_name.starts_with("Read") || tool_name.starts_with("Write") {
                PermissionDecision::allow()
            } else {
                PermissionDecision::deny("Only file tools are allowed")
            }
        })
    }))
    .build();

Lifecycle hooks

Register callbacks for 8 lifecycle events:

use claude_cli_sdk::{ClientConfig, HookMatcher, HookEvent, HookOutput};
use std::sync::Arc;

let config = ClientConfig::builder()
    .prompt("Refactor auth module")
    .hooks(vec![
        HookMatcher::new(HookEvent::PreToolUse, Arc::new(|input, _session, _ctx| {
            Box::pin(async move {
                eprintln!("Tool: {:?}", input.tool_name);
                HookOutput::allow()
            })
        })).for_tool("Bash"),
    ])
    .build();

Multimodal (images)

use claude_cli_sdk::{query_with_content, ClientConfig, UserContent};

let content = vec![
    UserContent::image_url("https://example.com/diagram.png", "image/png")?,
    UserContent::text("Describe this diagram"),
];
let messages = query_with_content(content, config).await?;

Also supports base64-encoded images via UserContent::image_base64(). Accepted MIME types: image/jpeg, image/png, image/gif, image/webp. Maximum base64 payload: 15 MiB.

Extended thinking

let config = ClientConfig::builder()
    .prompt("Solve this step by step")
    .max_thinking_tokens(10_000_u32)
    .build();

Thinking blocks appear as ContentBlock::Thinking in the response:

use claude_cli_sdk::ContentBlock;

for block in &assistant.message.content {
    if let ContentBlock::Thinking(t) = block {
        println!("Thinking: {}", t.thinking);
    }
}

Fallback model

let config = ClientConfig::builder()
    .prompt("Complex task")
    .model("claude-sonnet-4-5")
    .fallback_model("claude-haiku-4-5")
    .build();

Dynamic control

Change model or permission mode mid-session:

// Switch model during a conversation
client.set_model(Some("claude-haiku-4-5")).await?;

// Revert to session default
client.set_model(None).await?;

// Change permission mode
client.set_permission_mode(PermissionMode::AcceptEdits).await?;

// Send interrupt signal (SIGINT)
client.interrupt().await?;

Message callback

Observe, transform, or filter messages before they reach your code:

use claude_cli_sdk::{ClientConfig, Message, MessageCallback};
use std::sync::Arc;

let callback: MessageCallback = Arc::new(|msg: Message| {
    eprintln!("received: {msg:?}");
    Some(msg) // pass through (return None to filter out)
});

let config = ClientConfig::builder()
    .prompt("Hello")
    .message_callback(callback)
    .build();

Cancellation

use claude_cli_sdk::{query_stream, CancellationToken, ClientConfig};

let token = CancellationToken::new();
let config = ClientConfig::builder()
    .prompt("Long task")
    .cancellation_token(token.clone())
    .build();

// Cancel from another task:
token.cancel();

// Stream will yield Error::Cancelled, checkable via:
if error.is_cancelled() { /* handle gracefully */ }

MCP servers

use claude_cli_sdk::{ClientConfig, McpServerConfig, McpServers};

let mut servers = McpServers::new();
servers.insert(
    "filesystem".into(),
    McpServerConfig::new("npx")
        .with_args(["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]),
);

let config = ClientConfig::builder()
    .prompt("List files using the filesystem MCP server")
    .mcp_servers(servers)
    .build();

Stderr debugging

Capture the CLI's stderr output for diagnostics:

use std::sync::Arc;

let config = ClientConfig::builder()
    .prompt("Debug this")
    .verbose(true)
    .stderr_callback(Arc::new(|line: String| {
        eprintln!("[stderr] {line}");
    }))
    .build();

ClientConfig Reference

Set any Option<Duration> timeout to None to wait indefinitely.

Python SDK Comparison

Testing

Enable the testing feature for unit tests without a live CLI:

[dev-dependencies]
claude-cli-sdk = { version = "0.1", features = ["testing"] }

use std::sync::Arc;
use claude_cli_sdk::Client;
use claude_cli_sdk::config::ClientConfig;
use claude_cli_sdk::testing::{ScenarioBuilder, assistant_text};

let transport = ScenarioBuilder::new("test-session")
    .exchange(vec![assistant_text("Hello!")])
    .build();
let transport = Arc::new(transport);

let mut client = Client::with_transport(
    ClientConfig::builder().prompt("test").build(),
    transport,
).unwrap();

ScenarioBuilder queues init + exchange messages so your tests exercise real Client logic without spawning a CLI process.

Troubleshooting

Feature Flags

Platform Support

macOS, Linux, and Windows.

Disclaimer

This is an unofficial SDK, community-developed by the POM team, and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic. This crate interacts with the Claude Code CLI but does not contain any Anthropic proprietary code.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.