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.3**
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 protocol;
106pub mod types;
107
108// Client modules
109#[cfg(feature = "async-client")]
110pub mod client_async;
111#[cfg(feature = "sync-client")]
112pub mod client_sync;
113
114// Client-related modules
115#[cfg(any(feature = "sync-client", feature = "async-client"))]
116pub mod cli;
117#[cfg(any(feature = "sync-client", feature = "async-client"))]
118pub mod version;
119
120// Core exports always available
121pub use error::{Error, Result};
122pub use io::{AssistantMessageContent, ClaudeInput, ClaudeOutput, ParseError};
123pub use messages::*;
124pub use protocol::{MessageEnvelope, Protocol};
125pub use types::*;
126
127// Control protocol types for tool permission handling
128pub use io::{
129    ControlRequest, ControlRequestMessage, ControlRequestPayload, ControlResponse,
130    ControlResponseMessage, ControlResponsePayload, HookCallbackRequest, InitializeRequest,
131    McpMessageRequest, PermissionResult, ToolPermissionRequest,
132};
133
134// Client exports
135#[cfg(feature = "async-client")]
136pub use client_async::{AsyncClient, AsyncStreamProcessor};
137#[cfg(feature = "sync-client")]
138pub use client_sync::{StreamProcessor, SyncClient};
139
140// Client-related exports
141#[cfg(any(feature = "sync-client", feature = "async-client"))]
142pub use cli::{ClaudeCliBuilder, PermissionMode};
143
144#[cfg(test)]
145mod tests {
146    #[test]
147    fn it_works() {
148        assert_eq!(2 + 2, 4);
149    }
150}
claude_codes/lib.rs

claude_codes/
lib.rs
