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.220**
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// Login support tooling (PTY-driven `claude auth login` / `setup-token`)
111#[cfg(feature = "auth")]
112pub mod auth;
113
114// Client modules
115#[cfg(feature = "async-client")]
116pub mod client_async;
117#[cfg(feature = "async-client")]
118pub mod client_raw_async;
119#[cfg(feature = "sync-client")]
120pub mod client_sync;
121
122// Client-related modules
123#[cfg(any(feature = "sync-client", feature = "async-client"))]
124pub mod cli;
125#[cfg(any(feature = "sync-client", feature = "async-client"))]
126pub mod version;
127
128#[cfg(any(feature = "sync-client", feature = "async-client"))]
129mod process;
130
131// Core exports always available
132pub use error::{Error, Result};
133pub use io::{
134    AnthropicError, AnthropicErrorDetails, ApiErrorType, AssistantMessageContent, ClaudeInput,
135    ClaudeOutput, ParseError, TranscriptMessage,
136};
137pub use messages::*;
138pub use models::ClaudeModel;
139pub use protocol::{MessageEnvelope, Protocol};
140pub use types::*;
141
142// Content block types for message parsing
143pub use io::{
144    CodeExecutionToolResultBlock, ContainerUploadBlock, ContentBlock, FallbackBlock, FallbackModel,
145    ImageBlock, ImageSource, ImageSourceType, McpToolResultBlock, McpToolUseBlock, MediaType,
146    ServerToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolResultContent,
147    WebSearchToolResultBlock,
148};
149
150// Control protocol types for tool permission handling
151pub use io::{
152    AskUserQuestionResponseError, ControlRequest, ControlRequestMessage, ControlRequestPayload,
153    ControlResponse, ControlResponseMessage, ControlResponsePayload, GetUsageResponse,
154    HookCallbackRequest, InitializeRequest, McpMessageRequest, ModelScopedRateLimit, Permission,
155    PermissionBehavior, PermissionDenial, PermissionDestination, PermissionModeName,
156    PermissionResult, PermissionRule, PermissionSuggestion, PermissionType, ToolCaller,
157    ToolPermissionRequest, ToolUseBlock, UsageBehavior, UsageBehaviors, UsageModelUsage,
158    UsageRateLimitWindow, UsageRateLimits, UsageSession,
159};
160
161// System message and assistant message types
162pub use io::{
163    ApiKeySource, ApiRetryMessage, AssistantErrorKind, BackgroundTaskInfo,
164    BackgroundTasksChangedMessage, CodeChangePublishedMessage, CommandInfo, CommandsChangedMessage,
165    CompactBoundaryMessage, CompactMetadata, CompactionTrigger, ControlRequestProgressMessage,
166    ElicitationCompleteMessage, FailedPersistedFile, FilesPersistedMessage, HookProgressMessage,
167    HookResponseMessage, HookStartedMessage, InformationalMessage, InitMessage, InitPermissionMode,
168    KnownSystemEvent, LocalCommandOutputMessage, McpMeta, McpServerError, MemoryPaths,
169    MemoryRecallItem, MemoryRecallMessage, MessageOrigin, MessageRole, MirrorErrorKey,
170    MirrorErrorMessage, ModelRefusalFallbackMessage, ModelRefusalNoFallbackMessage,
171    NotificationMessage, OutputStyle, PermissionDeniedMessage, PersistedFile, PluginDiagnostic,
172    PluginInfo, PluginInstallMessage, PreservedMessages, PreservedSegment, RefusalFallbackScope,
173    StatusMessage, StatusMessageStatus, StopReason, SummarizeMetadata, SystemMessage,
174    SystemSubtype, TaskNotificationMessage, TaskPatch, TaskProgressMessage, TaskStartedMessage,
175    TaskStatus, TaskType, TaskUpdatedMessage, TaskUsage, ThinkingTokensMessage, ToolResultMeta,
176    ToolUseMeta, VcsMutationKind, VcsStateChangedMessage, WorkerShuttingDownMessage,
177};
178
179// Additional top-level output message wrappers
180pub use io::{
181    AuthStatusMessage, CommandLifecycleMessage, CommandLifecycleState, ConversationResetMessage,
182    PromptSuggestionMessage, StreamEventMessage, SubagentRetry, ToolProgressMessage,
183    ToolUseSummaryMessage,
184};
185
186// Wire-fidelity audit for verifying frames are fully typed
187pub use io::{assert_fully_wrapped, audit_frame, FrameAudit};
188
189// Rate limit types
190pub use io::{
191    OverageDisabledReason, OveragePeriodUtilization, OverageStatus, RateLimitErrorCode,
192    RateLimitEvent, RateLimitInfo, RateLimitStatus, RateLimitWindow,
193};
194
195// Usage types
196pub use io::{
197    AssistantUsage, CacheCreationDetails, DeferredToolUse, FastModeDisabledReason, ServerToolUse,
198    SubagentResult, SubagentToolStats, SubagentUsageRollup, UsageInfo,
199};
200
201// Typed tool input types
202pub use tool_inputs::{
203    AllowedPrompt, AskUserQuestionInput, BashInput, EditInput, EnterPlanModeInput,
204    ExitPlanModeInput, GlobInput, GrepInput, GrepOutputMode, KillShellInput, LsInput,
205    MultiEditInput, MultiEditOperation, NotebookCellType, NotebookEditInput, NotebookEditMode,
206    NotebookReadInput, Question, QuestionMetadata, QuestionOption, ReadInput, ScheduleWakeupInput,
207    SkillInput, SubagentType, TaskInput, TaskOutputInput, TodoItem, TodoStatus, TodoWriteInput,
208    ToolInput, ToolSearchInput, WebFetchInput, WebSearchInput, WriteInput,
209};
210
211// Client exports
212#[cfg(feature = "async-client")]
213pub use client_async::{AsyncClient, AsyncStreamProcessor};
214#[cfg(feature = "async-client")]
215pub use client_raw_async::RawAsyncClient;
216#[cfg(feature = "sync-client")]
217pub use client_sync::{StreamProcessor, SyncClient};
218
219// Client-related exports
220#[cfg(any(feature = "sync-client", feature = "async-client"))]
221pub use cli::{ClaudeCliBuilder, CliFlag, InputFormat, OutputFormat, PermissionMode};
222
223#[cfg(test)]
224mod tests {
225    #[test]
226    fn it_works() {
227        assert_eq!(2 + 2, 4);
228    }
229}
claude_codes/lib.rs

claude_codes/
lib.rs
