claude_code 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. checksums.yaml +7 -0
  2. data/.rspec +3 -0
  3. data/.rspec_status +114 -0
  4. data/.rubocop.yml +51 -0
  5. data/.yardopts +7 -0
  6. data/CHANGELOG.md +37 -0
  7. data/LICENSE +21 -0
  8. data/README.md +288 -0
  9. data/Rakefile +32 -0
  10. data/USAGE_EXAMPLES.md +428 -0
  11. data/claude_code.gemspec +47 -0
  12. data/docs/README.md +254 -0
  13. data/docs/mcp_integration.md +404 -0
  14. data/docs/streaming.md +316 -0
  15. data/examples/authentication_examples.rb +133 -0
  16. data/examples/basic_usage.rb +73 -0
  17. data/examples/conversation_resuming.rb +96 -0
  18. data/examples/irb_helpers.rb +168 -0
  19. data/examples/jsonl_cli_equivalent.rb +108 -0
  20. data/examples/mcp_examples.rb +166 -0
  21. data/examples/model_examples.rb +111 -0
  22. data/examples/quick_start.rb +75 -0
  23. data/examples/rails_sidekiq_example.rb +336 -0
  24. data/examples/streaming_examples.rb +195 -0
  25. data/examples/streaming_json_input.rb +171 -0
  26. data/hello.txt +1 -0
  27. data/lib/claude_code/client.rb +437 -0
  28. data/lib/claude_code/errors.rb +48 -0
  29. data/lib/claude_code/types.rb +237 -0
  30. data/lib/claude_code/version.rb +5 -0
  31. data/lib/claude_code.rb +265 -0
  32. metadata +219 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 1e89198b386fb44c13a460464648e8f45a6348082dbe3aaa41982c0f5a345b27
4
+ data.tar.gz: 1b65a49fc89bae14e5828f7fcdf8b95de2a83a38dea9d7a54837749bda907ec4
5
+ SHA512:
6
+ metadata.gz: c594f6ea648ef10a9ec3dbf976a4c586ca7daddba16458a5310f312bb8a89698c3e59e8322c42c467f62fe7d04379484e26be45ed06663466b949cc03679e22c
7
+ data.tar.gz: f31c12ac42ef0df771b9886754968239b0d3280334f06a7156569a38bdc4ddbf21e33354506c5499807f75981daf9f0edba8c0ab63087e131ee4c32da9fc58f2
data/.rspec ADDED
@@ -0,0 +1,3 @@
1
+ --require spec_helper
2
+ --color
3
+ --format progress
data/.rspec_status ADDED
@@ -0,0 +1,114 @@
1
+ example_id | status | run_time |
2
+ -------------------------------------------------- | ------ | --------------- |
3
+ ./spec/claude_code/client_spec.rb[1:1:1:1] | passed | 0.00034 seconds |
4
+ ./spec/claude_code/client_spec.rb[1:1:1:2] | passed | 0.0004 seconds |
5
+ ./spec/claude_code/client_spec.rb[1:1:1:3] | passed | 0.00034 seconds |
6
+ ./spec/claude_code/client_spec.rb[1:1:1:4] | passed | 0.00029 seconds |
7
+ ./spec/claude_code/client_spec.rb[1:1:2:1] | passed | 0.00018 seconds |
8
+ ./spec/claude_code/client_spec.rb[1:1:3:1] | passed | 0.00031 seconds |
9
+ ./spec/claude_code/client_spec.rb[1:1:4:1] | passed | 0.00044 seconds |
10
+ ./spec/claude_code/client_spec.rb[1:1:5:1] | passed | 0.00518 seconds |
11
+ ./spec/claude_code/client_spec.rb[1:1:5:2] | passed | 0.00037 seconds |
12
+ ./spec/claude_code/client_spec.rb[1:1:5:3] | passed | 0.00346 seconds |
13
+ ./spec/claude_code/client_spec.rb[1:2:1] | passed | 0.00007 seconds |
14
+ ./spec/claude_code/client_spec.rb[1:2:2] | passed | 0.00015 seconds |
15
+ ./spec/claude_code/client_spec.rb[1:2:3] | passed | 0.00018 seconds |
16
+ ./spec/claude_code/client_spec.rb[1:2:4] | passed | 0.00021 seconds |
17
+ ./spec/claude_code/client_spec.rb[1:3:1:1] | passed | 0.00005 seconds |
18
+ ./spec/claude_code/client_spec.rb[1:3:1:2] | passed | 0.00004 seconds |
19
+ ./spec/claude_code/client_spec.rb[1:3:2:1] | passed | 0.00005 seconds |
20
+ ./spec/claude_code/client_spec.rb[1:3:3:1] | passed | 0.00004 seconds |
21
+ ./spec/claude_code/client_spec.rb[1:3:4:1] | passed | 0.00048 seconds |
22
+ ./spec/claude_code/client_spec.rb[1:3:5:1] | passed | 0.00003 seconds |
23
+ ./spec/claude_code/client_spec.rb[1:3:5:2] | passed | 0.00003 seconds |
24
+ ./spec/claude_code/client_spec.rb[1:3:6:1] | passed | 0.00004 seconds |
25
+ ./spec/claude_code/client_spec.rb[1:3:6:2] | passed | 0.00005 seconds |
26
+ ./spec/claude_code/subprocess_cli_spec.rb[1:1:1:1] | passed | 0.00045 seconds |
27
+ ./spec/claude_code/subprocess_cli_spec.rb[1:1:1:2] | passed | 0.00038 seconds |
28
+ ./spec/claude_code/subprocess_cli_spec.rb[1:1:2:1] | passed | 0.00009 seconds |
29
+ ./spec/claude_code/subprocess_cli_spec.rb[1:1:3:1] | passed | 0.00036 seconds |
30
+ ./spec/claude_code/subprocess_cli_spec.rb[1:2:1] | passed | 0.00004 seconds |
31
+ ./spec/claude_code/subprocess_cli_spec.rb[1:2:2] | passed | 0.00006 seconds |
32
+ ./spec/claude_code/subprocess_cli_spec.rb[1:2:3] | passed | 0.00004 seconds |
33
+ ./spec/claude_code/subprocess_cli_spec.rb[1:2:4] | passed | 0.0005 seconds |
34
+ ./spec/claude_code/subprocess_cli_spec.rb[1:3:1] | passed | 0.001 seconds |
35
+ ./spec/claude_code/subprocess_cli_spec.rb[1:3:2] | passed | 0.00023 seconds |
36
+ ./spec/claude_code/subprocess_cli_spec.rb[1:3:3] | passed | 0.00014 seconds |
37
+ ./spec/claude_code/subprocess_cli_spec.rb[1:4:1] | passed | 0.00004 seconds |
38
+ ./spec/claude_code/subprocess_cli_spec.rb[1:4:2] | passed | 0.0001 seconds |
39
+ ./spec/claude_code/subprocess_cli_spec.rb[1:4:3] | passed | 0.00012 seconds |
40
+ ./spec/claude_code/subprocess_cli_spec.rb[1:5:1] | passed | 0.00028 seconds |
41
+ ./spec/claude_code/subprocess_cli_spec.rb[1:5:2] | passed | 0.00017 seconds |
42
+ ./spec/claude_code_spec.rb[1:1] | passed | 0.00484 seconds |
43
+ ./spec/claude_code_spec.rb[1:2:1] | passed | 0.00063 seconds |
44
+ ./spec/claude_code_spec.rb[1:2:2] | passed | 0.00033 seconds |
45
+ ./spec/claude_code_spec.rb[1:2:3] | passed | 0.00018 seconds |
46
+ ./spec/claude_code_spec.rb[1:2:4] | passed | 0.00019 seconds |
47
+ ./spec/claude_code_spec.rb[1:2:5] | passed | 0.00015 seconds |
48
+ ./spec/claude_code_spec.rb[1:2:6] | passed | 0.00017 seconds |
49
+ ./spec/claude_code_spec.rb[1:3:1] | passed | 0.00017 seconds |
50
+ ./spec/claude_code_spec.rb[1:3:2] | passed | 0.00018 seconds |
51
+ ./spec/claude_code_spec.rb[1:3:3] | passed | 0.00017 seconds |
52
+ ./spec/claude_code_spec.rb[1:3:4] | passed | 0.00019 seconds |
53
+ ./spec/claude_code_spec.rb[1:4:1] | passed | 0.00019 seconds |
54
+ ./spec/claude_code_spec.rb[1:4:2] | passed | 0.00022 seconds |
55
+ ./spec/claude_code_spec.rb[1:4:3] | passed | 0.00014 seconds |
56
+ ./spec/claude_code_spec.rb[1:5:1] | passed | 0.00014 seconds |
57
+ ./spec/claude_code_spec.rb[1:5:2] | passed | 0.00022 seconds |
58
+ ./spec/claude_code_spec.rb[1:6:1] | passed | 0.00017 seconds |
59
+ ./spec/claude_code_spec.rb[1:6:2] | passed | 0.00073 seconds |
60
+ ./spec/claude_code_spec.rb[1:6:3] | passed | 0.00028 seconds |
61
+ ./spec/claude_code_spec.rb[1:7:1] | passed | 0.00011 seconds |
62
+ ./spec/claude_code_spec.rb[1:7:2] | passed | 0.00011 seconds |
63
+ ./spec/claude_code_spec.rb[1:8:1] | passed | 0.0003 seconds |
64
+ ./spec/claude_code_spec.rb[1:8:2] | passed | 0.00131 seconds |
65
+ ./spec/claude_code_spec.rb[1:9:1:1] | passed | 0.00012 seconds |
66
+ ./spec/claude_code_spec.rb[1:9:1:2] | passed | 0.00063 seconds |
67
+ ./spec/claude_code_spec.rb[1:9:1:3] | passed | 0.0001 seconds |
68
+ ./spec/errors_spec.rb[1:1:1:1] | passed | 0.00002 seconds |
69
+ ./spec/errors_spec.rb[1:1:1:2] | passed | 0.00003 seconds |
70
+ ./spec/errors_spec.rb[1:1:2:1] | passed | 0.00002 seconds |
71
+ ./spec/errors_spec.rb[1:1:2:2] | passed | 0.00003 seconds |
72
+ ./spec/errors_spec.rb[1:1:2:3] | passed | 0.00003 seconds |
73
+ ./spec/errors_spec.rb[1:1:2:4] | passed | 0.00003 seconds |
74
+ ./spec/errors_spec.rb[1:1:3:1] | passed | 0.00004 seconds |
75
+ ./spec/errors_spec.rb[1:1:3:2] | passed | 0.00002 seconds |
76
+ ./spec/errors_spec.rb[1:1:4:1] | passed | 0.00003 seconds |
77
+ ./spec/errors_spec.rb[1:1:4:2] | passed | 0.00005 seconds |
78
+ ./spec/errors_spec.rb[1:1:4:3] | passed | 0.00003 seconds |
79
+ ./spec/errors_spec.rb[1:1:4:4] | passed | 0.00004 seconds |
80
+ ./spec/errors_spec.rb[1:1:4:5] | passed | 0.00004 seconds |
81
+ ./spec/errors_spec.rb[1:1:5:1] | passed | 0.00002 seconds |
82
+ ./spec/errors_spec.rb[1:1:5:2] | passed | 0.00003 seconds |
83
+ ./spec/errors_spec.rb[1:1:5:3] | passed | 0.00003 seconds |
84
+ ./spec/errors_spec.rb[1:1:5:4] | passed | 0.00003 seconds |
85
+ ./spec/errors_spec.rb[1:2:1] | passed | 0.00021 seconds |
86
+ ./spec/errors_spec.rb[1:2:2] | passed | 0.00015 seconds |
87
+ ./spec/errors_spec.rb[1:2:3] | passed | 0.00017 seconds |
88
+ ./spec/errors_spec.rb[1:2:4] | passed | 0.00016 seconds |
89
+ ./spec/errors_spec.rb[1:2:5] | passed | 0.00015 seconds |
90
+ ./spec/integration/claude_code_spec.rb[1:1:1:1] | passed | 0.00071 seconds |
91
+ ./spec/integration/claude_code_spec.rb[1:1:2:1] | passed | 0.00032 seconds |
92
+ ./spec/integration/claude_code_spec.rb[1:1:3:1] | passed | 0.00016 seconds |
93
+ ./spec/integration/claude_code_spec.rb[1:1:4:1] | passed | 0.00028 seconds |
94
+ ./spec/integration/claude_code_spec.rb[1:1:5:1] | passed | 0.00036 seconds |
95
+ ./spec/jsonl_helpers_spec.rb[1:1:1] | passed | 0.00003 seconds |
96
+ ./spec/jsonl_helpers_spec.rb[1:1:2] | passed | 0.00003 seconds |
97
+ ./spec/jsonl_helpers_spec.rb[1:1:3] | passed | 0.00002 seconds |
98
+ ./spec/jsonl_helpers_spec.rb[1:1:4] | passed | 0.00002 seconds |
99
+ ./spec/jsonl_helpers_spec.rb[1:2:1] | passed | 0.00005 seconds |
100
+ ./spec/jsonl_helpers_spec.rb[1:2:2] | passed | 0.00003 seconds |
101
+ ./spec/jsonl_helpers_spec.rb[1:2:3] | passed | 0.00003 seconds |
102
+ ./spec/jsonl_helpers_spec.rb[1:2:4] | passed | 0.00003 seconds |
103
+ ./spec/jsonl_helpers_spec.rb[1:3:1] | passed | 0.00011 seconds |
104
+ ./spec/jsonl_helpers_spec.rb[1:3:2] | passed | 0.00004 seconds |
105
+ ./spec/jsonl_helpers_spec.rb[1:3:3] | passed | 0.00005 seconds |
106
+ ./spec/jsonl_helpers_spec.rb[1:3:4] | passed | 0.00003 seconds |
107
+ ./spec/jsonl_helpers_spec.rb[1:4:1] | passed | 0.0001 seconds |
108
+ ./spec/types_spec.rb[1:1:1:1] | passed | 0.00003 seconds |
109
+ ./spec/types_spec.rb[1:1:2:1] | passed | 0.00003 seconds |
110
+ ./spec/types_spec.rb[1:1:3:1] | passed | 0.00003 seconds |
111
+ ./spec/types_spec.rb[1:1:4:1] | passed | 0.00002 seconds |
112
+ ./spec/types_spec.rb[1:2:1] | passed | 0.00003 seconds |
113
+ ./spec/types_spec.rb[1:2:2] | passed | 0.00003 seconds |
114
+ ./spec/types_spec.rb[1:2:3:1] | passed | 0.00003 seconds |
data/.rubocop.yml ADDED
@@ -0,0 +1,51 @@
1
+ # frozen_string_literal: true
2
+
3
+ require:
4
+ - rubocop-rspec
5
+ - rubocop-performance
6
+ - rubocop-rake
7
+
8
+ AllCops:
9
+ TargetRubyVersion: 3.0
10
+ NewCops: enable
11
+ Exclude:
12
+ - 'vendor/**/*'
13
+ - 'bin/**/*'
14
+
15
+ # Disable some opinionated cops
16
+ Style/Documentation:
17
+ Enabled: false
18
+
19
+ Style/StringLiterals:
20
+ EnforcedStyle: single_quotes
21
+
22
+ Style/StringLiteralsInInterpolation:
23
+ EnforcedStyle: single_quotes
24
+
25
+ Layout/LineLength:
26
+ Max: 120
27
+ Exclude:
28
+ - 'spec/**/*'
29
+
30
+ Metrics/BlockLength:
31
+ Exclude:
32
+ - 'spec/**/*'
33
+ - 'Rakefile'
34
+ - '*.gemspec'
35
+
36
+ Metrics/MethodLength:
37
+ Max: 20
38
+ Exclude:
39
+ - 'spec/**/*'
40
+
41
+ Metrics/ClassLength:
42
+ Max: 150
43
+
44
+ RSpec/ExampleLength:
45
+ Max: 15
46
+
47
+ RSpec/MultipleExpectations:
48
+ Max: 5
49
+
50
+ RSpec/NestedGroups:
51
+ Max: 4
data/.yardopts ADDED
@@ -0,0 +1,7 @@
1
+ --markup markdown
2
+ --readme README.md
3
+ --files CHANGELOG.md,LICENSE
4
+ --private
5
+ --protected
6
+ --output-dir doc
7
+ lib/**/*.rb
data/CHANGELOG.md ADDED
@@ -0,0 +1,37 @@
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
+ ## [Unreleased]
9
+
10
+ ### Added
11
+ - Real-time streaming support with lazy enumerators
12
+ - Ergonomic MCP (Model Context Protocol) integration
13
+ - Rails + Sidekiq + ActionCable streaming integration examples
14
+ - Advanced error handling with user-friendly installation instructions
15
+ - IRB helpers for quick testing and development
16
+ - Comprehensive documentation and examples
17
+ - Model selection with aliases (sonnet, haiku, opus)
18
+ - Advanced CLI subprocess management with proper cleanup
19
+ - Buffer overflow protection for large JSON messages
20
+
21
+ ### Enhanced
22
+ - Better gem structure following Ruby best practices
23
+ - Improved test infrastructure with coverage reporting
24
+ - Development tooling with Rake, RuboCop, and YARD
25
+ - Professional documentation and README
26
+
27
+ ## [0.0.1] - 2025-01-16
28
+
29
+ ### Added
30
+ - Initial Ruby SDK implementation for Claude Code
31
+ - Core streaming functionality
32
+ - MCP server integration
33
+ - Basic error handling
34
+ - Examples and documentation
35
+
36
+ [Unreleased]: https://github.com/anthropics/claude-code-sdk-python/compare/v0.0.1...HEAD
37
+ [0.0.1]: https://github.com/anthropics/claude-code-sdk-python/releases/tag/ruby-v0.0.1
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 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 all
13
+ 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 THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,288 @@
1
+ # Claude Code SDK for Ruby
2
+
3
+ Unofficial Ruby SDK for Claude Code. See the [Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for more information.
4
+
5
+ ## Installation
6
+
7
+ Add this line to your application's Gemfile:
8
+
9
+ ```ruby
10
+ gem 'claude_code'
11
+ ```
12
+
13
+ And then execute:
14
+
15
+ ```bash
16
+ bundle install
17
+ ```
18
+
19
+ Or install it yourself as:
20
+
21
+ ```bash
22
+ gem install claude_code
23
+ ```
24
+
25
+ **Prerequisites:**
26
+ - Ruby 3.0+
27
+ - Node.js
28
+ - Claude Code: `npm install -g @anthropic-ai/claude-code`
29
+
30
+ ## Quick Start
31
+
32
+ ```ruby
33
+ require 'claude_code'
34
+
35
+ # Simple query
36
+ ClaudeCode.query(prompt: "What is 2 + 2?").each do |message|
37
+ puts message
38
+ end
39
+ ```
40
+
41
+ ## Usage
42
+
43
+ ### Authentication
44
+
45
+ First, set your API key:
46
+
47
+ ```bash
48
+ export ANTHROPIC_API_KEY='your-api-key-here'
49
+ ```
50
+
51
+ Or for Amazon Bedrock:
52
+ ```bash
53
+ export CLAUDE_CODE_USE_BEDROCK=1
54
+ export AWS_ACCESS_KEY_ID='your-access-key'
55
+ export AWS_SECRET_ACCESS_KEY='your-secret-key'
56
+ export AWS_REGION='us-west-2'
57
+ ```
58
+
59
+ Or for Google Vertex AI:
60
+ ```bash
61
+ export CLAUDE_CODE_USE_VERTEX=1
62
+ export GOOGLE_APPLICATION_CREDENTIALS='path/to/service-account.json'
63
+ export GOOGLE_CLOUD_PROJECT='your-project-id'
64
+ ```
65
+
66
+ ### Basic Query
67
+
68
+ ```ruby
69
+ require 'claude_code'
70
+
71
+ # Simple query
72
+ ClaudeCode.query(prompt: "Hello Claude").each do |message|
73
+ if message.is_a?(ClaudeCode::AssistantMessage)
74
+ message.content.each do |block|
75
+ if block.is_a?(ClaudeCode::TextBlock)
76
+ puts block.text
77
+ end
78
+ end
79
+ end
80
+ end
81
+
82
+ # With options
83
+ options = ClaudeCode::ClaudeCodeOptions.new(
84
+ system_prompt: "You are a helpful assistant",
85
+ max_turns: 1
86
+ )
87
+
88
+ ClaudeCode.query(prompt: "Tell me a joke", options: options).each do |message|
89
+ puts message
90
+ end
91
+ ```
92
+
93
+ ### Conversation Resuming
94
+
95
+ ```ruby
96
+ # Continue the most recent conversation
97
+ ClaudeCode.continue_conversation("What did we just discuss?").each do |message|
98
+ # Process messages...
99
+ end
100
+
101
+ # Resume a specific conversation by session ID
102
+ session_id = "550e8400-e29b-41d4-a716-446655440000"
103
+ ClaudeCode.resume_conversation(session_id, "Continue our discussion").each do |message|
104
+ # Process messages...
105
+ end
106
+
107
+ # Continue with options
108
+ options = ClaudeCode::ClaudeCodeOptions.new(max_turns: 2)
109
+ ClaudeCode.continue_conversation("Add more details", options: options)
110
+ ```
111
+
112
+ ### Streaming JSON Input
113
+
114
+ For multi-turn conversations without restarting the CLI, use streaming JSON input:
115
+
116
+ ```ruby
117
+ # Create multiple user messages for a conversation
118
+ messages = [
119
+ ClaudeCode::JSONLHelpers.create_user_message("Hello! I'm working on a Ruby project."),
120
+ ClaudeCode::JSONLHelpers.create_user_message("Can you help me understand modules?"),
121
+ ClaudeCode::JSONLHelpers.create_user_message("Show me a practical example.")
122
+ ]
123
+
124
+ # Process all messages in a single streaming session
125
+ ClaudeCode.stream_json_query(messages) do |message|
126
+ case message
127
+ when ClaudeCode::AssistantMessage
128
+ message.content.each do |block|
129
+ puts block.text if block.is_a?(ClaudeCode::TextBlock)
130
+ end
131
+ when ClaudeCode::ResultMessage
132
+ puts "Cost: $#{message.total_cost_usd}"
133
+ end
134
+ end
135
+
136
+ # Manual JSONL format (equivalent to CLI)
137
+ custom_messages = [
138
+ {
139
+ 'type' => 'user',
140
+ 'message' => {
141
+ 'role' => 'user',
142
+ 'content' => [{'type' => 'text', 'text' => 'Explain this code'}]
143
+ }
144
+ }
145
+ ]
146
+
147
+ ClaudeCode.stream_json_query(custom_messages)
148
+ ```
149
+
150
+ ### Using Tools
151
+
152
+ ```ruby
153
+ options = ClaudeCode::ClaudeCodeOptions.new(
154
+ allowed_tools: ["Read", "Write", "Bash"],
155
+ permission_mode: 'acceptEdits' # auto-accept file edits
156
+ )
157
+
158
+ ClaudeCode.query(
159
+ prompt: "Create a hello.rb file",
160
+ options: options
161
+ ).each do |message|
162
+ # Process tool use and results
163
+ end
164
+ ```
165
+
166
+ ### Working Directory
167
+
168
+ ```ruby
169
+ options = ClaudeCode::ClaudeCodeOptions.new(
170
+ cwd: "/path/to/project"
171
+ )
172
+ ```
173
+
174
+ ## API Reference
175
+
176
+ ### Core Methods
177
+
178
+ #### `ClaudeCode.query(prompt:, options: nil, cli_path: nil, mcp_servers: {})`
179
+
180
+ Main function for querying Claude.
181
+
182
+ **Parameters:**
183
+ - `prompt` (String): The prompt to send to Claude
184
+ - `options` (ClaudeCodeOptions): Optional configuration
185
+ - `cli_path` (String): Optional path to Claude CLI binary
186
+ - `mcp_servers` (Hash): Optional MCP server configurations
187
+
188
+ **Returns:** Enumerator of response messages
189
+
190
+ #### `ClaudeCode.continue_conversation(prompt = nil, options: nil, cli_path: nil, mcp_servers: {})`
191
+
192
+ Continue the most recent conversation.
193
+
194
+ **Parameters:**
195
+ - `prompt` (String): Optional new prompt to add
196
+ - `options` (ClaudeCodeOptions): Optional configuration
197
+ - `cli_path` (String): Optional path to Claude CLI binary
198
+ - `mcp_servers` (Hash): Optional MCP server configurations
199
+
200
+ **Returns:** Enumerator of response messages
201
+
202
+ #### `ClaudeCode.resume_conversation(session_id, prompt = nil, options: nil, cli_path: nil, mcp_servers: {})`
203
+
204
+ Resume a specific conversation by session ID.
205
+
206
+ **Parameters:**
207
+ - `session_id` (String): The session ID to resume
208
+ - `prompt` (String): Optional new prompt to add
209
+ - `options` (ClaudeCodeOptions): Optional configuration
210
+ - `cli_path` (String): Optional path to Claude CLI binary
211
+ - `mcp_servers` (Hash): Optional MCP server configurations
212
+
213
+ **Returns:** Enumerator of response messages
214
+
215
+ #### `ClaudeCode.stream_query(prompt:, options: nil, cli_path: nil, mcp_servers: {}, &block)`
216
+
217
+ Stream query responses with auto-formatting or custom block handling.
218
+
219
+ #### `ClaudeCode.stream_json_query(messages, options: nil, cli_path: nil, mcp_servers: {})`
220
+
221
+ Send multiple messages via streaming JSON input (JSONL format). This allows multiple turns of conversation without re-launching the Claude binary.
222
+
223
+ **Parameters:**
224
+ - `messages` (Array): Array of JSONL message objects
225
+ - `options` (ClaudeCodeOptions): Optional configuration (automatically sets input_format: 'stream-json')
226
+ - `cli_path` (String): Optional path to Claude CLI binary
227
+ - `mcp_servers` (Hash): Optional MCP server configurations
228
+
229
+ **Returns:** Enumerator of response messages
230
+
231
+ #### `ClaudeCode.quick_mcp_query(prompt, server_name:, server_url:, tools:, **options)`
232
+
233
+ Ultra-convenient method for quick MCP server usage.
234
+
235
+ #### `ClaudeCode.add_mcp_server(name, config)`
236
+
237
+ Helper to create MCP server configurations.
238
+
239
+ ### JSONL Helpers
240
+
241
+ #### `ClaudeCode::JSONLHelpers.create_user_message(text)`
242
+
243
+ Create a user message in the format expected by Claude CLI.
244
+
245
+ #### `ClaudeCode::JSONLHelpers.create_conversation(*turns)`
246
+
247
+ Create multiple user messages from text strings.
248
+
249
+ #### `ClaudeCode::JSONLHelpers.format_messages_as_jsonl(messages)`
250
+
251
+ Format multiple messages as JSONL string.
252
+
253
+ ### Types
254
+
255
+ See [lib/claude_code_sdk/types.rb](lib/claude_code_sdk/types.rb) for complete type definitions:
256
+ - `ClaudeCodeOptions` - Configuration options
257
+ - `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
258
+ - `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
259
+
260
+ ## Error Handling
261
+
262
+ ```ruby
263
+ begin
264
+ ClaudeCode.query(prompt: "Hello").each do |message|
265
+ # Process message
266
+ end
267
+ rescue ClaudeCode::CLINotFoundError
268
+ puts "Please install Claude Code"
269
+ rescue ClaudeCode::ProcessError => e
270
+ puts "Process failed with exit code: #{e.exit_code}"
271
+ rescue ClaudeCode::CLIJSONDecodeError => e
272
+ puts "Failed to parse response: #{e}"
273
+ end
274
+ ```
275
+
276
+ See [lib/claude_code_sdk/errors.rb](lib/claude_code_sdk/errors.rb) for all error types.
277
+
278
+ ## Available Tools
279
+
280
+ See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude) for a complete list of available tools.
281
+
282
+ ## Examples
283
+
284
+ See [examples/quick_start.rb](examples/quick_start.rb) for a complete working example.
285
+
286
+ ## License
287
+
288
+ MIT
data/Rakefile ADDED
@@ -0,0 +1,32 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bundler/gem_tasks'
4
+ require 'rspec/core/rake_task'
5
+ require 'rubocop/rake_task'
6
+
7
+ RSpec::Core::RakeTask.new(:spec)
8
+ RuboCop::RakeTask.new
9
+
10
+ task default: [:spec, :rubocop]
11
+
12
+ desc 'Run all tests and linting'
13
+ task test: [:spec, :rubocop]
14
+
15
+ desc 'Run tests with coverage report'
16
+ task :coverage do
17
+ ENV['COVERAGE'] = 'true'
18
+ Rake::Task[:spec].invoke
19
+ end
20
+
21
+ desc 'Generate YARD documentation'
22
+ task :docs do
23
+ sh 'yard doc'
24
+ end
25
+
26
+ desc 'Setup development environment'
27
+ task :setup do
28
+ sh 'bundle install'
29
+ puts 'Development environment setup complete!'
30
+ puts 'Run `rake test` to run tests'
31
+ puts 'Run `rake docs` to generate documentation'
32
+ end