{"id":29132270,"url":"https://github.com/epsilla-cloud/claude-code-sdk-rust","last_synced_at":"2025-08-11T16:12:47.360Z","repository":{"id":300533248,"uuid":"1006410391","full_name":"epsilla-cloud/claude-code-sdk-rust","owner":"epsilla-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-22T08:58:23.000Z","size":42,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T13:12:09.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epsilla-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T07:49:25.000Z","updated_at":"2025-07-26T01:35:15.000Z","dependencies_parsed_at":"2025-06-22T08:46:32.555Z","dependency_job_id":"fc67903e-b2dc-4e8b-ad2c-e7932b269f39","html_url":"https://github.com/epsilla-cloud/claude-code-sdk-rust","commit_stats":null,"previous_names":["epsilla-cloud/claude-code-sdk-rust"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/epsilla-cloud/claude-code-sdk-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclaude-code-sdk-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclaude-code-sdk-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclaude-code-sdk-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclaude-code-sdk-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epsilla-cloud","download_url":"https://codeload.github.com/epsilla-cloud/claude-code-sdk-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclaude-code-sdk-rust/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269917327,"owners_count":24496070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T06:38:09.712Z","updated_at":"2025-08-11T16:12:47.335Z","avatar_url":"https://github.com/epsilla-cloud.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code SDK for Rust\n\nRust SDK for Claude Code. See the [Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for more information.\n\n## Installation\n\nAdd this to your `Cargo.toml`:\n\n```toml\n[dependencies]\nclaude-code-sdk = \"0.0.3\"\ntokio = { version = \"1.0\", features = [\"full\"] }\n```\n\n**Prerequisites:**\n- Rust 1.70+\n- Node.js \n- Claude Code: `npm install -g @anthropic-ai/claude-code`\n\n## Quick Start\n\n```rust\nuse claude_code_sdk::query;\nuse tokio_stream::StreamExt;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Optional: Initialize logging to see detailed SDK operations\n    claude_code_sdk::init_tracing();\n    \n    let mut stream = query(\"What is 2 + 2?\", None).await?;\n    \n    while let Some(message) = stream.next().await {\n        println!(\"{:?}\", message);\n    }\n    \n    Ok(())\n}\n```\n\n## Usage\n\n### Basic Query\n\n```rust\nuse claude_code_sdk::{query, ClaudeCodeOptions, Message};\nuse tokio_stream::StreamExt;\n\n// Simple query\nlet mut stream = query(\"Hello Claude\", None).await?;\nwhile let Some(message) = stream.next().await {\n    match message {\n        Message::Assistant(msg) =\u003e {\n            for block in \u0026msg.content {\n                if let ContentBlock::Text(text_block) = block {\n                    println!(\"Claude: {}\", text_block.text);\n                }\n            }\n        }\n        _ =\u003e {}\n    }\n}\n\n// With options\nlet options = ClaudeCodeOptions {\n    system_prompt: Some(\"You are a helpful assistant\".to_string()),\n    max_turns: Some(1),\n    ..Default::default()\n};\n\nlet mut stream = query(\"Tell me a joke\", Some(options)).await?;\nwhile let Some(message) = stream.next().await {\n    println!(\"{:?}\", message);\n}\n```\n\n### Using Tools\n\n```rust\nlet options = ClaudeCodeOptions {\n    allowed_tools: vec![\"Read\".to_string(), \"Write\".to_string()],\n    permission_mode: Some(PermissionMode::AcceptEdits),\n    ..Default::default()\n};\n\nlet mut stream = query(\"Create a hello.rs file\", Some(options)).await?;\nwhile let Some(message) = stream.next().await {\n    // Process tool use and results\n}\n```\n\n### Working Directory\n\n```rust\nuse std::path::PathBuf;\n\nlet options = ClaudeCodeOptions {\n    cwd: Some(PathBuf::from(\"/path/to/project\")),\n    ..Default::default()\n};\n```\n\n## Logging\n\nThe Claude Code SDK provides comprehensive structured logging using the [`tracing`](https://tracing.rs/) ecosystem. This helps with debugging, monitoring, and understanding SDK operations.\n\n### Quick Setup\n\n```rust\nuse claude_code_sdk;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Initialize default logging\n    claude_code_sdk::init_tracing();\n    \n    // Your code here...\n    Ok(())\n}\n```\n\n### Environment Variables\n\nControl logging levels with the `RUST_LOG` environment variable:\n\n```bash\n# Show info and above (default)\nRUST_LOG=claude_code_sdk=info cargo run\n\n# Show debug messages (recommended for development)\nRUST_LOG=claude_code_sdk=debug cargo run\n\n# Show all messages including trace\nRUST_LOG=claude_code_sdk=trace cargo run\n\n# Show only errors\nRUST_LOG=claude_code_sdk=error cargo run\n\n# Multiple modules\nRUST_LOG=claude_code_sdk=debug,tokio=info cargo run\n```\n\n### Custom Logging Setup\n\nFor more control over logging, set up `tracing-subscriber` directly:\n\n```rust\nuse tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};\n\n// JSON structured logging\ntracing_subscriber::registry()\n    .with(tracing_subscriber::EnvFilter::new(\"claude_code_sdk=debug\"))\n    .with(tracing_subscriber::fmt::layer().json())\n    .init();\n\n// Custom formatting\ntracing_subscriber::registry()\n    .with(tracing_subscriber::EnvFilter::new(\"claude_code_sdk=debug\"))\n    .with(\n        tracing_subscriber::fmt::layer()\n            .with_target(true)\n            .with_thread_ids(true)\n            .with_file(true)\n            .with_line_number(true)\n            .pretty()\n    )\n    .init();\n\n// File logging\nlet file = std::fs::OpenOptions::new()\n    .create(true)\n    .write(true)\n    .truncate(true)\n    .open(\"claude_sdk.log\")?;\n\ntracing_subscriber::registry()\n    .with(tracing_subscriber::EnvFilter::new(\"claude_code_sdk=trace\"))\n    .with(tracing_subscriber::fmt::layer().with_writer(file))\n    .init();\n```\n\n### What Gets Logged\n\nThe SDK logs various operations at different levels:\n\n- **ERROR**: CLI not found, connection failures, JSON decode errors\n- **WARN**: Process termination issues, unexpected states\n- **INFO**: Query start/completion, connection events, major operations\n- **DEBUG**: Message processing, command building, subprocess management\n- **TRACE**: Individual message parsing, detailed state changes\n\n### Log Fields\n\nStructured logs include useful fields:\n\n```json\n{\n  \"timestamp\": \"2024-01-01T12:00:00.000Z\",\n  \"level\": \"INFO\",\n  \"target\": \"claude_code_sdk::client\",\n  \"message\": \"Processing query through transport\",\n  \"fields\": {\n    \"prompt_length\": 25,\n    \"has_options\": true,\n    \"system_prompt\": \"You are helpful\",\n    \"allowed_tools\": 2,\n    \"permission_mode\": \"AcceptEdits\"\n  }\n}\n```\n\n### Performance Monitoring\n\nEnable performance monitoring with tracing spans:\n\n```rust\nuse tracing::{info, Instrument};\n\nasync fn my_function() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let span = tracing::info_span!(\"my_operation\", operation_type = \"query\");\n    \n    async move {\n        let start = std::time::Instant::now();\n        \n        // Your Claude SDK operations here\n        let mut stream = query(\"Hello\", None).await?;\n        // ... process stream\n        \n        info!(duration_ms = start.elapsed().as_millis(), \"Operation completed\");\n        Ok(())\n    }\n    .instrument(span)\n    .await\n}\n```\n\n## Safety \u0026 Long Text Handling\n\nThe Claude Code SDK includes comprehensive safety mechanisms to handle long text responses safely and prevent common issues like memory exhaustion and performance degradation.\n\n### Safety Limits\n\nConfigure safety limits to protect against resource exhaustion:\n\n```rust\nuse claude_code_sdk::{SafetyLimits, SafetyError, ClaudeSDKError};\n\n// Default limits (balanced)\nlet default_limits = SafetyLimits::default();\n\n// Conservative limits (memory-constrained environments)\nlet conservative = SafetyLimits::conservative();\n\n// Generous limits (high-memory servers)\nlet generous = SafetyLimits::generous();\n\n// Custom limits\nlet custom = SafetyLimits {\n    max_line_size: 5 * 1024 * 1024,      // 5MB per line\n    max_text_block_size: 2 * 1024 * 1024, // 2MB per text block\n    max_buffer_size: 20 * 1024 * 1024,   // 20MB total buffer\n    max_buffered_messages: 50,            // 50 messages max\n    json_parse_timeout_ms: 3000,          // 3 second timeout\n    max_log_preview_chars: 150,           // 150 char preview\n};\n```\n\n### Protected Operations\n\nThe SDK automatically protects against:\n\n- **Memory Exhaustion**: Line size and text block limits prevent runaway memory usage\n- **JSON Parsing Timeouts**: Large JSON objects are monitored for parsing time\n- **Log Explosion**: Automatic truncation of log messages with size indicators\n- **Buffer Overflow**: Channel size limits prevent message queue buildup\n\n### Error Handling\n\nSafety violations are reported through structured errors:\n\n```rust\nmatch query(\"Generate a very long response\", None).await {\n    Ok(stream) =\u003e {\n        // Process normally\n    }\n    Err(ClaudeSDKError::Safety(SafetyError::LineTooLarge { actual, limit })) =\u003e {\n        println!(\"Line too large: {} bytes (limit: {})\", actual, limit);\n    }\n    Err(ClaudeSDKError::Safety(SafetyError::TextBlockTooLarge { actual, limit })) =\u003e {\n        println!(\"Text block too large: {} bytes (limit: {})\", actual, limit);\n    }\n    Err(ClaudeSDKError::Safety(SafetyError::ParseTimeout { timeout_ms })) =\u003e {\n        println!(\"JSON parsing timeout after {}ms\", timeout_ms);\n    }\n    Err(other) =\u003e {\n        println!(\"Other error: {}\", other);\n    }\n}\n```\n\n### Risk Mitigation\n\n| Risk | Mitigation | Configuration |\n|------|------------|---------------|\n| **Memory exhaustion** | Line and text block size limits | `max_line_size`, `max_text_block_size` |\n| **JSON parsing hangs** | Parsing timeout monitoring | `json_parse_timeout_ms` |\n| **Log file explosion** | Safe preview truncation | `max_log_preview_chars` |\n| **Message queue buildup** | Buffer size and count limits | `max_buffer_size`, `max_buffered_messages` |\n| **Process blocking** | Async processing with backpressure | Automatic |\n\n### Monitoring\n\nThe SDK provides detailed monitoring of resource usage:\n\n```rust\nuse tracing::{info, warn};\n\n// Automatic logging of resource usage\n// INFO: Text block size monitoring\n// WARN: Approaching safety limits  \n// ERROR: Safety limit violations\n\n// Example log output:\n// INFO text_length=1048576 limit=5242880 \"Large text block detected\"\n// WARN \"Text block is approaching size limit\"\n// ERROR actual=10485760 limit=5242880 \"Line exceeds safety limit\"\n```\n\n## API Reference\n\n### `query(prompt: \u0026str, options: Option\u003cClaudeCodeOptions\u003e)`\n\nMain async function for querying Claude.\n\n**Parameters:**\n- `prompt`: The prompt to send to Claude\n- `options`: Optional configuration\n\n**Returns:** `Result\u003cPin\u003cBox\u003cdyn Stream\u003cItem = Message\u003e\u003e\u003e, ClaudeSDKError\u003e`\n\n### Types\n\nSee [src/types.rs](src/types.rs) for complete type definitions:\n- `ClaudeCodeOptions` - Configuration options\n- `Message` variants - `Assistant`, `User`, `System`, `Result`\n- `ContentBlock` variants - `Text`, `ToolUse`, `ToolResult`\n\n## Error Handling\n\n```rust\nuse claude_code_sdk::{\n    ClaudeSDKError,      // Base error\n    CLINotFoundError,    // Claude Code not installed\n    CLIConnectionError,  // Connection issues\n    ProcessError,        // Process failed\n    CLIJSONDecodeError,  // JSON parsing issues\n};\n\nmatch query(\"Hello\", None).await {\n    Ok(mut stream) =\u003e {\n        // Process messages\n    }\n    Err(ClaudeSDKError::CLINotFound(e)) =\u003e {\n        println!(\"Please install Claude Code: {}\", e);\n    }\n    Err(ClaudeSDKError::Process(e)) =\u003e {\n        println!(\"Process failed with exit code: {:?}\", e.exit_code);\n    }\n    Err(e) =\u003e {\n        println!(\"Error: {}\", e);\n    }\n}\n```\n\n## Available Tools\n\nSee the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/security#tools-available-to-claude) for a complete list of available tools.\n\n## Examples\n\n- **[examples/quick_start.rs](examples/quick_start.rs)** - Complete working example with logging\n- **[examples/logging_demo.rs](examples/logging_demo.rs)** - Advanced logging configurations\n- **[examples/safety_demo.rs](examples/safety_demo.rs)** - Safety mechanisms and long text handling\n\n### Running Examples\n\n```bash\n# Basic example with default logging\ncargo run --example quick_start\n\n# Advanced logging demo with JSON output\ncargo run --example logging_demo -- --json\n\n# File logging\ncargo run --example logging_demo -- --file logs/claude.log\n\n# Performance monitoring\nRUST_LOG=claude_code_sdk=debug cargo run --example logging_demo -- --perf\n\n# Safety demonstration\ncargo run --example safety_demo -- --simulate-large\n```\n\n## License\n\nMIT ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepsilla-cloud%2Fclaude-code-sdk-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepsilla-cloud%2Fclaude-code-sdk-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepsilla-cloud%2Fclaude-code-sdk-rust/lists"}