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//! ```no_run
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//! ```no_run
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: **1.0.89**
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
101pub mod cli;
102pub mod client;
103pub mod error;
104pub mod io;
105pub mod messages;
106pub mod protocol;
107pub mod types;
108pub mod version;
109
110pub use cli::{ClaudeCliBuilder, PermissionMode};
111pub use client::{AsyncClient, SyncClient};
112pub use error::{Error, Result};
113pub use io::{AssistantMessageContent, ClaudeInput, ClaudeOutput, ParseError};
114pub use messages::*;
115pub use protocol::Protocol;
116pub use types::*;
117
118#[cfg(test)]
119mod tests {
120    #[test]
121    fn it_works() {
122        assert_eq!(2 + 2, 4);
123    }
124}
claude_codes/lib.rs

claude_codes/
lib.rs
