Claude Code SDK Ruby

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.

Add this line to your application's Gemfile:

gem 'claude-code-sdk-ruby'

And then execute:

bundle install

Or install it yourself as:

gem install claude-code-sdk-ruby

This SDK requires the Claude Code CLI to be installed:

npm install -g @anthropic-ai/claude-code

You'll also need to configure your API key. Please refer to the Claude Code documentation for detailed setup instructions.

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

require 'claude_sdk'

ClaudeSDK.query("Hello, Claude!") do |message|
  puts message
end

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

require 'claude_sdk'

messages = ClaudeSDK.query("Hello")
messages.each do |message|
  puts message
end

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

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

Assistant messages contain content blocks:

• ClaudeSDK::ContentBlock::Text - Text content
• ClaudeSDK::ContentBlock::ToolUse - Tool usage
• ClaudeSDK::ContentBlock::ToolResult - Tool results

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

The SDK provides specific error types:

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

• Ruby 3.0 or higher
• Node.js (for Claude Code CLI)
• async gem for async support

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.

# Run tests
bundle exec rspec

# Run tests with coverage
COVERAGE=true bundle exec rspec

# Build the gem
gem build claude-code-sdk-ruby.gemspec

# Install locally
gem install ./claude-code-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.

Bug reports and pull requests are welcome on GitHub at https://github.com/parruda/claude-code-sdk-ruby.

The gem is available as open source under the terms of the MIT License.