{"id":30257629,"url":"https://github.com/schappim/claude-code-sdk-ruby","last_synced_at":"2025-08-15T16:05:22.685Z","repository":{"id":304937075,"uuid":"1020596886","full_name":"schappim/claude-code-sdk-ruby","owner":"schappim","description":"Claude Code SDK for Ruby","archived":false,"fork":false,"pushed_at":"2025-07-16T09:20:51.000Z","size":154,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T20:18:27.545Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schappim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T05:48:17.000Z","updated_at":"2025-07-31T20:02:58.000Z","dependencies_parsed_at":"2025-07-17T13:30:29.366Z","dependency_job_id":"3244fb30-a4bc-4597-b480-4568b53ffdfd","html_url":"https://github.com/schappim/claude-code-sdk-ruby","commit_stats":null,"previous_names":["schappim/claude-code-sdk-ruby"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/schappim/claude-code-sdk-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schappim%2Fclaude-code-sdk-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schappim%2Fclaude-code-sdk-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schappim%2Fclaude-code-sdk-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schappim%2Fclaude-code-sdk-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schappim","download_url":"https://codeload.github.com/schappim/claude-code-sdk-ruby/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schappim%2Fclaude-code-sdk-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270594163,"owners_count":24612661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-15T16:02:47.903Z","updated_at":"2025-08-15T16:05:22.669Z","avatar_url":"https://github.com/schappim.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Claude Code SDK for Ruby\n\nUnofficial Ruby SDK for Claude Code. See the [Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for more information.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'claude_code'\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\nOr install it yourself as:\n\n```bash\ngem install claude_code\n```\n\n**Prerequisites:**\n- Ruby 3.0+\n- Node.js\n- Claude Code: `npm install -g @anthropic-ai/claude-code`\n\n## Quick Start\n\n```ruby\nrequire 'claude_code'\n\n# Simple query\nClaudeCode.query(prompt: \"What is 2 + 2?\").each do |message|\n  puts message\nend\n```\n\n## Usage\n\n### Authentication\n\nFirst, set your API key:\n\n```bash\nexport ANTHROPIC_API_KEY='your-api-key-here'\n```\n\nOr for Amazon Bedrock:\n```bash\nexport CLAUDE_CODE_USE_BEDROCK=1\nexport AWS_ACCESS_KEY_ID='your-access-key'\nexport AWS_SECRET_ACCESS_KEY='your-secret-key'  \nexport AWS_REGION='us-west-2'\n```\n\nOr for Google Vertex AI:\n```bash\nexport CLAUDE_CODE_USE_VERTEX=1\nexport GOOGLE_APPLICATION_CREDENTIALS='path/to/service-account.json'\nexport GOOGLE_CLOUD_PROJECT='your-project-id'\n```\n\n### Basic Query\n\n```ruby\nrequire 'claude_code'\n\n# Simple query\nClaudeCode.query(prompt: \"Hello Claude\").each do |message|\n  if message.is_a?(ClaudeCode::AssistantMessage)\n    message.content.each do |block|\n      if block.is_a?(ClaudeCode::TextBlock)\n        puts block.text\n      end\n    end\n  end\nend\n\n# With options\noptions = ClaudeCode::ClaudeCodeOptions.new(\n  system_prompt: \"You are a helpful assistant\",\n  max_turns: 1\n)\n\nClaudeCode.query(prompt: \"Tell me a joke\", options: options).each do |message|\n  puts message\nend\n```\n\n### Conversation Resuming\n\n```ruby\n# Continue the most recent conversation\nClaudeCode.continue_conversation(\"What did we just discuss?\").each do |message|\n  # Process messages...\nend\n\n# Resume a specific conversation by session ID\nsession_id = \"550e8400-e29b-41d4-a716-446655440000\"\nClaudeCode.resume_conversation(session_id, \"Continue our discussion\").each do |message|\n  # Process messages...\nend\n\n# Continue with options\noptions = ClaudeCode::ClaudeCodeOptions.new(max_turns: 2)\nClaudeCode.continue_conversation(\"Add more details\", options: options)\n```\n\n### Streaming JSON Input\n\nFor multi-turn conversations without restarting the CLI, use streaming JSON input:\n\n```ruby\n# Create multiple user messages for a conversation\nmessages = [\n  ClaudeCode::JSONLHelpers.create_user_message(\"Hello! I'm working on a Ruby project.\"),\n  ClaudeCode::JSONLHelpers.create_user_message(\"Can you help me understand modules?\"),\n  ClaudeCode::JSONLHelpers.create_user_message(\"Show me a practical example.\")\n]\n\n# Process all messages in a single streaming session\nClaudeCode.stream_json_query(messages) do |message|\n  case message\n  when ClaudeCode::AssistantMessage\n    message.content.each do |block|\n      puts block.text if block.is_a?(ClaudeCode::TextBlock)\n    end\n  when ClaudeCode::ResultMessage\n    puts \"Cost: $#{message.total_cost_usd}\"\n  end\nend\n\n# Manual JSONL format (equivalent to CLI)\ncustom_messages = [\n  {\n    'type' =\u003e 'user',\n    'message' =\u003e {\n      'role' =\u003e 'user',\n      'content' =\u003e [{'type' =\u003e 'text', 'text' =\u003e 'Explain this code'}]\n    }\n  }\n]\n\nClaudeCode.stream_json_query(custom_messages)\n```\n\n### Using Tools\n\n```ruby\noptions = ClaudeCode::ClaudeCodeOptions.new(\n  allowed_tools: [\"Read\", \"Write\", \"Bash\"],\n  permission_mode: 'acceptEdits'  # auto-accept file edits\n)\n\nClaudeCode.query(\n  prompt: \"Create a hello.rb file\",\n  options: options\n).each do |message|\n  # Process tool use and results\nend\n```\n\n### Working Directory\n\n```ruby\noptions = ClaudeCode::ClaudeCodeOptions.new(\n  cwd: \"/path/to/project\"\n)\n```\n\n## API Reference\n\n### Core Methods\n\n#### `ClaudeCode.query(prompt:, options: nil, cli_path: nil, mcp_servers: {})`\n\nMain function for querying Claude.\n\n**Parameters:**\n- `prompt` (String): The prompt to send to Claude\n- `options` (ClaudeCodeOptions): Optional configuration\n- `cli_path` (String): Optional path to Claude CLI binary\n- `mcp_servers` (Hash): Optional MCP server configurations\n\n**Returns:** Enumerator of response messages\n\n#### `ClaudeCode.continue_conversation(prompt = nil, options: nil, cli_path: nil, mcp_servers: {})`\n\nContinue the most recent conversation.\n\n**Parameters:**\n- `prompt` (String): Optional new prompt to add\n- `options` (ClaudeCodeOptions): Optional configuration\n- `cli_path` (String): Optional path to Claude CLI binary\n- `mcp_servers` (Hash): Optional MCP server configurations\n\n**Returns:** Enumerator of response messages\n\n#### `ClaudeCode.resume_conversation(session_id, prompt = nil, options: nil, cli_path: nil, mcp_servers: {})`\n\nResume a specific conversation by session ID.\n\n**Parameters:**\n- `session_id` (String): The session ID to resume\n- `prompt` (String): Optional new prompt to add\n- `options` (ClaudeCodeOptions): Optional configuration\n- `cli_path` (String): Optional path to Claude CLI binary\n- `mcp_servers` (Hash): Optional MCP server configurations\n\n**Returns:** Enumerator of response messages\n\n#### `ClaudeCode.stream_query(prompt:, options: nil, cli_path: nil, mcp_servers: {}, \u0026block)`\n\nStream query responses with auto-formatting or custom block handling.\n\n#### `ClaudeCode.stream_json_query(messages, options: nil, cli_path: nil, mcp_servers: {})`\n\nSend multiple messages via streaming JSON input (JSONL format). This allows multiple turns of conversation without re-launching the Claude binary.\n\n**Parameters:**\n- `messages` (Array): Array of JSONL message objects\n- `options` (ClaudeCodeOptions): Optional configuration (automatically sets input_format: 'stream-json')\n- `cli_path` (String): Optional path to Claude CLI binary\n- `mcp_servers` (Hash): Optional MCP server configurations\n\n**Returns:** Enumerator of response messages\n\n#### `ClaudeCode.quick_mcp_query(prompt, server_name:, server_url:, tools:, **options)`\n\nUltra-convenient method for quick MCP server usage.\n\n#### `ClaudeCode.add_mcp_server(name, config)`\n\nHelper to create MCP server configurations.\n\n### JSONL Helpers\n\n#### `ClaudeCode::JSONLHelpers.create_user_message(text)`\n\nCreate a user message in the format expected by Claude CLI.\n\n#### `ClaudeCode::JSONLHelpers.create_conversation(*turns)`\n\nCreate multiple user messages from text strings.\n\n#### `ClaudeCode::JSONLHelpers.format_messages_as_jsonl(messages)`\n\nFormat multiple messages as JSONL string.\n\n### Types\n\nSee [lib/claude_code_sdk/types.rb](lib/claude_code_sdk/types.rb) for complete type definitions:\n- `ClaudeCodeOptions` - Configuration options\n- `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types\n- `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks\n\n## Error Handling\n\n```ruby\nbegin\n  ClaudeCode.query(prompt: \"Hello\").each do |message|\n    # Process message\n  end\nrescue ClaudeCode::CLINotFoundError\n  puts \"Please install Claude Code\"\nrescue ClaudeCode::ProcessError =\u003e e\n  puts \"Process failed with exit code: #{e.exit_code}\"\nrescue ClaudeCode::CLIJSONDecodeError =\u003e e\n  puts \"Failed to parse response: #{e}\"\nend\n```\n\nSee [lib/claude_code_sdk/errors.rb](lib/claude_code_sdk/errors.rb) for all error types.\n\n## Available Tools\n\nSee the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude) for a complete list of available tools.\n\n## Examples\n\nSee [examples/quick_start.rb](examples/quick_start.rb) for a complete working example.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschappim%2Fclaude-code-sdk-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschappim%2Fclaude-code-sdk-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschappim%2Fclaude-code-sdk-ruby/lists"}