claude-code-sdk-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 154889ea495b7743bded0f1cf1ab96b74da5adc93bf19f1e226d6fd9f949dee1
+  data.tar.gz: 77039484cf7d9acbd273334aad182db014b8a5d471d41019d3565828479716a8
+SHA512:
+  metadata.gz: 73ad8a8341c21ef6cbac699ee4ce211619a853676632c6072374821b08737ccacbe8007dd9de0971dacdf3b6bc9e4b69d21275dc2e4b13e7106a1b7f8a8d34e9
+  data.tar.gz: fc9e88788b6783fd4a335b4553fb6c3607b65083ff1fe898756c4cbb5ee4566012562748107e748ab08f1a1c3dc712eab7bb1e91032bb8ca3818539b6755a1d7

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format progress

data/.rubocop.yml

@@ -0,0 +1,19 @@
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+plugins:
+  - rubocop-rspec
+  - rubocop-rake
+  
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  Exclude:
+    - '.ruby-lsp/**/*'
+
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.2

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--readme README.md
+--files CHANGELOG.md,LICENSE
+--output-dir doc
+--protected
+--private
+--exclude spec/
+--exclude examples/

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- Removed unused `async-process` dependency
+
+## [0.0.1] - 2024-07-14
+
+### Added
+- Initial release of claude-sdk-ruby
+- Core SDK functionality for interacting with Claude Code CLI
+- Support for async query processing
+- Message types: User, Assistant, System, and Result
+- Content blocks: Text, ToolUse, and ToolResult
+- Configuration options via ClaudeCodeOptions
+- Error handling with specific error types:
+  - CLINotFoundError
+  - CLIConnectionError  
+  - ProcessError
+- Internal client for direct subprocess communication
+- Comprehensive test suite with RSpec
+- Examples and documentation
+
+### Dependencies
+- async (~> 2.0)
+
+### Development Dependencies
+- bundler (~> 2.0)
+- rake (~> 13.0)
+- rspec (~> 3.0)
+- rubocop (~> 1.50)
+- rubocop-rspec (~> 2.20)
+- simplecov (~> 0.22)
+- yard (~> 0.9)
+
+[Unreleased]: https://github.com/anthropics/claude-code-sdk-ruby/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/anthropics/claude-code-sdk-ruby/releases/tag/v0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Paulo Arruda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,220 @@
+# Claude SDK Ruby
+
+[![Gem Version](https://badge.fury.io/rb/claude-sdk-ruby.svg)](https://badge.fury.io/rb/claude-sdk-ruby)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Ruby SDK for interacting with Claude Code CLI. This gem provides a Ruby-idiomatic interface to Claude Code with full async support, proper error handling, and comprehensive type definitions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'claude-sdk-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install claude-sdk-ruby
+```
+
+## Prerequisites
+
+This SDK requires the Claude Code CLI to be installed:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+You'll also need to configure your API key. Please refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for detailed setup instructions.
+
+## Quick Start
+
+```ruby
+require 'claude_sdk'
+
+# Simple query
+ClaudeSDK.query("What is 2+2?") do |message|
+  case message
+  when ClaudeSDK::Messages::Assistant
+    message.content.each do |block|
+      puts block.text if block.is_a?(ClaudeSDK::ContentBlock::Text)
+    end
+  when ClaudeSDK::Messages::Result
+    puts "Session completed in #{message.duration_ms}ms"
+  end
+end
+```
+
+## Usage
+
+### Basic Query
+
+```ruby
+require 'claude_sdk'
+
+ClaudeSDK.query("Hello, Claude!") do |message|
+  puts message
+end
+```
+
+### With Options
+
+```ruby
+require 'claude_sdk'
+
+options = ClaudeSDK::ClaudeCodeOptions.new(
+  allowed_tools: ['Read', 'Write', 'Bash'],
+  max_turns: 3,
+  system_prompt: 'You are a helpful coding assistant.',
+  cwd: '/path/to/working/directory'
+)
+
+ClaudeSDK.query("Help me write a Ruby script", options: options) do |message|
+  case message
+  when ClaudeSDK::Messages::Assistant
+    message.content.each do |block|
+      case block
+      when ClaudeSDK::ContentBlock::Text
+        puts block.text
+      when ClaudeSDK::ContentBlock::ToolUse
+        puts "Tool: #{block.name}"
+        puts "Input: #{block.input}"
+      end
+    end
+  when ClaudeSDK::Messages::Result
+    puts "Completed in #{message.num_turns} turns"
+    puts "Total cost: $#{message.total_cost_usd}"
+  end
+end
+```
+
+### Without Block (Returns Enumerator)
+
+```ruby
+require 'claude_sdk'
+
+messages = ClaudeSDK.query("Hello")
+messages.each do |message|
+  puts message
+end
+```
+
+### Advanced: Using the Internal Client Directly
+
+```ruby
+require 'claude_sdk/internal/client'
+
+client = ClaudeSDK::Internal::InternalClient.new
+options = ClaudeSDK::ClaudeCodeOptions.new(
+  allowed_tools: ['Read', 'Bash'],
+  max_turns: 5
+)
+
+Async do
+  client.process_query(prompt: "What files are in this directory?", options: options) do |message|
+    case message
+    when ClaudeSDK::Messages::Assistant
+      puts "Assistant response received"
+    when ClaudeSDK::Messages::System
+      puts "System message: #{message.subtype}"
+    when ClaudeSDK::Messages::Result
+      puts "Query completed"
+    end
+  end
+end
+```
+
+## Message Types
+
+The SDK provides several message types:
+
+- `ClaudeSDK::Messages::User` - User input messages
+- `ClaudeSDK::Messages::Assistant` - Assistant responses containing content blocks
+- `ClaudeSDK::Messages::System` - System messages (tool results, errors)
+- `ClaudeSDK::Messages::Result` - Query completion results with timing and cost info
+- `ClaudeSDK::Messages::Error` - Error messages from the CLI
+
+## Content Blocks
+
+Assistant messages contain content blocks:
+
+- `ClaudeSDK::ContentBlock::Text` - Text content
+- `ClaudeSDK::ContentBlock::ToolUse` - Tool usage
+- `ClaudeSDK::ContentBlock::ToolResult` - Tool results
+
+## Configuration Options
+
+The `ClaudeCodeOptions` class supports all Claude Code CLI options:
+
+- `allowed_tools` - Array of allowed tool names (e.g., `['Read', 'Write', 'Bash']`)
+- `disallowed_tools` - Array of disallowed tool names
+- `max_turns` - Maximum conversation turns
+- `system_prompt` - System prompt for the conversation
+- `append_system_prompt` - Additional system prompt to append
+- `cwd` - Working directory for file operations
+- `model` - Model to use (e.g., `'claude-3-opus'`)
+- `permission_mode` - Permission mode (`:default`, `:accept_edits`, `:auto`, `:ask`)
+- `permission_prompt_tool_name` - Tool for permission prompts
+- `continue_conversation` - Whether to continue from previous conversation
+- `resume` - Resume from a specific conversation ID
+- `mcp_servers` - MCP server configuration
+
+## Error Handling
+
+The SDK provides specific error types:
+
+```ruby
+begin
+  ClaudeSDK.query("Hello") do |message|
+    puts message
+  end
+rescue ClaudeSDK::CLINotFoundError => e
+  puts "Claude Code CLI not found: #{e.message}"
+rescue ClaudeSDK::CLIConnectionError => e
+  puts "Connection error: #{e.message}"
+rescue ClaudeSDK::ProcessError => e
+  puts "Process error: #{e.message}"
+end
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Node.js (for Claude Code CLI)
+- async gem for async support
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Run tests with coverage
+COVERAGE=true bundle exec rspec
+
+# Build the gem
+gem build claude-sdk-ruby.gemspec
+
+# Install locally
+gem install ./claude-sdk-ruby-0.1.0.gem
+```
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/anthropics/claude-code-sdk-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]
+
+desc "Run all tests and linting"
+task test: [:spec, :rubocop]

data/claude-code-sdk-ruby.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/claude_sdk/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "claude-code-sdk-ruby"
+  spec.version = ClaudeSDK::VERSION
+  spec.authors = ["Paulo Arruda"]
+  spec.email = ["parrudaj@gmail.com"]
+
+  spec.summary = "Ruby SDK for Claude Code"
+  spec.description = "Ruby SDK for interacting with Claude Code"
+  spec.homepage = "https://github.com/parruda/claude-code-sdk-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    %x(git ls-files -z).split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?("bin/", "test/", "spec/", "features/", ".git", ".github", "appveyor", "Gemfile")
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency("async", "~> 2.26")
+  spec.add_dependency("logger", "~> 1.7")
+end

data/examples/async_multiple_queries.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_sdk"
+require "async"
+
+# Example: Running multiple queries concurrently
+
+Async do |task|
+  queries = [
+    "What is the capital of France?",
+    "Explain Ruby blocks in one sentence",
+    "List 3 benefits of async programming",
+  ]
+
+  # Run queries concurrently
+  results = queries.map do |prompt|
+    task.async do
+      responses = []
+      ClaudeSDK.query(prompt) do |message|
+        if message.is_a?(ClaudeSDK::Messages::Assistant)
+          message.content.each do |block|
+            responses << block.text if block.is_a?(ClaudeSDK::ContentBlock::Text)
+          end
+        end
+      end
+      { prompt: prompt, response: responses.join(" ") }
+    end
+  end.map(&:wait)
+
+  # Display results
+  results.each do |result|
+    puts "\n💭 Question: #{result[:prompt]}"
+    puts "💡 Answer: #{result[:response]}"
+  end
+end

data/examples/basic_usage.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add lib to load path for development
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "async"
+require "claude_sdk/types"
+require "claude_sdk/errors"
+require "claude_sdk/internal/client"
+
+# Example of using the Ruby Claude SDK internal client
+#
+# This demonstrates:
+# - Creating an internal client
+# - Processing a query with options
+# - Handling different message types
+# - Error handling
+
+# Create options
+options = ClaudeSDK::ClaudeCodeOptions.new(
+  allowed_tools: ["bash", "read"],
+  max_turns: 3,
+  system_prompt: "You are a helpful coding assistant.",
+)
+
+# Create client
+client = ClaudeSDK::Internal::InternalClient.new
+
+# Process query
+Async do
+  puts "Sending query to Claude..."
+  puts "=" * 50
+
+  client.process_query("What is 2+2?", options) do |message|
+    case message
+    when ClaudeSDK::Messages::User
+      puts "\n[USER]"
+      puts message.content
+
+    when ClaudeSDK::Messages::Assistant
+      puts "\n[ASSISTANT]"
+      message.content.each do |block|
+        case block
+        when ClaudeSDK::ContentBlock::Text
+          puts block.text
+        when ClaudeSDK::ContentBlock::ToolUse
+          puts "Tool Use: #{block.name}"
+          puts "Input: #{block.input.inspect}"
+        when ClaudeSDK::ContentBlock::ToolResult
+          puts "Tool Result for #{block.tool_use_id}"
+          puts "Content: #{block.content}"
+          puts "Error: #{block.is_error}" if block.is_error
+        end
+      end
+
+    when ClaudeSDK::Messages::System
+      puts "\n[SYSTEM: #{message.subtype}]"
+      puts message.data.inspect
+
+    when ClaudeSDK::Messages::Result
+      puts "\n[RESULT]"
+      puts "Session ID: #{message.session_id}"
+      puts "Duration: #{message.duration_ms}ms (API: #{message.duration_api_ms}ms)"
+      puts "Turns: #{message.num_turns}"
+      puts "Cost: $#{message.total_cost_usd}" if message.total_cost_usd
+      puts "Error: #{message.is_error}" if message.is_error
+    end
+  end
+rescue ClaudeSDK::CLINotFoundError => e
+  puts "Error: #{e.message}"
+  puts "Please install Claude Code CLI first"
+rescue ClaudeSDK::CLIConnectionError => e
+  puts "Connection error: #{e.message}"
+rescue ClaudeSDK::ProcessError => e
+  puts "Process error: #{e.message}"
+  puts "Exit code: #{e.exit_code}" if e.exit_code
+  puts "Stderr: #{e.stderr}" if e.stderr
+rescue StandardError => e
+  puts "Unexpected error: #{e.class} - #{e.message}"
+  puts e.backtrace
+end

data/examples/enumerator_usage.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_sdk"
+
+# Example: Using enumerators for fine-grained control
+
+# Get an enumerator instead of using a block
+messages = ClaudeSDK.query("Write a haiku about Ruby programming")
+
+# Process messages with more control
+message_count = 0
+assistant_messages = []
+
+begin
+  loop do
+    message = messages.next
+    message_count += 1
+
+    case message
+    when ClaudeSDK::Messages::User
+      puts "📨 Message #{message_count}: User prompt received"
+
+    when ClaudeSDK::Messages::Assistant
+      assistant_messages << message
+      text_blocks = message.content.select { |b| b.is_a?(ClaudeSDK::ContentBlock::Text) }
+      puts "🤖 Message #{message_count}: Assistant responded with #{text_blocks.count} text blocks"
+
+      # We could break early if we wanted
+      # break if text_blocks.any? { |b| b.text.include?("haiku") }
+
+    when ClaudeSDK::Messages::System
+      puts "⚙️  Message #{message_count}: System message (#{message.subtype})"
+
+    when ClaudeSDK::Messages::Result
+      puts "✅ Message #{message_count}: Completed in #{message.duration_ms}ms"
+      break # End of conversation
+    end
+  end
+rescue StopIteration
+  # Normal end of enumeration
+end
+
+# Display the haiku
+puts "\n📝 Generated Haiku:"
+assistant_messages.each do |msg|
+  msg.content.each do |block|
+    puts block.text if block.is_a?(ClaudeSDK::ContentBlock::Text)
+  end
+end

data/examples/error_handling.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_sdk"
+
+# Example: Proper error handling with ClaudeSDK
+
+begin
+  ClaudeSDK.query("Hello, Claude!") do |message|
+    puts message.inspect
+  end
+rescue ClaudeSDK::CLINotFoundError => e
+  puts "❌ Claude CLI not found!"
+  puts e.message
+  puts "\nTo install Claude CLI:"
+  puts "  npm install -g @anthropic-ai/claude-code"
+rescue ClaudeSDK::CLIConnectionError => e
+  puts "❌ Failed to connect to Claude CLI"
+  puts e.message
+rescue ClaudeSDK::ProcessError => e
+  puts "❌ Process failed"
+  puts "Exit code: #{e.exit_code}"
+  puts "Error output: #{e.stderr}"
+rescue ClaudeSDK::Error => e
+  # Catch any other ClaudeSDK errors
+  puts "❌ An error occurred: #{e.message}"
+rescue StandardError => e
+  # Catch unexpected errors
+  puts "❌ Unexpected error: #{e.class} - #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+end

data/examples/mcp_servers.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_sdk"
+
+# Example: Using MCP (Model Context Protocol) servers
+
+# Configure MCP servers
+mcp_servers = {
+  "filesystem" => {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+  },
+  "git" => {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-git", "--repository", "."],
+  },
+}
+
+# Create options with MCP servers
+options = ClaudeSDK::ClaudeCodeOptions.new(
+  mcp_servers: mcp_servers,
+  mcp_tools: ["read_file", "write_file", "git_status", "git_diff"],
+)
+
+# Query using MCP tools
+ClaudeSDK.query("Read the README.md file and summarize it", options: options) do |message|
+  case message
+  when ClaudeSDK::Messages::Assistant
+    message.content.each do |block|
+      if block.is_a?(ClaudeSDK::ContentBlock::ToolUse) && block.name.start_with?("mcp_")
+        puts "🔌 Using MCP tool: #{block.name}"
+        puts "   Server: #{block.name.split("_")[1]}"
+        puts "   Input: #{block.input.inspect}"
+      elsif block.is_a?(ClaudeSDK::ContentBlock::Text)
+        puts "📝 #{block.text}"
+      end
+    end
+  when ClaudeSDK::Messages::Result
+    puts "\n✅ Done! Used #{message.num_turns} turns"
+  end
+end

data/examples/with_options.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "claude_sdk"
+
+# Example: Using ClaudeSDK with various options
+
+# Create options with custom settings
+options = ClaudeSDK::ClaudeCodeOptions.new(
+  system_prompt: "You are a helpful Ruby programming assistant",
+  cwd: Dir.pwd,
+  max_thinking_tokens: 10_000,
+  permission_mode: :accept_edits, # Auto-accept file edits
+  allowed_tools: ["bash", "read", "write"],
+  model: "claude-3.5-sonnet",
+)
+
+# Query with options
+ClaudeSDK.query("Write a Ruby function to calculate fibonacci numbers", options: options) do |message|
+  case message
+  when ClaudeSDK::Messages::User
+    puts "\n👤 User: #{message.content}"
+  when ClaudeSDK::Messages::Assistant
+    message.content.each do |block|
+      case block
+      when ClaudeSDK::ContentBlock::Text
+        puts "\n🤖 Claude: #{block.text}"
+      when ClaudeSDK::ContentBlock::ToolUse
+        puts "\n🔧 Using tool: #{block.name}"
+        puts "   Input: #{block.input.inspect}"
+      when ClaudeSDK::ContentBlock::ToolResult
+        puts "\n📊 Tool result: #{block.content}"
+      end
+    end
+  when ClaudeSDK::Messages::Result
+    puts "\n✅ Completed!"
+    puts "   Duration: #{message.duration_ms}ms"
+    puts "   API calls: #{message.duration_api_ms}ms"
+    puts "   Total cost: $#{format("%.4f", message.total_cost_usd || 0)}"
+  end
+end