Skip to content

Commit 459ea32

Browse files
drenzclaude
drenz
and
claude
committed
Initial commit for Claude Code SDK Ruby
Add Ruby SDK implementation for programmatic access to Claude Code CLI capabilities. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
0 parents  commit 459ea32

37 files changed

Lines changed: 1765 additions & 0 deletions

‎.DS_Store‎

6 KB
Binary file not shown.

‎.github/workflows/ci.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
ruby-version: ['3.0', '3.1', '3.2', '3.3']
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Ruby
20+
uses: ruby/setup-ruby@v1
21+
with:
22+
ruby-version: ${{ matrix.ruby-version }}
23+
bundler-cache: true
24+
25+
- name: Run tests
26+
run: bundle exec rake spec
27+
28+
- name: Run linter
29+
run: bundle exec rubocop
30+
31+
- name: Check documentation
32+
run: bundle exec yard stats --list-undoc
33+
34+
integration:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- uses: actions/checkout@v4
38+
39+
- name: Set up Ruby
40+
uses: ruby/setup-ruby@v1
41+
with:
42+
ruby-version: '3.2'
43+
bundler-cache: true
44+
45+
- name: Set up Node.js
46+
uses: actions/setup-node@v4
47+
with:
48+
node-version: '20'
49+
50+
- name: Install Claude Code CLI
51+
run: npm install -g @anthropic-ai/claude-code
52+
53+
- name: Run integration tests
54+
run: bundle exec rake integration
55+
env:
56+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

‎.gitignore‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
*.gem
2+
*.rbc
3+
/.config
4+
/coverage/
5+
/InstalledFiles
6+
/pkg/
7+
/spec/reports/
8+
/spec/examples.txt
9+
/test/tmp/
10+
/test/version_tmp/
11+
/tmp/
12+
13+
# Used by dotenv library to load environment variables.
14+
# .env
15+
16+
# Ignore Byebug command history file.
17+
.byebug_history
18+
19+
## Specific to RubyMotion:
20+
.dat*
21+
.repl_history
22+
build/
23+
*.bridgesupport
24+
build-iPhoneOS/
25+
build-iPhoneSimulator/
26+
27+
## Specific to RubyMotion (use of CocoaPods):
28+
#
29+
# We recommend against adding the Pods directory to your .gitignore. However
30+
# you should judge for yourself, the pros and cons are mentioned at:
31+
# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
32+
#
33+
# vendor/Pods/
34+
35+
## Documentation cache and generated files:
36+
/.yardoc/
37+
/_yardoc/
38+
/doc/
39+
/rdoc/
40+
41+
## Environment normalization:
42+
/.bundle/
43+
/vendor/bundle
44+
/lib/bundler/man/
45+
46+
# for a library or gem, you might want to ignore these files since the code is
47+
# intended to run in multiple environments; otherwise, check them in:
48+
Gemfile.lock
49+
.ruby-version
50+
.ruby-gemset
51+
52+
# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
53+
.rvmrc
54+
55+
# Used by RuboCop. Remote config files pulled in from inherit_from directive.
56+
# .rubocop-https?--*

‎.rspec‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
--require spec_helper
2+
--format documentation
3+
--color

‎.rubocop.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
require:
2+
- rubocop-rspec
3+
4+
plugins:
5+
- rubocop-rake
6+
7+
AllCops:
8+
TargetRubyVersion: 3.0
9+
NewCops: enable
10+
Exclude:
11+
- 'vendor/**/*'
12+
- 'spec/fixtures/**/*'
13+
- 'tmp/**/*'
14+
15+
Style/StringLiterals:
16+
Enabled: true
17+
EnforcedStyle: double_quotes
18+
19+
Style/StringLiteralsInInterpolation:
20+
Enabled: true
21+
EnforcedStyle: double_quotes
22+
23+
Layout/LineLength:
24+
Max: 120
25+
26+
Metrics/BlockLength:
27+
Exclude:
28+
- 'spec/**/*'
29+
- '*.gemspec'
30+
31+
Metrics/MethodLength:
32+
Max: 20
33+
34+
RSpec/ExampleLength:
35+
Max: 20
36+
37+
RSpec/MultipleExpectations:
38+
Max: 5

‎.yardopts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
--markup markdown
2+
--title "Claude Code SDK for Ruby"
3+
--charset utf-8
4+
--readme README.md
5+
--plugin yard-sorbet
6+
-
7+
LICENSE.txt

‎CHANGELOG.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2024-XX-XX
9+
10+
### Added
11+
- Initial release of Claude Code SDK for Ruby
12+
- Block-based API for streaming messages
13+
- Support for all message types (User, Assistant, System, Result)
14+
- Content block parsing (Text, ToolUse, ToolResult)
15+
- Comprehensive options configuration
16+
- Global configuration support
17+
- Error hierarchy with detailed error information
18+
- Transport abstraction with subprocess CLI implementation
19+
- Full compatibility with Claude Code CLI
20+
- Examples for common use cases
21+
- RSpec test suite
22+
- CI/CD configuration with GitHub Actions

‎CLAUDE.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
### Testing
8+
```bash
9+
# Run all tests
10+
bundle exec rake spec
11+
12+
# Run tests with coverage
13+
bundle exec rake coverage
14+
15+
# Run integration tests (requires Claude Code CLI)
16+
bundle exec rake integration
17+
18+
# Default task (runs spec + rubocop)
19+
bundle exec rake
20+
```
21+
22+
### Code Quality
23+
```bash
24+
# Run linter
25+
bundle exec rubocop
26+
27+
# Generate documentation
28+
bundle exec yard
29+
```
30+
31+
### Development
32+
```bash
33+
# Install dependencies
34+
bundle install
35+
36+
# Open console with gem loaded
37+
bundle exec rake console
38+
39+
# Build and install gem locally
40+
bundle exec rake install
41+
42+
# Release gem (updates version, creates tag, pushes to rubygems)
43+
bundle exec rake release
44+
```
45+
46+
## Architecture Overview
47+
48+
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:
49+
50+
### Core Structure
51+
- **Main Entry Point**: `ClaudeCodeSDK` module provides `query()` and `ask()` methods
52+
- **Transport Layer**: Abstracts communication with Claude Code CLI via subprocess
53+
- **Message System**: Strongly typed message objects for different interaction types
54+
- **Configuration**: Global and per-query configuration options
55+
56+
### Key Components
57+
58+
**Transport Layer** (`lib/claude_code_sdk/transport/`):
59+
- `Base`: Abstract transport interface
60+
- `SimpleCLI`: Current implementation using direct CLI execution
61+
- `SubprocessCLI`: Alternative implementation (currently disabled due to subprocess issues)
62+
63+
**Message Types** (`lib/claude_code_sdk/messages.rb`):
64+
- `UserMessage`: User input
65+
- `AssistantMessage`: Claude's responses with content blocks (text, tool use, tool results)
66+
- `SystemMessage`: System notifications
67+
- `ResultMessage`: Session results with cost/usage data
68+
69+
**Configuration** (`lib/claude_code_sdk/configuration.rb`):
70+
- Singleton pattern for global defaults
71+
- Options object for per-query configuration
72+
- Supports all Claude Code CLI parameters (tools, permissions, prompts, etc.)
73+
74+
### Transport Implementation Details
75+
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.
76+
77+
### Prerequisites
78+
- Ruby >= 3.0.0
79+
- Claude Code CLI must be installed: `npm install -g @anthropic-ai/claude-code`
80+
- Zeitwerk for autoloading
81+
82+
### Testing Strategy
83+
- Unit tests for message parsing and configuration
84+
- Integration tests that require actual Claude Code CLI
85+
- Coverage reporting via SimpleCov
86+
- RuboCop for code style enforcement

‎Gemfile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# frozen_string_literal: true
2+
3+
source "https://rubygems.org"
4+
5+
# Specify your gem's dependencies in claude_code_sdk.gemspec
6+
gemspec
7+
8+
gem "rake", "~> 13.0"

‎LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2024 Anthropic
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

0 commit comments

Comments
 (0)