claude_code/
lib.rs

1//! # Claude Code SDK for Rust
2//!
3//! A Rust implementation of the Claude Code Agent SDK, providing programmatic access
4//! to Claude Code as a subprocess. This crate is a port of the official
5//! [Python Claude Code SDK](https://platform.claude.com/docs/en/agent-sdk/python).
6//!
7//! ## Overview
8//!
9//! The SDK provides two main ways to interact with Claude Code:
10//!
11//! - **[`query()`]** — Creates a new session for each interaction. Best for one-off tasks,
12//!   independent operations, and simple automation scripts.
13//! - **[`ClaudeSdkClient`]** — Maintains a conversation session across multiple exchanges.
14//!   Best for continuing conversations, follow-up questions, interactive applications, and
15//!   session lifecycle management.
16//!
17//! ## Quick Comparison
18//!
19//! | Feature | `query()` | `ClaudeSdkClient` |
20//! |---------|-----------|-------------------|
21//! | Session | New session each time | Reuses same session |
22//! | Conversation | Single exchange | Multiple exchanges in same context |
23//! | Connection | Managed automatically | Manual control |
24//! | Interrupts | Not supported | Supported |
25//! | Custom Tools | Supported | Supported |
26//! | Use Case | One-off tasks | Continuous conversations |
27//!
28//! ## Example — One-off query
29//!
30//! ```rust,no_run
31//! use claude_code::{query, ClaudeAgentOptions, InputPrompt, Message};
32//!
33//! # async fn example() -> claude_code::Result<()> {
34//! let messages = query(
35//!     InputPrompt::Text("What is 2 + 2?".to_string()),
36//!     Some(ClaudeAgentOptions {
37//!         permission_mode: Some(claude_code::PermissionMode::BypassPermissions),
38//!         ..Default::default()
39//!     }),
40//!     None,
41//! ).await?;
42//!
43//! for msg in messages {
44//!     if let Message::Assistant(assistant) = msg {
45//!         println!("{:?}", assistant.content);
46//!     }
47//! }
48//! # Ok(())
49//! # }
50//! ```
51//!
52//! ## Example — Continuous conversation with `ClaudeSdkClient`
53//!
54//! ```rust,no_run
55//! use claude_code::{ClaudeSdkClient, InputPrompt};
56//!
57//! # async fn example() -> claude_code::Result<()> {
58//! let mut client = ClaudeSdkClient::new(None, None);
59//! client.connect(None).await?;
60//!
61//! // First question
62//! client.query(InputPrompt::Text("What's the capital of France?".into()), "default").await?;
63//! let response = client.receive_response().await?;
64//!
65//! // Follow-up — session retains context
66//! client.query(InputPrompt::Text("What's the population of that city?".into()), "default").await?;
67//! let follow_up = client.receive_response().await?;
68//!
69//! client.disconnect().await?;
70//! # Ok(())
71//! # }
72//! ```
73
74pub mod client;
75pub mod errors;
76pub mod internal_client;
77pub mod message_parser;
78pub mod query;
79pub mod query_fn;
80pub mod sdk_mcp;
81pub mod transport;
82pub mod types;
83
84pub use client::{ClaudeSdkClient, InputPrompt};
85pub use errors::{
86    CLIConnectionError, CLIJSONDecodeError, CLINotFoundError, ClaudeSDKError, Error,
87    MessageParseError, ProcessError, Result,
88};
89pub use message_parser::parse_message;
90pub use query::{Query, handle_sdk_mcp_request};
91pub use query_fn::{query, query_from_stream, query_stream, query_stream_from_stream};
92pub use sdk_mcp::{McpSdkServer, SdkMcpTool, create_sdk_mcp_server, tool};
93pub use transport::subprocess_cli::{
94    DEFAULT_MAX_BUFFER_SIZE, JsonStreamBuffer, Prompt, SubprocessCliTransport,
95};
96pub use transport::{
97    SplitAdapter, Transport, TransportCloseHandle, TransportFactory, TransportReader,
98    TransportSplitResult, TransportWriter, split_with_adapter,
99};
100pub use types::{
101    AgentDefinition, AssistantMessage, ClaudeAgentOptions, ContentBlock, HookCallback, HookContext,
102    HookInput, HookJSONOutput, HookMatcher, McpHttpServerConfig, McpSSEServerConfig,
103    McpSdkServerConfig, McpServerConfig, McpServersOption, McpStdioServerConfig, Message,
104    PermissionMode, PermissionResult, PermissionResultAllow, PermissionResultDeny,
105    PermissionUpdate, ResultMessage, SandboxIgnoreViolations, SandboxNetworkConfig,
106    SandboxSettings, SdkPluginConfig, SettingSource, StderrCallback, StreamEvent, SystemMessage,
107    SystemPrompt, SystemPromptPreset, TextBlock, ThinkingBlock, ThinkingConfig, ToolAnnotations,
108    ToolPermissionContext, ToolResultBlock, ToolUseBlock, ToolsOption, ToolsPreset, UserContent,
109    UserMessage,
110};
111
112/// The version of the Claude Code Rust SDK, sourced from `Cargo.toml`.
113pub const SDK_VERSION: &str = env!("CARGO_PKG_VERSION");
claude_code/lib.rs

claude_code/
lib.rs
