Claude Agent SDK for Ruby

https://github.com/ya-luotao/claude-agent-sdk-ruby
Admin
An unofficial Ruby SDK for the Claude Code agent runtime that enables Ruby developers to build AI...
Tokens:71,898
Snippets:519
Trust Score:8.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install optional example dependencies

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md

Install the backend client gems required for the example adapters by configuring the :examples Bundler group.

```bash
bundle config set --local with examples
bundle install
```

--------------------------------

### Run example tests with Docker

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md

Start Redis and PostgreSQL containers and run the example specs by providing the necessary connection URLs.

```bash
docker run -d -p 6379:6379 redis:7-alpine
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine

SESSION_STORE_REDIS_URL=redis://localhost:6379/0 \
SESSION_STORE_POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/postgres \
  bundle exec rspec spec/examples/
```

--------------------------------

### bin/setup: Install CLI with environment variable

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md

A bin/setup script that installs the CLI using the CLAUDE_CLI_VERSION environment variable, defaulting to 'stable'. This is suitable for local development setup.

```ruby
#!/usr/bin/env ruby
# bin/setup
require 'claude_agent_sdk'
puts ClaudeAgentSDK::CLIInstaller.install(version: ENV.fetch('CLAUDE_CLI_VERSION', 'stable'))
```

--------------------------------

### Install dependencies with bundle install

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md

Install required dependencies for the project.

```bash
bundle install
```

--------------------------------

### Quick Start: one-shot query

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Run a single conversation with query() and yield each response message to the block. The example prints the text of assistant messages.

```ruby
require 'claude_agent_sdk'

ClaudeAgentSDK.query(prompt: "What is 2 + 2?") do |message|
  puts message.text if message.is_a?(ClaudeAgentSDK::AssistantMessage)
end
```

--------------------------------

### Install OTel gems for Langfuse

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/observability.md

Install the OpenTelemetry gems required for Langfuse integration. The SDK does not bundle these gems; you choose your exporter. Use the gem install command for a one-off setup or add the Gemfile lines for a project.

```bash
gem install opentelemetry-sdk opentelemetry-exporter-otlp
```

```ruby
gem 'opentelemetry-sdk', '~> 1.4'
gem 'opentelemetry-exporter-otlp', '~> 0.28'
```

--------------------------------

### Install CLI with version and custom directory

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md

Install a pinned version of the claude CLI into the default vendor directory or a custom directory. The install is idempotent and safe to run concurrently. The installed_path method returns nil unless a binary is already installed.

```ruby
require 'claude_agent_sdk'

# 'stable' (default), 'latest', or a concrete version — pin it in production.
ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
# => "/app/vendor/claude/claude"

ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220', dir: '/opt/claude')

# nil unless a binary is already installed there
ClaudeAgentSDK::CLIInstaller.installed_path
```

--------------------------------

### Check Claude CLI installation

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md

Verify that the Claude CLI is installed and check its version.

```bash
which claude
claude -v
```

--------------------------------

### Create custom tool and SDK MCP server

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Define a Ruby block tool and register it as an SDK MCP server. Arguments are validated against the tool's JSON Schema before the handler runs; handler exceptions are reported back to the model in-band. The example creates a 'greet' tool and configures options to use it.

```ruby
greet = ClaudeAgentSDK.create_tool('greet', 'Greet a user', { name: :string }) do |args|
  { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
end

server = ClaudeAgentSDK.create_sdk_mcp_server(name: 'my-tools', tools: [greet])

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  mcp_servers: { tools: server },
  allowed_tools: ['mcp__tools__greet']
)
```

--------------------------------

### Add and install Claude Code plugin marketplace

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Use these commands to add the plugin marketplace and install the claude-agent-ruby plugin from the claude-agent-sdk-ruby marketplace.

```bash
/plugin marketplace add ya-luotao/claude-agent-sdk-ruby
/plugin install claude-agent-ruby@claude-agent-sdk-ruby
```

--------------------------------

### Add claude-agent-sdk to Gemfile

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Add the gem to your Gemfile with version constraint ~> 0.31.0. Then run bundle install or gem install claude-agent-sdk. To track unreleased changes, point the Gemfile at GitHub: gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'.

```ruby
# Gemfile
gem 'claude-agent-sdk', '~> 0.31.0'
```

--------------------------------

### Stream multiple user messages with Streaming.from_array

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Pass an Enumerator to query() to stream several user messages into one session. The example creates a stream from an array of strings and prints assistant messages.

```ruby
stream = ClaudeAgentSDK::Streaming.from_array(['Hello!', 'What is 2+2?', 'Thanks!'])

ClaudeAgentSDK.query(prompt: stream) do |message|
  puts message if message.is_a?(ClaudeAgentSDK::AssistantMessage)
end
```

--------------------------------

### Client bidirectional session

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Keep a session open for follow-up queries, interrupts, model switching, hooks, permission callbacks, and custom tools. Must run inside an async block; blocking calls yield automatically. The example connects, queries, receives responses, and disconnects in an ensure block.

```ruby
require 'claude_agent_sdk'
require 'async'

Async do
  client = ClaudeAgentSDK::Client.new

  begin
    client.connect
    client.query("What is the capital of France?")
    client.receive_response { |msg| puts msg }
  ensure
    client.disconnect
  end
end.wait
```

--------------------------------

### Create and use an SDK MCP server with a greet tool

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/plugins/claude-agent-ruby/skills/claude-agent-ruby/references/mcp-servers.md

Creates an in-process SDK MCP server with a single tool, mounts it in ClaudeAgentOptions, and runs a client session that queries the tool. The tool returns a text content block; the client connects, sends a query, and prints the response. Requires the async gem and the claude_agent_sdk gem.

```ruby
require "claude_agent_sdk"
require "async"

greet_tool = ClaudeAgentSDK.create_tool("greet", "Greet a user", { name: :string }) do |args|
  { content: [{ type: "text", text: "Hello, #{args[:name]}!" }] }
end

server = ClaudeAgentSDK.create_sdk_mcp_server(
  name: "tools",
  version: "1.0.0",
  tools: [greet_tool]
)

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  mcp_servers: { tools: server },
  allowed_tools: ["mcp__tools__greet"]
)

Async do
  client = ClaudeAgentSDK::Client.new(options: options)
  client.connect
  client.query("Greet Alice")
  client.receive_response { |msg| puts msg.inspect }
ensure
  client&.disconnect
end.wait
```

--------------------------------

### Create OTelObserver and run query

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/observability.md

Create an OTelObserver with optional session and user tags, attach it to ClaudeAgentOptions, and run a query. The observer groups traces by session and tags by user ID. For long-running apps, uncomment the shutdown call to flush before exit.

```ruby
require 'claude_agent_sdk'
require 'claude_agent_sdk/instrumentation'

observer = ClaudeAgentSDK::Instrumentation::OTelObserver.new(
  'langfuse.session.id' => 'my-session-123',  # optional: group traces by session
  'user.id' => 'user-42'                      # optional: tag with user ID
)

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  observers: [observer],
  allowed_tools: ['Bash', 'Read'],
  permission_mode: 'bypassPermissions'
)

ClaudeAgentSDK.query(prompt: "List files in /tmp", options: options) do |msg|
  puts msg.text if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
end

# For long-running apps, flush before exit:
# OpenTelemetry.tracer_provider.shutdown
```

--------------------------------

### Create a simple tool and MCP server

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md

Defines a 'greet' tool and registers it within an in-process MCP server, then configures the Claude agent to use it.

```ruby
require 'claude_agent_sdk'
require 'async'

greet_tool = ClaudeAgentSDK.create_tool(
  'greet', 'Greet a user', { name: :string },
  annotations: { title: 'Greeter', readOnlyHint: true }
) do |args|
  { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
end

server = ClaudeAgentSDK.create_sdk_mcp_server(
  name: 'my-tools',
  version: '1.0.0',
  tools: [greet_tool]
)

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  mcp_servers: { tools: server },
  allowed_tools: ['mcp__tools__greet']
)

Async do
  client = ClaudeAgentSDK::Client.new(options: options)
  client.connect
  client.query("Greet Alice")
  client.receive_response { |msg| puts msg }
  client.disconnect
end.wait
```

--------------------------------

### Run with detailed output

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md

Executes the test suite with the documentation formatter for detailed output.

```bash
bundle exec rspec --format documentation
```

--------------------------------

### Initialize PostgresSessionStore in Ruby

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md

Demonstrates how to connect to a PostgreSQL database using the pg gem and initialize the session store for use with the Claude Agent SDK.

```ruby
require 'pg'
require 'claude_agent_sdk'
require_relative 'postgres_session_store'

conn  = PG.connect('postgresql://localhost/mydb')
store = PostgresSessionStore.new(conn: conn)
store.create_schema  # idempotent CREATE TABLE IF NOT EXISTS

ClaudeAgentSDK.query(
  prompt: 'Hello!',
  options: ClaudeAgentSDK::ClaudeAgentOptions.new(session_store: store)
) do |message|
  puts message.result if message.is_a?(ClaudeAgentSDK::ResultMessage) && message.subtype == 'success'
end
```

--------------------------------

### Install Claude Code CLI globally

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md

Install the Claude Code CLI globally via npm.

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

--------------------------------

### Test SDK tool and server

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md

Create a tool and an SDK MCP server, then call the tool.

```ruby
tool = ClaudeAgentSDK.create_tool('test_tool', 'Description', { arg: :string }) do |args|
  { content: [{ type: 'text', text: "Result: #{args[:arg]}" }] }
end

server = ClaudeAgentSDK.create_sdk_mcp_server(
  name: 'test_server',
  tools: [tool]
)

result = server[:instance].call_tool('test_tool', { arg: 'value' })
```

--------------------------------

### Bare mode configuration

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/skills/references/usage-map.md

Initializes the agent with minimal startup options, including system prompts and permission bypass.

```ruby
options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  bare: true,
  system_prompt: 'You are a helpful assistant.',
  add_dirs: ['/path/to/project'],
  permission_mode: 'bypassPermissions'
)

ClaudeAgentSDK.query(prompt: "Review this code", options: options) do |msg|
  puts msg if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
end
```

--------------------------------

### Basic Client Usage with Async

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/client.md

Establishes a connection, sends a query, and processes assistant and result messages. Uses Async block and ensures disconnect in an ensure block.

```ruby
require 'claude_agent_sdk'
require 'async'

Async do
  client = ClaudeAgentSDK::Client.new

  begin
    client.connect
    client.query("What is the capital of France?")

    client.receive_response do |msg|
      case msg
      when ClaudeAgentSDK::AssistantMessage
        puts msg.text
      when ClaudeAgentSDK::ResultMessage
        puts "Cost: $#{msg.total_cost_usd}" if msg.total_cost_usd
      end
    end
  ensure
    client.disconnect
  end
end.wait
```

--------------------------------

### TaskStartedMessage

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/types.md

Typed subclass of SystemMessage for task started events.

```APIDOC
## TaskStartedMessage

### Description
Typed subclass of SystemMessage for task started events. Inherits from SystemMessage, so is_a?(SystemMessage) still works.

### Attributes
- **task_id** - Task identifier.
- **description** - Task description.
- **uuid** - Unique identifier.
- **session_id** - Session identifier.
- **tool_use_id** - Tool use identifier.
- **task_type** - Task type.
- **workflow_name** - Workflow name.
- **prompt** - Prompt text.

### Example
```ruby
class TaskStartedMessage < SystemMessage
  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type, :workflow_name, :prompt
end
```
```

--------------------------------

### Mutate session metadata

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/skills/references/usage-map.md

Examples for renaming a session and managing session tags.

```ruby
# Rename a session
ClaudeAgentSDK.rename_session(session_id: 'uuid', title: 'My Feature Work')

# Tag a session
ClaudeAgentSDK.tag_session(session_id: 'uuid', tag: 'important')

# Clear a tag
ClaudeAgentSDK.tag_session(session_id: 'uuid', tag: nil)
```

--------------------------------

### Create a calculator tool server

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md

Implements 'add' and 'divide' tools and registers them in a single MCP server instance.

```ruby
add_tool = ClaudeAgentSDK.create_tool('add', 'Add two numbers', { a: :number, b: :number }) do |args|
  result = args[:a] + args[:b]
  { content: [{ type: 'text', text: "#{args[:a]} + #{args[:b]} = #{result}" }] }
end

divide_tool = ClaudeAgentSDK.create_tool('divide', 'Divide numbers', { a: :number, b: :number }) do |args|
  if args[:b] == 0
    { content: [{ type: 'text', text: 'Error: Division by zero' }], is_error: true }
  else
    { content: [{ type: 'text', text: "Result: #{args[:a] / args[:b]}" }] }
  end
end

calculator = ClaudeAgentSDK.create_sdk_mcp_server(
  name: 'calculator',
  tools: [add_tool, divide_tool]
)

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  mcp_servers: { calc: calculator },
  allowed_tools: ['mcp__calc__add', 'mcp__calc__divide']
)
```

--------------------------------

### query() with options

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/README.md

Configure a one-shot query with system prompt, allowed tools, permission mode, working directory, and max turns. The block receives each response message.

```ruby
options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  system_prompt: "You are a helpful assistant",
  allowed_tools: ['Read', 'Write', 'Bash'],
  permission_mode: 'acceptEdits',
  cwd: "/path/to/project",
  max_turns: 5
)

ClaudeAgentSDK.query(prompt: "Create a hello.rb file", options: options) do |message|
  puts message
end
```

--------------------------------

### E2B sandbox transport example

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/client.md

This sketch shows a working custom transport that runs the Claude Code CLI inside an E2B Firecracker microVM. It reuses the SDK's CommandBuilder to produce the same argv as SubprocessCLITransport, shell-escapes it for E2B's /bin/bash -l -c execution path, and streams stdout/stderr back through CommandHandle#each. The example intentionally omits production hardening such as inactivity watchdog, keepalive heartbeat, and stream reconnect.

```ruby
require 'claude_agent_sdk'
require 'e2b'

class E2BCliTransport < ClaudeAgentSDK::Transport
  def initialize(options, sandbox:, cli_path: '/usr/local/bin/claude')
    @options, @sandbox, @cli_path = options, sandbox, cli_path
  end

  def connect
    argv = ClaudeAgentSDK::CommandBuilder.new(@cli_path, @options).build
    cmd = argv.map { |a| Shellwords.shellescape(a.to_s) }.join(' ')
    @handle = @sandbox.commands.run(cmd, background: true, stdin: true,
                                    cwd: @options.cwd&.to_s, envs: build_env)
    @pid = @handle.pid
    @ready = true
  end

  def write(data)         = @sandbox.commands.send_stdin(@pid, data)
  def end_input           = @sandbox.commands.close_stdin(@pid)
  def close               = @handle&.kill
  def ready?              = @ready

  def read_messages(&block)
    buf = +''
    @handle.each do |stdout, stderr, _pty|
      next if stderr && !stderr.empty?
      stdout.each_line do |line|
        buf << line.strip
        begin
          yield JSON.parse(buf, symbolize_names: true)
          buf.clear
        rescue JSON::ParserError
          # JSON line split across reads — keep buffering
        end
      end
    end
    @handle.wait # raises E2B::CommandExitError on non-zero exit
  end
end

sandbox = E2B::Sandbox.create(template: 'base', timeout: 600)
Async do
  client = ClaudeAgentSDK::Client.new(
    options: options,
    transport_class: E2BCliTransport,
    transport_args: { sandbox: sandbox }
  )
  client.connect
  client.query('Hello from the sandbox!')
  client.receive_response { |msg| puts msg }
  client.disconnect
ensure
  sandbox.kill
end.wait
```

--------------------------------

### Install pinned Claude Code CLI binary

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/plugins/claude-agent-ruby/skills/claude-agent-ruby/references/troubleshooting.md

Use this method to vendor a specific version of the Claude Code CLI into the project's vendor directory.

```ruby
ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
```

--------------------------------

### Defining and Using an MCP Server in Ruby

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/IMPLEMENTATION.md

Shows how to define a custom tool, create an MCP server, and integrate it into ClaudeAgentOptions.

```ruby
# Define a tool
add_tool = ClaudeAgentSDK.create_tool('add', 'Add numbers', { a: :number, b: :number }) do |args|
  result = args[:a] + args[:b]
  { content: [{ type: 'text', text: "Result: #{result}" }] }
end

# Create server
server = ClaudeAgentSDK.create_sdk_mcp_server(name: 'calc', tools: [add_tool])

# Use with Claude
options = ClaudeAgentOptions.new(
  mcp_servers: { calc: server },
  allowed_tools: ['mcp__calc__add']
)
```

--------------------------------

### Initialize ClaudeAgentOptions with bare mode

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/skills/SKILL.md

Configures the agent for minimal startup by setting bare to true and providing explicit context via system_prompt and permission_mode.

```ruby
options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  bare: true,
  system_prompt: 'You are a code reviewer.',
  permission_mode: 'bypassPermissions'
)
```

--------------------------------

### Dockerfile: Pin CLI in cached layer

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md

Use this Dockerfile snippet to install the pinned CLI version during the Docker build, ensuring the binary is cached in its own layer for faster rebuilds.

```dockerfile
# Dockerfile — pin the CLI in its own cached layer
RUN bundle exec ruby -e "require 'claude_agent_sdk'; \
    ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')"
```

--------------------------------

### Configure mixed internal and external MCP servers

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md

Shows how to combine an in-process SDK server with an external subprocess-based MCP server.

```ruby
options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  mcp_servers: {
    internal: sdk_server,      # In-process SDK server
    external: {                # External subprocess server
      type: 'stdio',
      command: 'external-server'
    }
  }
)
```

--------------------------------

### Handle messages with Client#receive_response and stop on ResultMessage

Source: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/plugins/claude-agent-ruby/skills/claude-agent-ruby/references/message-handling.md

Use this block with Client#receive_response to handle each message. Stop processing when you encounter a ClaudeAgentSDK::ResultMessage, which signals the end of a turn. The example prints assistant text and, for result messages, the cost, session ID, and structured output when available.

```ruby
client.receive_response do |message|
  case message
  when ClaudeAgentSDK::AssistantMessage
    puts message.text
  when ClaudeAgentSDK::ResultMessage
    puts "Cost: $#{message.total_cost_usd}" if message.total_cost_usd
    puts "Session: #{message.session_id}"
    puts "Structured: #{message.structured_output.inspect}" if message.structured_output
  end
end
```
Tokens:
Raw