claude_codes/

lib.rs

//! A tightly typed Rust interface for the Claude Code JSON protocol
//!
//! This crate provides type-safe bindings for interacting with the Claude CLI
//! through its JSON Lines protocol. It handles the complexity of message serialization,
//! deserialization, and streaming communication with Claude.
//!
//! # Quick Start
//!
//! Add this crate to your project:
//! ```bash
//! cargo add claude-codes
//! ```
//!
//! ## Using the Async Client (Recommended)
//!
//! ```ignore
//! use claude_codes::AsyncClient;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create a client with automatic version checking
//!     let mut client = AsyncClient::with_defaults().await?;
//!
//!     // Send a query and stream responses
//!     let mut stream = client.query_stream("What is 2 + 2?").await?;
//!
//!     while let Some(response) = stream.next().await {
//!         match response {
//!             Ok(output) => {
//!                 println!("Received: {}", output.message_type());
//!                 // Handle different message types
//!             }
//!             Err(e) => eprintln!("Error: {}", e),
//!         }
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Using the Sync Client
//!
//! ```ignore
//! use claude_codes::{SyncClient, ClaudeInput};
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create a synchronous client
//!     let mut client = SyncClient::with_defaults()?;
//!
//!     // Build a structured input message
//!     let input = ClaudeInput::user_message("What is 2 + 2?", uuid::Uuid::new_v4());
//!
//!     // Send and collect all responses
//!     let responses = client.query(input)?;
//!
//!     for response in responses {
//!         println!("Received: {}", response.message_type());
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! # Architecture
//!
//! The crate is organized into several key modules:
//!
//! - [`client`] - High-level async and sync clients for easy interaction
//! - [`protocol`] - Core JSON Lines protocol implementation
//! - [`io`] - Top-level message types (`ClaudeInput`, `ClaudeOutput`)
//! - [`messages`] - Detailed message structures for requests and responses
//! - [`cli`] - Builder for configuring Claude CLI invocation
//! - [`error`] - Error types and result aliases
//! - [`version`] - Version compatibility checking
//!
//! # Version Compatibility
//!
//! ⚠️ **Important**: The Claude CLI protocol is unstable and evolving. This crate
//! automatically checks your Claude CLI version and warns if it's newer than tested.
//!
//! Current tested version: **2.1.311**
//!
//! Report compatibility issues at: <https://github.com/meawoppl/rust-claude-codes/pulls>
//!
//! # Message Types
//!
//! The protocol uses several message types:
//!
//! - **System** - Initialization and metadata messages
//! - **User** - Input messages from the user
//! - **Assistant** - Claude's responses
//! - **Result** - Session completion with timing and cost info
//!
//! # Examples
//!
//! See the `examples/` directory for complete working examples:
//! - `async_client.rs` - Simple async client usage
//! - `sync_client.rs` - Synchronous client usage
//! - `basic_repl.rs` - Interactive REPL implementation

// Core modules always available
pub mod error;
pub mod io;
pub mod messages;
pub mod models;
pub mod protocol;
pub mod tool_inputs;
pub mod types;

// On-disk transcript locations (the CLI's unpublished path-encoding rule)
pub mod transcript;

// Login support tooling (PTY-driven `claude auth login` / `setup-token`)
#[cfg(feature = "auth")]
pub mod auth;

// Client modules
#[cfg(feature = "async-client")]
pub mod client_async;
#[cfg(feature = "async-client")]
pub mod client_raw_async;
#[cfg(feature = "sync-client")]
pub mod client_sync;

// Client-related modules
#[cfg(any(feature = "sync-client", feature = "async-client"))]
pub mod cli;
#[cfg(any(feature = "sync-client", feature = "async-client"))]
pub mod version;

#[cfg(any(feature = "sync-client", feature = "async-client"))]
mod process;

// Core exports always available
pub use error::{Error, Result};
pub use io::{
    AnthropicError, AnthropicErrorDetails, ApiErrorType, AssistantMessageContent, ClaudeInput,
    ClaudeOutput, ParseError, TranscriptMessage,
};
pub use messages::*;
pub use models::ClaudeModel;
pub use protocol::{MessageEnvelope, Protocol};
pub use types::*;

// Content block types for message parsing
pub use io::{
    CodeExecutionToolResultBlock, ContainerUploadBlock, ContentBlock, FallbackBlock, FallbackModel,
    ImageBlock, ImageSource, ImageSourceType, McpToolResultBlock, McpToolUseBlock, MediaType,
    ServerToolUseBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolResultContent,
    WebSearchToolResultBlock,
};

// Control protocol types for tool permission handling
pub use io::{
    AskUserQuestionResponseError, ControlCancelRequest, ControlRequest, ControlRequestMessage,
    ControlRequestPayload, ControlResponse, ControlResponseMessage, ControlResponsePayload,
    GetUsageResponse, HookCallbackRequest, InitializeRequest, McpMessageRequest,
    ModelScopedRateLimit, Permission, PermissionBehavior, PermissionDenial, PermissionDestination,
    PermissionModeName, PermissionResult, PermissionRule, PermissionSuggestion, PermissionType,
    ToolCaller, ToolPermissionRequest, ToolUseBlock, UsageBehavior, UsageBehaviors,
    UsageModelUsage, UsageRateLimitWindow, UsageRateLimits, UsageSession,
};

// System message and assistant message types
pub use io::{
    ApiErrorMedia, ApiErrorMediaReason, ApiErrorParams, ApiErrorProvider, ApiErrorRemedy,
    ApiKeySource, ApiRetryMessage, ApiRetryNoResponse, ArtifactReadVersion, AssistantErrorKind,
    BackgroundTaskInfo, BackgroundTasksChangedMessage, BatchToolUse, CloudSessionDeltaMessage,
    CodeChangePublishedMessage, CommandInfo, CommandsChangedMessage, CompactBoundaryMessage,
    CompactMetadata, CompactionTrigger, ContextAgent, ContextCategory, ContextMcpTool,
    ContextMemoryFile, ContextOverLimit, ContextSkill, ContextUsage, ControlRequestProgressMessage,
    DevIntentKind, DevIntentMessage, DevIntentTrigger, ElicitationCompleteMessage,
    FailedPersistedFile, FeedbackDraftQueuedMessage, FileAttachmentsMissingMessage,
    FilesPersistedMessage, HandbackReport, HookProgressMessage, HookResponseMessage,
    HookStartedMessage, InformationalMessage, InheritedAsksSettledMessage, InitMessage,
    InitPermissionMode, InstructionSizeWarningMessage, KnownSystemEvent, LocalCommandOutcome,
    LocalCommandOutcomeKind, LocalCommandOutputMessage, LocalCommandRun, McpMeta, McpServerError,
    MemoryPaths, MemoryRecallItem, MemoryRecallMessage, MessageOrigin, MessageRole, MirrorErrorKey,
    MirrorErrorMessage, MissingFileAttachment, ModelRefusalFallbackMessage,
    ModelRefusalNoFallbackMessage, NotificationMessage, OutputStyle, PeerMessageHoldCause,
    PeerMessageHoldMessage, PeerMessageHoldOutcome, PeerMessageHoldState, PeerMessageLane,
    PerTurnEffortChangedMessage, PermissionCheckStatus, PermissionCheckStatusMessage,
    PermissionDecisionOutcome, PermissionDecisionReasonType, PermissionDeniedMessage,
    PermissionDeniedReasonCode, PersistedFile, PluginDiagnostic, PluginInfo, PluginInstallMessage,
    PreservedMessages, PreservedSegment, PromptSubmitOutcome, PromptSubmitOutcomeKind,
    RefusalFallbackScope, RemedyFeature, RemedyFeatureCause, RemedyLoginProvider, RemedyPolicyKind,
    SessionTitleChangedMessage, StatusMessage, StatusMessageStatus, StopReason, SummarizeMetadata,
    SystemMessage, SystemSubtype, TaskEndReason, TaskHandback, TaskNotificationMessage, TaskPatch,
    TaskProgressMessage, TaskStartedMessage, TaskStatus, TaskType, TaskUpdatedMessage, TaskUsage,
    ThinkingTokensMessage, ToolPermissionDecision, ToolResultMeta, ToolResultRemedy,
    ToolResultRemedyKind, ToolUseMeta, TurnHandoffAvailableMessage, TurnPreemptedMessage,
    UiFocusMessage, UiInvalidateMessage, UiInvalidatedInstance, UiLogMessage, UiPane,
    UiPanesMessage, UiScrollMessage, UiSiteComponent, UiStatusMessage, UiToastMessage, UsageReport,
    UsageReportExtraUsage, UsageReportLimit, UsageReportRateLimits, UsageReportScope,
    UsageReportScopeLabel, VcsMutationKind, VcsStateChangedMessage, ViewMode,
    WorkerShuttingDownMessage,
};

// Additional top-level output message wrappers
pub use io::{
    AbandonedBlocks, AuthStatusMessage, CommandLifecycleMessage, CommandLifecycleState,
    CommandWakeupSource, ConversationResetMessage, ConversationResetTrigger,
    PromptSuggestionMessage, StreamEventMessage, SubagentRetry, ToolProgressMessage,
    ToolUseSummaryMessage,
};

// Wire-fidelity audit for verifying frames are fully typed
pub use io::{assert_fully_wrapped, audit_frame, FrameAudit};

// Rate limit types
pub use io::{
    AdminRequestOffer, AdminRequestOfferState, OverageDisabledReason, OveragePeriodUtilization,
    OverageStatus, RateLimitErrorCode, RateLimitEvent, RateLimitInfo, RateLimitScope,
    RateLimitStatus, RateLimitWindow, UsageCreditOffer, UsageCreditOfferKind,
};

// Usage types
pub use io::{
    AssistantUsage, CacheCreationDetails, DeferredToolUse, FastModeDisabledReason,
    GarbageCollectionCounts, InputAttachmentsDetail, ProcessGarbageCollections,
    ResumeStoreConfirmDetail, RunnerExit, RunnerExitPhase, ServerToolUse, StartupFailureReason,
    StreamPostQueuedBehind, SubagentKillCounts, SubagentRefusalCounts, SubagentResult,
    SubagentSpawnRequests, SubagentStats, SubagentToolStats, SubagentUsageRollup,
    TouchCompareCounts, TurnStartResumeKind, UsageInfo,
};

// Typed tool input types
pub use tool_inputs::{
    AllowedPrompt, AskUserQuestionInput, BashInput, EditInput, EnterPlanModeInput,
    ExitPlanModeInput, GlobInput, GrepInput, GrepOutputMode, KillShellInput, LsInput,
    MultiEditInput, MultiEditOperation, NotebookCellType, NotebookEditInput, NotebookEditMode,
    NotebookReadInput, Question, QuestionMetadata, QuestionOption, ReadInput, ScheduleWakeupInput,
    SkillInput, SubagentType, TaskInput, TaskOutputInput, TodoItem, TodoStatus, TodoWriteInput,
    ToolInput, ToolSearchInput, WebFetchInput, WebSearchInput, WriteInput,
};

// Client exports
#[cfg(feature = "async-client")]
pub use client_async::{AsyncClient, AsyncStreamProcessor};
#[cfg(feature = "async-client")]
pub use client_raw_async::RawAsyncClient;
#[cfg(feature = "sync-client")]
pub use client_sync::{StreamProcessor, SyncClient};

// Client-related exports
#[cfg(any(feature = "sync-client", feature = "async-client"))]
pub use cli::{ClaudeCliBuilder, CliFlag, InputFormat, OutputFormat, PermissionMode};

#[cfg(test)]
mod tests {
    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }
}