Claude Agent SDK for Ruby
An unofficial, community-maintained Ruby SDK for the Claude Code agent runtime. Not affiliated with or supported by Anthropic.
Official SDKs
Why a Ruby SDK?
Ruby powers a massive ecosystem — Rails, Sidekiq, Kamal, countless production web apps — but has no official Claude Agent SDK. This gem fills that gap so Ruby and Rails developers can build AI agents, automate coding workflows, and integrate Claude into existing applications without switching languages or shelling out to Python/Node.
All three SDKs share the same underlying mechanism: they spawn the claude CLI as a subprocess and communicate over stream-JSON on stdin/stdout. The wire protocol is identical, so Ruby gets the same capabilities as the official SDKs.
Comparison with Official SDKs
| Capability | TypeScript | Python | Ruby (this gem) |
|---|
One-shot query() | ✅ | ✅ | ✅ |
Bidirectional Client | ✅ | ✅ | ✅ |
| Streaming input | AsyncIterable | AsyncIterable | Enumerator |
| Custom tools (SDK MCP servers) | tool() | @tool decorator | create_tool block |
| Hooks (all 27 events) | ✅ | ✅ | ✅ |
| Permission callbacks | ✅ | ✅ | ✅ |
| Structured output | ✅ | ✅ | ✅ |
| All 24 message types | ✅ | partial | ✅ |
| Sandbox settings | ✅ | partial | ✅ |
Bare mode (--bare) | ✅ | ✅ | ✅ |
| File checkpointing & rewind | ✅ | ✅ | ✅ |
| Session browsing & mutations | ✅ | ✅ | ✅ |
| Programmatic subagents | ✅ | ✅ | ✅ |
| Bundled CLI binary | ✅ | ✅ | — (install claude separately) |
| Observability (OTel / Langfuse) | via Arize | — | ✅ (built-in) |
| Custom transport (pluggable I/O) | — | — | ✅ |
| Rails integration | — | — | ✅ |
Where Ruby goes further: Built-in OpenTelemetry observer with Langfuse flow diagram support — no third-party instrumentation library needed. Custom transport support lets you swap the subprocess for any I/O layer (e.g., connect to a remote Claude Code instance over SSH or a container). Rails integration provides a configure block for initializers with thread-safe observer factories, and plays well with ActionCable for real-time streaming. Full typed coverage for all 24 CLI message types and all 27 hook events — some of which the Python SDK hasn't typed yet.
What's missing: The Ruby gem does not bundle the claude CLI binary (npm install -g @anthropic-ai/claude-code).
Implementation differences from the official SDKs
Async model
TypeScript uses native async/await. Python uses async/await with anyio. Ruby uses the async gem with fibers — no await keyword needed, blocking calls yield automatically inside an Async block.
Async do
client = ClaudeAgentSDK::Client.new(options: options)
client.connect
client.query("Hello")
client.receive_messages { |msg| puts msg }
client.disconnect
end.wait
Types
TypeScript has Zod schemas with inferred types. Python uses dataclass with type annotations. Ruby uses plain classes with attr_accessor and keyword args — no runtime type checking, but the same structure and field names.
Subprocess transport
All three SDKs spawn claude CLI as a subprocess with stream-JSON over stdin/stdout. TypeScript uses Node child_process, Python uses anyio.open_process, Ruby uses Open3.popen3. The wire protocol is identical.
Table of Contents