Skip to main content

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.326**
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// On-disk transcript locations (the CLI's unpublished path-encoding rule)
111pub mod transcript;
112
113// Login support tooling (PTY-driven `claude auth login` / `setup-token`)
114#[cfg(feature = "auth")]
115pub mod auth;
116
117// Client modules
118#[cfg(feature = "async-client")]
119pub mod client_async;
120#[cfg(feature = "async-client")]
121pub mod client_raw_async;
122#[cfg(feature = "sync-client")]
123pub mod client_sync;
124
125// Client-related modules
126#[cfg(any(feature = "sync-client", feature = "async-client"))]
127pub mod cli;
128#[cfg(any(feature = "sync-client", feature = "async-client"))]
129pub mod version;
130
131#[cfg(any(feature = "sync-client", feature = "async-client"))]
132mod process;
133
134// Core exports always available
135pub use error::{Error, Result};
136pub use io::{
137    AnthropicError, AnthropicErrorDetails, ApiErrorType, AssistantMessageContent, ClaudeInput,
138    ClaudeOutput, ParseError, TranscriptMessage,
139};
140pub use messages::*;
141pub use models::{ClaudeModel, EffortLevel};
142pub use protocol::{MessageEnvelope, Protocol};
143pub use types::*;
144
145// Content block types for message parsing
146pub use io::{
147    CodeExecutionToolResultBlock, ContainerUploadBlock, ContentBlock, FallbackBlock, FallbackModel,
148    ImageBlock, ImageSource, ImageSourceType, McpToolResultBlock, McpToolUseBlock, MediaType,
149    ServerToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolResultContent,
150    WebSearchToolResultBlock,
151};
152
153// Control protocol types for tool permission handling
154pub use io::{
155    ApplyFlagSettingsRequest, AskUserQuestionResponseError, ControlCancelRequest, ControlRequest,
156    ControlRequestMessage, ControlRequestPayload, ControlResponse, ControlResponseMessage,
157    ControlResponsePayload, GetUsageResponse, HookCallbackRequest, InitializeRequest,
158    McpMessageRequest, ModelScopedRateLimit, Permission, PermissionBehavior, PermissionDenial,
159    PermissionDestination, PermissionModeName, PermissionResult, PermissionRule,
160    PermissionSuggestion, PermissionType, ToolCaller, ToolPermissionRequest, ToolUseBlock,
161    UsageBehavior, UsageBehaviors, UsageModelUsage, UsageRateLimitWindow, UsageRateLimits,
162    UsageSession,
163};
164
165// System message and assistant message types
166pub use io::{
167    ApiErrorCut, ApiErrorMedia, ApiErrorMediaReason, ApiErrorParams, ApiErrorProvider,
168    ApiErrorRemedy, ApiKeySource, ApiRetryMessage, ApiRetryNoResponse, ArtifactReadVersion,
169    AssistantErrorKind, AutoModeRule, AutoModeRuleList, BackgroundTaskInfo,
170    BackgroundTasksChangedMessage, BatchToolUse, ClientThinking, CloudSessionDeltaMessage,
171    CodeChangePublishedMessage, CommandInfo, CommandsChangedMessage, CompactBoundaryMessage,
172    CompactMetadata, CompactionTrigger, ContextAgent, ContextCategory, ContextMcpTool,
173    ContextMemoryFile, ContextOverLimit, ContextSkill, ContextUsage, ControlRequestProgressMessage,
174    CyberVerificationStatus, DevIntentKind, DevIntentMessage, DevIntentTrigger,
175    ElicitationCompleteMessage, FailedPersistedFile, FeedbackDraftQueuedMessage,
176    FileAttachmentsMissingMessage, FilesPersistedMessage, HandbackReport, HookNoVerdict,
177    HookProgressMessage, HookResponseMessage, HookStartedMessage, InformationalMessage,
178    InheritedAsksSettledMessage, InitMessage, InitPermissionMode, InstructionSizeWarningMessage,
179    KnownSystemEvent, LateAllowNotRunMessage, LateAllowNotRunReason, LocalCommandOutcome,
180    LocalCommandOutcomeKind, LocalCommandOutputMessage, LocalCommandRun, LostSessionWrite, McpMeta,
181    McpServerError, MemoryPaths, MemoryRecallItem, MemoryRecallMessage, MessageOrigin, MessageRole,
182    MirrorErrorKey, MirrorErrorMessage, MissingFileAttachment, ModelRefusalFallbackMessage,
183    ModelRefusalNoFallbackMessage, ModelRestriction, NotificationMessage, OutputStyle,
184    PeerMessageHoldCause, PeerMessageHoldMessage, PeerMessageHoldOutcome, PeerMessageHoldState,
185    PeerMessageLane, PerTurnEffortChangedMessage, PermissionCheckStatus,
186    PermissionCheckStatusMessage, PermissionDecisionOutcome, PermissionDecisionReasonType,
187    PermissionDeniedMessage, PermissionDeniedReasonCode, PersistedFile, PluginDiagnostic,
188    PluginInfo, PluginInstallMessage, PluginManagedLock, PluginPrompt, PreservedMessages,
189    PreservedSegment, PromptSubmitOutcome, PromptSubmitOutcomeKind, RefusalFallbackScope,
190    RemedyFeature, RemedyFeatureCause, RemedyLoginProvider, RemedyPolicyKind,
191    SessionTitleChangedMessage, SessionWriteErrorCode, SessionWritesLostMessage, StatusMessage,
192    StatusMessageStatus, StopReason, SummarizeMetadata, SystemMessage, SystemSubtype,
193    TaskEndReason, TaskHandback, TaskNotificationMessage, TaskPatch, TaskProgressMessage,
194    TaskStartedMessage, TaskStatus, TaskType, TaskUpdatedMessage, TaskUsage, ThinkingTokensMessage,
195    ToolPermissionDecision, ToolResultMeta, ToolResultRemedy, ToolResultRemedyKind, ToolUseMeta,
196    TurnHandoffAvailableMessage, TurnPreemptedMessage, UiFocusMessage, UiInvalidateMessage,
197    UiInvalidatedInstance, UiLogMessage, UiNotifyCancelMessage, UiNotifyMessage, UiPane,
198    UiPanesMessage, UiPlacedMessage, UiPlacedRow, UiScrollMessage, UiSiteComponent,
199    UiStatusMessage, UiToastMessage, UsageReport, UsageReportExtraUsage, UsageReportLimit,
200    UsageReportRateLimits, UsageReportScope, UsageReportScopeLabel, VcsMutationKind,
201    VcsStateChangedMessage, ViewMode, WorkerShuttingDownMessage,
202};
203
204// Additional top-level output message wrappers
205pub use io::{
206    AbandonedBlocks, AuthStatusMessage, CommandLifecycleMessage, CommandLifecycleState,
207    CommandWakeupSource, ConversationResetMessage, ConversationResetTrigger,
208    PromptSuggestionMessage, StreamEventMessage, SubagentRetry, ToolProgressMessage,
209    ToolUseSummaryMessage,
210};
211
212// Wire-fidelity audit for verifying frames are fully typed
213pub use io::{assert_fully_wrapped, audit_frame, FrameAudit};
214
215// Rate limit types
216pub use io::{
217    AdminRequestOffer, AdminRequestOfferState, OverageDisabledReason, OveragePeriodUtilization,
218    OverageStatus, RateLimitErrorCode, RateLimitEvent, RateLimitInfo, RateLimitScope,
219    RateLimitStatus, RateLimitWindow, UsageCreditOffer, UsageCreditOfferKind,
220};
221
222// Usage types
223pub use io::{
224    AssistantUsage, CacheCreationDetails, DeferredToolUse, DiffersFilesCounts,
225    FastModeDisabledReason, GarbageCollectionCounts, InputAttachmentsDetail, InvalidConfigFile,
226    MemoryCheckDetail, MemoryCheckHold, MemoryCheckWait, MessageNormalizationDetail,
227    ProcessGarbageCollections, ProcessStateTime, ProcessTurnStates, RequestBuildDetail,
228    RestoredRewind, ResumeStoreConfirmDetail, RunnerExit, RunnerExitPhase, ServerToolUse,
229    StartupFailureReason, StreamPostQueuedBehind, SubagentKillCounts, SubagentRefusalCounts,
230    SubagentResult, SubagentSpawnRequests, SubagentStats, SubagentToolStats, SubagentUsageRollup,
231    ToolSchemaBuildDetail, TouchCompareCounts, TurnStartResumeKind, UsageInfo,
232};
233
234// Typed tool input types
235pub use tool_inputs::{
236    AllowedPrompt, AskUserQuestionInput, BashInput, EditInput, EnterPlanModeInput,
237    ExitPlanModeInput, GlobInput, GrepInput, GrepOutputMode, KillShellInput, LsInput,
238    MultiEditInput, MultiEditOperation, NotebookCellType, NotebookEditInput, NotebookEditMode,
239    NotebookReadInput, Question, QuestionMetadata, QuestionOption, ReadInput, ScheduleWakeupInput,
240    SkillInput, SubagentType, TaskInput, TaskOutputInput, TodoItem, TodoStatus, TodoWriteInput,
241    ToolInput, ToolSearchInput, WebFetchInput, WebSearchInput, WriteInput,
242};
243
244// Client exports
245#[cfg(feature = "async-client")]
246pub use client_async::{AsyncClient, AsyncStreamProcessor};
247#[cfg(feature = "async-client")]
248pub use client_raw_async::RawAsyncClient;
249#[cfg(feature = "sync-client")]
250pub use client_sync::{StreamProcessor, SyncClient};
251
252// Client-related exports
253#[cfg(any(feature = "sync-client", feature = "async-client"))]
254pub use cli::{ClaudeCliBuilder, CliFlag, InputFormat, OutputFormat, PermissionMode};
255
256#[cfg(test)]
257mod tests {
258    #[test]
259    fn it_works() {
260        assert_eq!(2 + 2, 4);
261    }
262}