claude_code_sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ce4c61015be30c500aa333028e9f14b453144989b8e2040a0482a9914817286
+  data.tar.gz: dbb147b28512697a329e06a770a8e677c147a2ee2e85bdbca9f0347697b6e282
+SHA512:
+  metadata.gz: e8aff923ccef31394dcff359e9a7e4516d1c3fcb449fc69912e1fd7e53d00ab6fa084b7bf5b140b89e28781015b153e0835f292352a6beb7f0dc030ec099bb0c
+  data.tar.gz: d684035d8a139a67b83dd6cebffde09511dc6e0d6bc07035d4fe155b9b397f69d793f68c782be2b85e6970709697b67e4d0a18a02c5f361465875cba57706426

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,38 @@
+require:
+  - rubocop-rspec
+
+plugins:
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'tmp/**/*'
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 20
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 5

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--title "Claude Code SDK for Ruby"
+--charset utf-8
+--readme README.md
+--plugin yard-sorbet
+-
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 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]
+
+## [0.1.0] - 2025-01-10
+
+### Added
+- Initial release of Claude Code SDK for Ruby
+- Complete port of the official Python SDK functionality
+- Support for all Claude Code CLI features including:
+  - File operations (read, write, list)
+  - Code generation and refactoring
+  - Interactive development with streaming responses
+  - Tool permissions and restrictions
+  - System prompts and configuration
+- Strongly typed message system with content blocks
+- Global and per-query configuration options
+- Comprehensive error handling
+- Full test suite with RSpec
+- Integration tests for CLI interaction
+- Support for Ruby 3.0 and above
+
+### Developer Experience
+- Ruby idiomatic API with block-based iteration
+- Flexible configuration with sensible defaults
+- Detailed documentation and examples
+- RuboCop style enforcement
+- YARD documentation support
+
+[Unreleased]: https://github.com/TanookiLabs/claude-code-sdk-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/TanookiLabs/claude-code-sdk-ruby/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run tests with coverage
+bundle exec rake coverage
+
+# Run integration tests (requires Claude Code CLI)
+bundle exec rake integration
+
+# Default task (runs spec + rubocop)
+bundle exec rake
+```
+
+### Code Quality
+```bash
+# Run linter
+bundle exec rubocop
+
+# Generate documentation
+bundle exec yard
+```
+
+### Development
+```bash
+# Install dependencies
+bundle install
+
+# Open console with gem loaded
+bundle exec rake console
+
+# Build and install gem locally
+bundle exec rake install
+
+# Release gem (updates version, creates tag, pushes to rubygems)
+bundle exec rake release
+```
+
+## Architecture Overview
+
+This is a Ruby SDK for Claude Code CLI that provides a Ruby interface to Anthropic's AI coding assistant. The architecture follows these key patterns:
+
+### Core Structure
+- **Main Entry Point**: `ClaudeCodeSDK` module provides `query()` and `ask()` methods
+- **Transport Layer**: Abstracts communication with Claude Code CLI via subprocess
+- **Message System**: Strongly typed message objects for different interaction types
+- **Configuration**: Global and per-query configuration options
+
+### Key Components
+
+**Transport Layer** (`lib/claude_code_sdk/transport/`):
+- `Base`: Abstract transport interface
+- `SimpleCLI`: Current implementation using direct CLI execution
+- `SubprocessCLI`: Alternative implementation (currently disabled due to subprocess issues)
+
+**Message Types** (`lib/claude_code_sdk/messages.rb`):
+- `UserMessage`: User input
+- `AssistantMessage`: Claude's responses with content blocks (text, tool use, tool results)
+- `SystemMessage`: System notifications
+- `ResultMessage`: Session results with cost/usage data
+
+**Configuration** (`lib/claude_code_sdk/configuration.rb`):
+- Singleton pattern for global defaults
+- Options object for per-query configuration
+- Supports all Claude Code CLI parameters (tools, permissions, prompts, etc.)
+
+### Transport Implementation Details
+The SDK currently uses `SimpleCLI` transport which spawns the Claude Code CLI process for each query. The CLI communication happens via JSON message streaming, with the SDK parsing and converting CLI output into strongly-typed Ruby message objects.
+
+### Prerequisites
+- Ruby >= 3.0.0
+- Claude Code CLI must be installed: `npm install -g @anthropic-ai/claude-code`
+- Zeitwerk for autoloading
+
+### Testing Strategy
+- Unit tests for message parsing and configuration
+- Integration tests that require actual Claude Code CLI
+- Coverage reporting via SimpleCov
+- RuboCop for code style enforcement

data/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Claude Code SDK for Ruby
+
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## We Develop with GitHub
+
+We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use [GitHub Flow](https://guides.github.com/introduction/flow/index.html)
+
+All code changes happen through pull requests. We actively welcome your pull requests:
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## Any contributions you make will be under the MIT Software License
+
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using GitHub's [issues](https://github.com/TanookiLabs/claude-code-sdk-ruby/issues)
+
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/TanookiLabs/claude-code-sdk-ruby/issues/new); it's that easy!
+
+## Write bug reports with detail, background, and sample code
+
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+## Development Process
+
+1. Clone the repository
+2. Run `bundle install` to install dependencies
+3. Run `bundle exec rake spec` to run tests
+4. Make your changes
+5. Add tests for your changes
+6. Run `bundle exec rubocop` to ensure code style
+7. Create a pull request
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run with coverage
+bundle exec rake coverage
+
+# Run integration tests (requires Claude Code CLI)
+bundle exec rake integration
+
+# Run linter
+bundle exec rubocop
+```
+
+### Code Style
+
+We use RuboCop to maintain consistent code style. Please ensure your code passes RuboCop checks before submitting.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under its MIT License.
+
+## References
+
+This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanooki Labs LLC
+
+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,304 @@
+# Claude Code SDK for Ruby
+
+[![Gem Version](https://badge.fury.io/rb/claude_code_sdk.svg)](https://badge.fury.io/rb/claude_code_sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-ruby.svg)](https://www.ruby-lang.org)
+
+A Ruby port of the official Python SDK for Claude Code, providing a clean, idiomatic Ruby interface for interacting with Anthropic's Claude Code AI assistant. This gem enables Ruby developers to harness the power of Claude's advanced AI capabilities for code generation, refactoring, debugging, and more.
+
+## Why Claude Code SDK for Ruby?
+
+- **Fully Featured**: Complete port of the official Python SDK with all the same functionality
+- **Ruby Idiomatic**: Designed with Ruby best practices in mind - blocks, enumerables, and familiar patterns
+- **Real-time Streaming**: Process Claude's responses as they arrive for a responsive experience
+- **Type-Safe Messages**: Strongly typed message objects for better code clarity and error prevention
+- **Flexible Configuration**: Global defaults with per-query overrides
+- **Comprehensive Tool Support**: Access to all Claude Code tools including file operations, search, and more
+- **Production Ready**: Robust error handling, comprehensive test coverage, and battle-tested implementation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'claude_code_sdk'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install claude_code_sdk
+
+## Prerequisites
+
+The SDK requires the Claude Code CLI to be installed:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Make sure you have your Anthropic API key configured:
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+## Quick Start
+
+```ruby
+require 'claude_code_sdk'
+
+# Simple question
+response = ClaudeCodeSDK.ask("What's the best way to implement a singleton in Ruby?")
+puts response
+
+# Code generation with streaming
+ClaudeCodeSDK.query("Create a Ruby class for managing a todo list") do |message|
+  if message.is_a?(ClaudeCodeSDK::AssistantMessage)
+    message.content.each do |block|
+      print block.text if block.is_a?(ClaudeCodeSDK::Content::TextBlock)
+    end
+  end
+end
+```
+
+## Key Features
+
+### 1. Code Generation and Refactoring
+
+```ruby
+# Generate code with specific requirements
+ClaudeCodeSDK.query(
+  "Create a thread-safe cache implementation with TTL support",
+  system_prompt: "You are an expert Ruby developer focused on performance and thread safety"
+) do |message|
+  # Handle streaming responses
+end
+
+# Refactor existing code
+code = File.read("legacy_code.rb")
+ClaudeCodeSDK.ask("Refactor this code to use modern Ruby patterns:\n\n#{code}")
+```
+
+### 2. File Operations
+
+```ruby
+# Allow Claude to read and modify files
+ClaudeCodeSDK.query(
+  "Update all test files to use RSpec 3 syntax",
+  allowed_tools: ["read_file", "write_file", "list_files"],
+  cwd: Rails.root.to_s
+) do |message|
+  # Claude will analyze and update your test files
+end
+```
+
+### 3. Code Analysis and Debugging
+
+```ruby
+# Analyze code for potential issues
+ClaudeCodeSDK.query(
+  "Analyze this Rails controller for security vulnerabilities and performance issues",
+  allowed_tools: ["read_file"],
+  tree: ["app/controllers"],
+  tree_verbose: true
+) do |message|
+  # Get detailed analysis with file context
+end
+```
+
+### 4. Interactive Development
+
+```ruby
+# Build features interactively
+options = ClaudeCodeSDK::Options.new(
+  allowed_tools: ["read_file", "write_file", "bash"],
+  permission_mode: ClaudeCodeSDK::PermissionMode::ACCEPT_EDITS,
+  max_thinking_tokens: 20000
+)
+
+ClaudeCodeSDK.query("Help me add user authentication to my Sinatra app", options) do |message|
+  case message
+  when ClaudeCodeSDK::AssistantMessage
+    # Claude's responses and actions
+  when ClaudeCodeSDK::SystemMessage
+    puts "[System] #{message.title}: #{message.message}"
+  when ClaudeCodeSDK::ResultMessage
+    puts "Task completed! Cost: $#{message.cost[:usd]}"
+  end
+end
+```
+
+## Advanced Usage
+
+### Global Configuration
+
+```ruby
+ClaudeCodeSDK.configure do |config|
+  config.default_system_prompt = "You are a Ruby on Rails expert"
+  config.default_cwd = Rails.root.to_s
+  config.default_permission_mode = ClaudeCodeSDK::PermissionMode::DEFAULT
+  config.default_allowed_tools = ["read_file", "list_files"]
+end
+```
+
+### Working with Message Types
+
+```ruby
+ClaudeCodeSDK.query("Build a REST API endpoint") do |message|
+  case message
+  when ClaudeCodeSDK::UserMessage
+    # Your input to Claude
+    
+  when ClaudeCodeSDK::AssistantMessage
+    message.content.each do |block|
+      case block
+      when ClaudeCodeSDK::Content::TextBlock
+        # Claude's text responses
+        puts block.text
+        
+      when ClaudeCodeSDK::Content::ToolUseBlock
+        # Claude using a tool
+        puts "Using tool: #{block.name}"
+        
+      when ClaudeCodeSDK::Content::ToolResultBlock
+        # Results from tool execution
+        puts "Tool output: #{block.output}"
+      end
+    end
+    
+  when ClaudeCodeSDK::SystemMessage
+    # System notifications
+    
+  when ClaudeCodeSDK::ResultMessage
+    # Final results with usage stats
+    puts "Tokens used: #{message.usage[:total_tokens]}"
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  ClaudeCodeSDK.query("Complex task") do |message|
+    # Handle messages
+  end
+rescue ClaudeCodeSDK::CLINotFoundError => e
+  # Claude Code CLI not installed
+rescue ClaudeCodeSDK::ProcessError => e
+  # Process execution failed
+  puts "Exit code: #{e.exit_code}"
+  puts "Error: #{e.stderr}"
+rescue ClaudeCodeSDK::TimeoutError => e
+  # Operation timed out
+rescue ClaudeCodeSDK::CLIJSONDecodeError => e
+  # Invalid response from CLI
+end
+```
+
+## Options Reference
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `allowed_tools` | Array | Tools Claude can use (e.g., `["read_file", "write_file"]`) |
+| `blocked_tools` | Array | Tools Claude cannot use |
+| `permission_mode` | String | File edit handling: `"default"`, `"acceptEdits"`, `"bypassPermissions"` |
+| `max_thinking_tokens` | Integer | Max tokens for Claude's reasoning (default: 8000) |
+| `system_prompt` | String | System instructions for Claude |
+| `cwd` | String | Working directory for file operations |
+| `mcp_servers` | Array | MCP server configurations |
+| `disable_cache` | Boolean | Disable response caching |
+| `no_markdown` | Boolean | Disable markdown formatting |
+| `tree` | Array | Paths to include in file tree context |
+| `tree_symlinks` | Boolean | Include symlinks in file tree |
+| `tree_verbose` | Boolean | Verbose file tree output |
+
+## Real-World Examples
+
+### Rails Development Assistant
+
+```ruby
+# Help with Rails development tasks
+ClaudeCodeSDK.query(
+  "Add a full-text search feature to the Product model using PostgreSQL",
+  allowed_tools: ["read_file", "write_file", "bash"],
+  cwd: Rails.root.to_s,
+  system_prompt: "You are a Rails expert. Follow Rails conventions and best practices."
+) do |message|
+  # Claude will analyze your models, create migrations, and implement search
+end
+```
+
+### Test Generation
+
+```ruby
+# Generate comprehensive tests
+ClaudeCodeSDK.query(
+  "Generate RSpec tests for the UserService class with full coverage",
+  allowed_tools: ["read_file", "write_file"],
+  tree: ["app/services", "spec"]
+) do |message|
+  # Claude analyzes your code and creates thorough test suites
+end
+```
+
+### Code Review Assistant
+
+```ruby
+# Automated code review
+changed_files = `git diff --name-only main`.split("\n")
+ClaudeCodeSDK.query(
+  "Review these changed files for code quality, potential bugs, and improvements",
+  allowed_tools: ["read_file"],
+  tree: changed_files
+) do |message|
+  # Get detailed code review feedback
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run tests with coverage
+bundle exec rake coverage
+
+# Run integration tests (requires Claude Code CLI)
+bundle exec rake integration
+
+# Run linter
+bundle exec rubocop
+
+# Open console for experimentation
+bundle exec rake console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TanookiLabs/claude-code-sdk-ruby. This project is intended to be a safe, welcoming space for collaboration.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## About Tanooki Labs
+
+Claude Code SDK for Ruby is maintained by [Tanooki Labs LLC](https://tanookilabs.com), a software consultancy specializing in AI-powered developer tools and Ruby applications.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+This gem is a Ruby port of the official Python SDK for Claude Code. We thank Anthropic for creating Claude and the Claude Code CLI that makes this integration possible.

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+YARD::Rake::YardocTask.new
+
+task default: %i[spec rubocop]
+
+desc "Run tests with coverage"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task["spec"].invoke
+end
+
+desc "Open an IRB session with the gem loaded"
+task :console do
+  require "irb"
+  require "claude_code_sdk"
+  ARGV.clear
+  IRB.start
+end
+
+desc "Run integration tests (requires Claude Code CLI)"
+task :integration do
+  ENV["INTEGRATION"] = "true"
+  Rake::Task["spec"].invoke
+end

data/claude_code_sdk.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "lib/claude_code_sdk/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "claude_code_sdk"
+  spec.version = ClaudeCodeSDK::VERSION
+  spec.authors = ["Tanooki Labs LLC"]
+  spec.email = ["hello@tanookilabs.com"]
+
+  spec.summary = "Ruby SDK for Claude Code - AI-powered coding assistant"
+  spec.description = "A Ruby port of the official Python SDK for Claude Code. This gem provides a clean, idiomatic Ruby interface for interacting with Anthropic's Claude Code AI assistant through the command-line interface."
+  spec.homepage = "https://github.com/TanookiLabs/claude-code-sdk-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/claude_code_sdk"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Files to include in the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github 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 "zeitwerk", "~> 2.6"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "webmock", "~> 3.19"
+  spec.add_development_dependency "yard", "~> 0.9"
+
+  # Optional runtime dependencies
+  spec.add_development_dependency "async", "~> 2.0" # For async support
+  spec.add_development_dependency "sorbet-runtime", "~> 0.5" # For type checking
+end