claude_codes/
lib.rs

1//! A tightly typed Rust interface for the Claude Code JSON protocol
2//!
3//! This crate provides type-safe bindings for interacting with the Claude CLI
4//! through its JSON Lines protocol. It handles the complexity of message serialization,
5//! deserialization, and streaming communication with Claude.
6//!
7//! # Quick Start
8//!
9//! Add this crate to your project:
10//! ```bash
11//! cargo add claude-codes
12//! ```
13//!
14//! ## Using the Async Client (Recommended)
15//!
16//! ```ignore
17//! use claude_codes::AsyncClient;
18//!
19//! #[tokio::main]
20//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
21//!     // Create a client with automatic version checking
22//!     let mut client = AsyncClient::with_defaults().await?;
23//!
24//!     // Send a query and stream responses
25//!     let mut stream = client.query_stream("What is 2 + 2?").await?;
26//!
27//!     while let Some(response) = stream.next().await {
28//!         match response {
29//!             Ok(output) => {
30//!                 println!("Received: {}", output.message_type());
31//!                 // Handle different message types
32//!             }
33//!             Err(e) => eprintln!("Error: {}", e),
34//!         }
35//!     }
36//!
37//!     Ok(())
38//! }
39//! ```
40//!
41//! ## Using the Sync Client
42//!
43//! ```ignore
44//! use claude_codes::{SyncClient, ClaudeInput};
45//!
46//! fn main() -> Result<(), Box<dyn std::error::Error>> {
47//!     // Create a synchronous client
48//!     let mut client = SyncClient::with_defaults()?;
49//!
50//!     // Build a structured input message
51//!     let input = ClaudeInput::user_message("What is 2 + 2?", uuid::Uuid::new_v4());
52//!
53//!     // Send and collect all responses
54//!     let responses = client.query(input)?;
55//!
56//!     for response in responses {
57//!         println!("Received: {}", response.message_type());
58//!     }
59//!
60//!     Ok(())
61//! }
62//! ```
63//!
64//! # Architecture
65//!
66//! The crate is organized into several key modules:
67//!
68//! - [`client`] - High-level async and sync clients for easy interaction
69//! - [`protocol`] - Core JSON Lines protocol implementation
70//! - [`io`] - Top-level message types (`ClaudeInput`, `ClaudeOutput`)
71//! - [`messages`] - Detailed message structures for requests and responses
72//! - [`cli`] - Builder for configuring Claude CLI invocation
73//! - [`error`] - Error types and result aliases
74//! - [`version`] - Version compatibility checking
75//!
76//! # Version Compatibility
77//!
78//! ⚠️ **Important**: The Claude CLI protocol is unstable and evolving. This crate
79//! automatically checks your Claude CLI version and warns if it's newer than tested.
80//!
81//! Current tested version: **2.1.219**
82//!
83//! Report compatibility issues at: <https://github.com/meawoppl/rust-claude-codes/pulls>
84//!
85//! # Message Types
86//!
87//! The protocol uses several message types:
88//!
89//! - **System** - Initialization and metadata messages
90//! - **User** - Input messages from the user
91//! - **Assistant** - Claude's responses
92//! - **Result** - Session completion with timing and cost info
93//!
94//! # Examples
95//!
96//! See the `examples/` directory for complete working examples:
97//! - `async_client.rs` - Simple async client usage
98//! - `sync_client.rs` - Synchronous client usage
99//! - `basic_repl.rs` - Interactive REPL implementation
100
101// Core modules always available
102pub mod error;
103pub mod io;
104pub mod messages;
105pub mod models;
106pub mod protocol;
107pub mod tool_inputs;
108pub mod types;
109
110// Client modules
111#[cfg(feature = "async-client")]
112pub mod client_async;
113#[cfg(feature = "sync-client")]
114pub mod client_sync;
115
116// Client-related modules
117#[cfg(any(feature = "sync-client", feature = "async-client"))]
118pub mod cli;
119#[cfg(any(feature = "sync-client", feature = "async-client"))]
120pub mod version;
121
122// Core exports always available
123pub use error::{Error, Result};
124pub use io::{
125    AnthropicError, AnthropicErrorDetails, ApiErrorType, AssistantMessageContent, ClaudeInput,
126    ClaudeOutput, ParseError, TranscriptMessage,
127};
128pub use messages::*;
129pub use models::ClaudeModel;
130pub use protocol::{MessageEnvelope, Protocol};
131pub use types::*;
132
133// Content block types for message parsing
134pub use io::{
135    CodeExecutionToolResultBlock, ContainerUploadBlock, ContentBlock, FallbackBlock, FallbackModel,
136    ImageBlock, ImageSource, ImageSourceType, McpToolResultBlock, McpToolUseBlock, MediaType,
137    ServerToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolResultContent,
138    WebSearchToolResultBlock,
139};
140
141// Control protocol types for tool permission handling
142pub use io::{
143    AskUserQuestionResponseError, ControlRequest, ControlRequestMessage, ControlRequestPayload,
144    ControlResponse, ControlResponseMessage, ControlResponsePayload, GetUsageResponse,
145    HookCallbackRequest, InitializeRequest, McpMessageRequest, ModelScopedRateLimit, Permission,
146    PermissionBehavior, PermissionDenial, PermissionDestination, PermissionModeName,
147    PermissionResult, PermissionRule, PermissionSuggestion, PermissionType, ToolCaller,
148    ToolPermissionRequest, ToolUseBlock, UsageBehavior, UsageBehaviors, UsageModelUsage,
149    UsageRateLimitWindow, UsageRateLimits, UsageSession,
150};
151
152// System message and assistant message types
153pub use io::{
154    ApiKeySource, ApiRetryMessage, AssistantErrorKind, BackgroundTaskInfo,
155    BackgroundTasksChangedMessage, CodeChangePublishedMessage, CommandInfo, CommandsChangedMessage,
156    CompactBoundaryMessage, CompactMetadata, CompactionTrigger, ControlRequestProgressMessage,
157    ElicitationCompleteMessage, FailedPersistedFile, FilesPersistedMessage, HookProgressMessage,
158    HookResponseMessage, HookStartedMessage, InformationalMessage, InitMessage, InitPermissionMode,
159    KnownSystemEvent, LocalCommandOutputMessage, McpMeta, McpServerError, MemoryPaths,
160    MemoryRecallItem, MemoryRecallMessage, MessageOrigin, MessageRole, MirrorErrorKey,
161    MirrorErrorMessage, ModelRefusalFallbackMessage, ModelRefusalNoFallbackMessage,
162    NotificationMessage, OutputStyle, PermissionDeniedMessage, PersistedFile, PluginDiagnostic,
163    PluginInfo, PluginInstallMessage, PreservedMessages, PreservedSegment, StatusMessage,
164    StatusMessageStatus, StopReason, SummarizeMetadata, SystemMessage, SystemSubtype,
165    TaskNotificationMessage, TaskPatch, TaskProgressMessage, TaskStartedMessage, TaskStatus,
166    TaskType, TaskUpdatedMessage, TaskUsage, ThinkingTokensMessage, ToolResultMeta, ToolUseMeta,
167    VcsMutationKind, VcsStateChangedMessage, WorkerShuttingDownMessage,
168};
169
170// Additional top-level output message wrappers
171pub use io::{
172    AuthStatusMessage, CommandLifecycleMessage, CommandLifecycleState, ConversationResetMessage,
173    PromptSuggestionMessage, StreamEventMessage, SubagentRetry, ToolProgressMessage,
174    ToolUseSummaryMessage,
175};
176
177// Wire-fidelity audit for verifying frames are fully typed
178pub use io::{assert_fully_wrapped, audit_frame, FrameAudit};
179
180// Rate limit types
181pub use io::{
182    OverageDisabledReason, OveragePeriodUtilization, OverageStatus, RateLimitErrorCode,
183    RateLimitEvent, RateLimitInfo, RateLimitStatus, RateLimitWindow,
184};
185
186// Usage types
187pub use io::{
188    AssistantUsage, CacheCreationDetails, DeferredToolUse, FastModeDisabledReason, ServerToolUse,
189    SubagentResult, SubagentToolStats, SubagentUsageRollup, UsageInfo,
190};
191
192// Typed tool input types
193pub use tool_inputs::{
194    AllowedPrompt, AskUserQuestionInput, BashInput, EditInput, EnterPlanModeInput,
195    ExitPlanModeInput, GlobInput, GrepInput, GrepOutputMode, KillShellInput, LsInput,
196    MultiEditInput, MultiEditOperation, NotebookCellType, NotebookEditInput, NotebookEditMode,
197    NotebookReadInput, Question, QuestionMetadata, QuestionOption, ReadInput, ScheduleWakeupInput,
198    SkillInput, SubagentType, TaskInput, TaskOutputInput, TodoItem, TodoStatus, TodoWriteInput,
199    ToolInput, ToolSearchInput, WebFetchInput, WebSearchInput, WriteInput,
200};
201
202// Client exports
203#[cfg(feature = "async-client")]
204pub use client_async::{AsyncClient, AsyncStreamProcessor};
205#[cfg(feature = "sync-client")]
206pub use client_sync::{StreamProcessor, SyncClient};
207
208// Client-related exports
209#[cfg(any(feature = "sync-client", feature = "async-client"))]
210pub use cli::{ClaudeCliBuilder, CliFlag, InputFormat, OutputFormat, PermissionMode};
211
212#[cfg(test)]
213mod tests {
214    #[test]
215    fn it_works() {
216        assert_eq!(2 + 2, 4);
217    }
218}
claude_codes/lib.rs

claude_codes/
lib.rs
