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, FeedbackDraftQueuedMessage,
167    FilesPersistedMessage, HookProgressMessage, HookResponseMessage, HookStartedMessage,
168    InformationalMessage, InitMessage, InitPermissionMode, KnownSystemEvent,
169    LocalCommandOutputMessage, McpMeta, McpServerError, MemoryPaths, MemoryRecallItem,
170    MemoryRecallMessage, MessageOrigin, MessageRole, MirrorErrorKey, MirrorErrorMessage,
171    ModelRefusalFallbackMessage, ModelRefusalNoFallbackMessage, NotificationMessage, OutputStyle,
172    PermissionDeniedMessage, PersistedFile, PluginDiagnostic, PluginInfo, PluginInstallMessage,
173    PreservedMessages, PreservedSegment, RefusalFallbackScope, StatusMessage, StatusMessageStatus,
174    StopReason, SummarizeMetadata, SystemMessage, SystemSubtype, TaskNotificationMessage,
175    TaskPatch, TaskProgressMessage, TaskStartedMessage, TaskStatus, TaskType, TaskUpdatedMessage,
176    TaskUsage, ThinkingTokensMessage, ToolResultMeta, ToolUseMeta, VcsMutationKind,
177    VcsStateChangedMessage, WorkerShuttingDownMessage,
178};
179
180// Additional top-level output message wrappers
181pub use io::{
182    AuthStatusMessage, CommandLifecycleMessage, CommandLifecycleState, ConversationResetMessage,
183    PromptSuggestionMessage, StreamEventMessage, SubagentRetry, ToolProgressMessage,
184    ToolUseSummaryMessage,
185};
186
187// Wire-fidelity audit for verifying frames are fully typed
188pub use io::{assert_fully_wrapped, audit_frame, FrameAudit};
189
190// Rate limit types
191pub use io::{
192    OverageDisabledReason, OveragePeriodUtilization, OverageStatus, RateLimitErrorCode,
193    RateLimitEvent, RateLimitInfo, RateLimitStatus, RateLimitWindow,
194};
195
196// Usage types
197pub use io::{
198    AssistantUsage, CacheCreationDetails, DeferredToolUse, FastModeDisabledReason, ServerToolUse,
199    SubagentResult, SubagentToolStats, SubagentUsageRollup, UsageInfo,
200};
201
202// Typed tool input types
203pub use tool_inputs::{
204    AllowedPrompt, AskUserQuestionInput, BashInput, EditInput, EnterPlanModeInput,
205    ExitPlanModeInput, GlobInput, GrepInput, GrepOutputMode, KillShellInput, LsInput,
206    MultiEditInput, MultiEditOperation, NotebookCellType, NotebookEditInput, NotebookEditMode,
207    NotebookReadInput, Question, QuestionMetadata, QuestionOption, ReadInput, ScheduleWakeupInput,
208    SkillInput, SubagentType, TaskInput, TaskOutputInput, TodoItem, TodoStatus, TodoWriteInput,
209    ToolInput, ToolSearchInput, WebFetchInput, WebSearchInput, WriteInput,
210};
211
212// Client exports
213#[cfg(feature = "async-client")]
214pub use client_async::{AsyncClient, AsyncStreamProcessor};
215#[cfg(feature = "async-client")]
216pub use client_raw_async::RawAsyncClient;
217#[cfg(feature = "sync-client")]
218pub use client_sync::{StreamProcessor, SyncClient};
219
220// Client-related exports
221#[cfg(any(feature = "sync-client", feature = "async-client"))]
222pub use cli::{ClaudeCliBuilder, CliFlag, InputFormat, OutputFormat, PermissionMode};
223
224#[cfg(test)]
225mod tests {
226    #[test]
227    fn it_works() {
228        assert_eq!(2 + 2, 4);
229    }
230}
claude_codes/lib.rs

claude_codes/
lib.rs
