ruby_llm-claude_cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c32a73de5301283e7fb20c62193d24353eced9373f95d35cf2877657937e057
+  data.tar.gz: 15c16a35ea36ccbc652a31530c4cbfb2ba4bb17f3736c46aa579b4965b7ca0ed
+SHA512:
+  metadata.gz: 6a04712e0065cf570d1819dfac38c81051578b47ec34c8cef9d96188e85645c8798bf781e687943becd0f3f4da04fa623eab4ed30a2468e49a1515cf745fbdb2
+  data.tar.gz: 6e9cf1df56aff8e60c0fcf1bab27fce6832104747b497d131fa380c7912c32df10ea46dbe4f10cb0857eb902ce1f0cc2583bf531c00e1886bbe15542ffb47c86

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `claude_cli` provider for RubyLLM 2.x with streaming, images, PDFs, text and
+  Office attachments, staged files with a hex preview, an attachment converter hook, structured
+  output, effort, and emulated ruby_llm tool calls.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andreas Idogawa
+
+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,86 @@
+# ruby_llm-claude_cli
+
+A [RubyLLM](https://rubyllm.com) 2.x provider that runs chats through the local
+`claude -p` (Claude Code) instead of the HTTP API. Requests use whatever login
+Claude Code has, including a Pro/Max subscription. No API key is needed.
+
+```ruby
+require 'ruby_llm/claude_cli'
+
+chat = RubyLLM.chat(model: 'sonnet', provider: :claude_cli)   # or opus, haiku, claude-opus-5-5
+chat.ask('Summarise this', with: 'report.pdf')
+chat.ask('Stream please') { |chunk| print chunk.content }
+```
+
+## How it works
+
+It subclasses ruby_llm's Anthropic protocol and swaps the HTTP call for a
+`claude -p --input-format stream-json --output-format stream-json` process.
+The CLI streams raw Messages API events, so ruby_llm's own Anthropic parser
+reads the stream. Each call starts a fresh, isolated CLI session with a
+throwaway working directory, no settings files, MCP servers, skills or saved
+session, and your system prompt in place of Claude Code's.
+
+## What is supported, and the workarounds
+
+| Feature | How |
+|---|---|
+| Text, system prompts, multi-turn | History is sent as one tagged transcript (stream-json input only accepts user turns) |
+| Streaming | Native, from the CLI's partial-message events |
+| Images (png/jpeg/gif/webp ≤ 5 MB) | Inline base64 image blocks. URLs are downloaded first. Images in earlier turns are kept. |
+| PDFs (≤ 20 MB) | Inline document blocks |
+| Text, code, CSV, JSON | Inline text |
+| docx / xlsx / pptx | Text is extracted from the Office XML (needs `rubyzip`) |
+| Larger images and PDFs | Saved to the working directory. The model opens them with the Read tool, which downsizes images and pages through PDFs. |
+| Other binaries | Saved to the working directory, plus a hex and strings preview |
+| Audio, video, anything else | `config.claude_cli_attachment_converter` hook, see below |
+| Tools (`with_tools`) | Emulated: tools are described in the system prompt and the reply is forced through `--json-schema` into `{text, tool_calls}`. ruby_llm runs the tools as usual. Honours `choice:` and `calls: :one`. |
+| Structured output (`with_schema`) | `--json-schema` |
+| `with_thinking(effort:)` | `--effort` (low/medium/high/xhigh/max) |
+| temperature, max_output_tokens, token counting, citations, caching controls | Not available through the CLI. Ignored, or an error is raised. |
+
+Transcribe audio with another provider before it reaches Claude:
+
+```ruby
+RubyLLM.configure do |c|
+  c.claude_cli_attachment_converter = lambda do |attachment|
+    RubyLLM.transcribe(attachment.source.to_s, model: 'gpt-4o-transcribe').text if attachment.audio?
+  end
+end
+```
+
+## Configuration
+
+```ruby
+RubyLLM.configure do |c|
+  c.claude_cli_command = 'claude'             # path to the CLI
+  c.claude_cli_timeout = 300                  # seconds; kills the process after that
+  c.claude_cli_native_tools = %w[WebSearch]   # let Claude Code's own tools run (default: none)
+  c.claude_cli_extra_args = ['--max-budget-usd', '1']
+  c.claude_cli_workdir = nil                  # fixed dir instead of a fresh temp dir per call
+  c.claude_cli_default_system_prompt = 'You are a helpful assistant.'
+end
+```
+
+## Trade-offs
+
+- Each call starts a process, so there is about 2–4 s of extra latency per turn.
+  A tool round trip is two calls.
+- The full history is re-sent every turn. There is no `--resume`, so ruby_llm
+  stays the source of truth for the conversation.
+- Token counts come from the CLI's result. Costs follow your Claude Code plan.
+
+## Try it
+
+```bash
+bundle install
+bundle exec ruby bin/console        # irb with a `chat` helper and a demo Weather tool
+bundle exec ruby examples/demo.rb   # scripted demo; MODEL=haiku for speed
+```
+
+## Tests
+
+```bash
+ruby test/content_test.rb        # offline
+ruby examples/smoke.rb haiku     # real claude -p calls, ~2 min
+```

data/lib/ruby_llm/claude_cli/content.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RubyLLM
+  module ClaudeCLI
+    # Turns a ruby_llm conversation into the content blocks of the single user
+    # message `claude -p` receives.
+    #
+    # Attachment handling:
+    # * png/jpeg/gif/webp up to 5 MB  -> inline image block (URLs are fetched)
+    # * PDF up to 20 MB               -> inline document block
+    # * text, code, csv, json         -> inline text
+    # * docx/xlsx/pptx                -> text extracted from the Office XML
+    #                                    (needs the rubyzip gem), else staged
+    # * anything, via hook            -> config.claude_cli_attachment_converter
+    # * everything else, oversized    -> copied into the work dir and the model
+    #   images and PDFs                  is told the path; the Read tool is
+    #                                    enabled so it can open it (Read also
+    #                                    downsizes big images and pages PDFs);
+    #                                    binaries also get a hex preview
+    class Content
+      INLINE_IMAGE_TYPES = %w[image/png image/jpeg image/gif image/webp].freeze
+      MAX_INLINE_IMAGE = 5 * 1024 * 1024
+      MAX_INLINE_PDF = 20 * 1024 * 1024
+      OFFICE_TEXT_PARTS = {
+        'docx' => %r{\Aword/(document|header\d*|footer\d*|footnotes)\.xml\z},
+        'pptx' => %r{\Appt/slides/slide\d+\.xml\z},
+        'xlsx' => %r{\Axl/(sharedStrings|worksheets/sheet\d+)\.xml\z}
+      }.freeze
+
+      attr_reader :staged_files
+
+      def initialize(workdir, config = nil)
+        @workdir = workdir
+        @config = config
+        @staged_files = []
+      end
+
+      def system_prompt(system_messages)
+        system_messages.map { |msg| text_of(msg) }.reject(&:empty?).join("\n\n")
+      end
+
+      # One user turn goes in as-is; longer histories become a tagged
+      # transcript, because stream-json input only takes user messages.
+      def blocks(messages)
+        if messages.one? && messages.first.role == :user
+          return message_blocks(messages.first).then { |b| b.empty? ? [text('(empty message)')] : b }
+        end
+
+        out = [text("The conversation so far follows. Continue it by writing the assistant's next reply " \
+                    "to the last turn. Do not repeat the tags.\n")]
+        messages.each { |msg| out.concat(transcript_turn(msg)) }
+        merge_texts(out)
+      end
+
+      private
+
+      def transcript_turn(msg)
+        case msg.role
+        when :tool
+          [text("<tool_result id=\"#{msg.tool_call_id}\">\n"), *message_blocks(msg), text("\n</tool_result>\n")]
+        when :assistant
+          calls = (msg.tool_calls || {}).values.map do |call|
+            text(%(\n<tool_call id="#{call.id}" name="#{call.name}">#{JSON.generate(call.arguments)}</tool_call>))
+          end
+          [text("<assistant>\n"), *message_blocks(msg), *calls, text("\n</assistant>\n")]
+        else
+          [text("<user>\n"), *message_blocks(msg), text("\n</user>\n")]
+        end
+      end
+
+      def message_blocks(msg)
+        parts = []
+        body = content_string(msg.content)
+        parts << text(body) unless body.empty?
+        msg.attachments.each { |attachment| parts.concat(attachment_blocks(attachment)) }
+        parts
+      end
+
+      def text_of(msg)
+        [content_string(msg.content), *msg.attachments.map { |a| a.text? ? a.for_llm : '' }].join("\n").strip
+      end
+
+      def content_string(content) = content.to_s
+
+      def attachment_blocks(attachment)
+        if (converted = convert(attachment))
+          [text("<file name='#{attachment.filename}' mime_type='#{attachment.mime_type}' " \
+                "note='converted to text'>#{converted}</file>")]
+        elsif attachment.image? && INLINE_IMAGE_TYPES.include?(attachment.mime_type) &&
+           attachment.content.bytesize <= MAX_INLINE_IMAGE
+          [{ type: 'image', source: { type: 'base64', media_type: attachment.mime_type, data: attachment.encoded } }]
+        elsif attachment.pdf? && attachment.content.bytesize <= MAX_INLINE_PDF
+          [{ type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: attachment.encoded },
+             title: attachment.filename }.compact]
+        elsif attachment.text?
+          [text(attachment.for_llm)]
+        elsif (office = office_text(attachment))
+          [text("<file name='#{attachment.filename}' mime_type='#{attachment.mime_type}' " \
+                "note='text extracted from the Office file'>#{office}</file>")]
+        else
+          [text(stage(attachment))]
+        end
+      end
+
+      # config.claude_cli_attachment_converter = ->(attachment) { ... }
+      # returns text for an attachment (e.g. a transcript of audio made with
+      # RubyLLM.transcribe on another provider), or nil to fall through.
+      def convert(attachment)
+        converter = @config&.claude_cli_attachment_converter
+        result = converter&.call(attachment)
+        result.nil? || result.to_s.empty? ? nil : result.to_s
+      end
+
+      def office_text(attachment)
+        pattern = OFFICE_TEXT_PARTS[attachment.extension]
+        return unless pattern && zip_available?
+
+        require 'stringio'
+        texts = []
+        Zip::File.open_buffer(StringIO.new(attachment.content)) do |zip|
+          zip.entries.select { |e| e.name.match?(pattern) }.sort_by { |e| e.name.scan(/\d+/).map(&:to_i) }.each do |e|
+            texts << xml_to_text(e.get_input_stream.read)
+          end
+        end
+        joined = texts.join("\n\n").strip
+        joined.empty? ? nil : joined
+      rescue StandardError => e
+        RubyLLM.logger.debug { "claude-cli: office text extraction failed: #{e.message}" }
+        nil
+      end
+
+      def xml_to_text(xml)
+        xml.force_encoding('UTF-8')
+           .gsub(%r{</w:p>|</a:p>|</row>|<w:br/>}, "\n").gsub(%r{</c>|<w:tab/>}, "\t")
+           .gsub(/<[^>]+>/, '')
+           .gsub('&lt;', '<').gsub('&gt;', '>').gsub('&quot;', '"').gsub('&apos;', "'").gsub('&amp;', '&')
+           .gsub(/\n{3,}/, "\n\n")
+      end
+
+      def zip_available?
+        return @zip_available unless @zip_available.nil?
+
+        @zip_available = begin
+          require 'zip'
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def stage(attachment)
+        dir = File.join(@workdir, 'attachments')
+        FileUtils.mkdir_p(dir)
+        name = File.basename(attachment.filename || "file#{@staged_files.size + 1}")
+        name = "#{@staged_files.size + 1}-#{name}" if File.exist?(File.join(dir, name))
+        path = File.join(dir, name)
+        File.binwrite(path, attachment.content)
+        @staged_files << path
+        size = File.size(path)
+        note = "[Attached file '#{name}' (#{attachment.mime_type}, #{size} bytes) is saved at #{path}. "
+        note += if attachment.image? || attachment.pdf?
+                  'It is too large to inline; open it with the Read tool.]'
+                else
+                  'The Read tool can open it if it is text. Its first bytes as hex, with printable ' \
+                    "strings, are:\n#{hex_preview(attachment.content)}\n" \
+                    'If the format cannot be understood from this, say so.]'
+                end
+        note
+      end
+
+      def hex_preview(bytes, limit = 512)
+        head = bytes.byteslice(0, limit).b
+        lines = head.bytes.each_slice(16).map do |row|
+          hex = row.map { |b| format('%02x', b) }.join(' ')
+          "#{hex.ljust(47)}  #{row.map { |b| b.between?(32, 126) ? b.chr : '.' }.join}"
+        end
+        strings = bytes.b.scan(/[\x20-\x7e]{6,}/n).first(40).join(' | ')
+        "#{lines.join("\n")}\nstrings: #{strings}"
+      end
+
+      def text(value) = { type: 'text', text: value }
+
+      def merge_texts(blocks)
+        blocks.each_with_object([]) do |block, out|
+          if block[:type] == 'text' && out.last && out.last[:type] == 'text'
+            out[-1] = text(out.last[:text] + block[:text])
+          else
+            out << block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/claude_cli/protocol.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'tmpdir'
+
+module RubyLLM
+  module ClaudeCLI
+    # Reuses the Anthropic protocol's response and stream parsing, and swaps
+    # the HTTP request for a `claude -p` process. The CLI's stream-json output
+    # carries raw Messages API events, so build_chunk reads them as-is.
+    class Protocol < Protocols::Anthropic
+      EFFORTS = %w[low medium high xhigh max].freeze
+      DEFAULT_SYSTEM_PROMPT = 'You are a helpful assistant.'
+
+      # The payload stays a plain description of the request; the CLI
+      # arguments are built when it runs, next to its work directory.
+      def render_payload(messages, tools:, temperature:, model:, stream: false, max_output_tokens: nil,
+                         schema: nil, thinking: nil, citations: false, caching: nil, tool_prefs: nil) # rubocop:disable Lint/UnusedMethodArgument
+        if temperature || max_output_tokens
+          RubyLLM.logger.debug { 'claude-cli: temperature and max_output_tokens are not supported, ignoring' }
+        end
+        { model: model.id, messages: messages, tools: tools, tool_prefs: tool_prefs || {},
+          schema: schema, thinking: thinking, stream: stream }
+      end
+
+      def count_tokens(*, **)
+        raise RubyLLM::Error, 'claude_cli does not support token counting'
+      end
+
+      def preprocess_message(message)
+        message
+      end
+
+      private
+
+      def auto_upload_large_files? = false
+      def supports_provider_file_references? = false
+
+      def sync_response(payload, _headers = {})
+        run_cli(payload)
+      end
+
+      def stream_response(payload, _headers = {}, &)
+        run_cli(payload, &)
+      end
+
+      def run_cli(payload, &block)
+        workdir = make_workdir
+        request, emulate = build_request(payload, workdir, stream: !block.nil?)
+        model_id = nil
+        @cli_blocks = {}
+
+        result = Runner.new(@config).run(request) do |event|
+          model_id ||= event.dig('message', 'model') if event['type'] == 'assistant'
+          forward_stream_event(event, &block) if request.stream
+        end
+
+        message = parse_completion_body(response_body(result, payload, emulate, model_id), raw: result)
+        block&.call(Chunk.new(role: :assistant, content: message.content, model: message.model)) unless request.stream
+        message
+      ensure
+        FileUtils.rm_rf(workdir) if workdir && !@config.claude_cli_workdir
+      end
+
+      def build_request(payload, workdir, stream:)
+        content = Content.new(workdir, @config)
+        system_messages, chat_messages = payload[:messages].partition { |m| m.role == :system }
+        blocks = content.blocks(chat_messages)
+
+        system_prompt = content.system_prompt(system_messages)
+        system_prompt = @config.claude_cli_default_system_prompt || DEFAULT_SYSTEM_PROMPT if system_prompt.empty?
+
+        tools = ToolEmulation.active_tools(payload[:tools] || {}, payload[:tool_prefs])
+        emulate = tools.any?
+        json_schema = if emulate
+                        system_prompt = "#{system_prompt}\n\n#{ToolEmulation.instructions(tools, payload[:tool_prefs])}"
+                        ToolEmulation.schema(tools, payload[:tool_prefs], payload[:schema])
+                      elsif payload[:schema]
+                        ToolEmulation.user_schema_body(payload[:schema])
+                      end
+
+        native = Array(@config.claude_cli_native_tools).map(&:to_s)
+        native |= ['Read'] if content.staged_files.any?
+
+        request = Runner::Request.new(
+          model: payload[:model], system_prompt:, content: blocks, json_schema:,
+          effort: effort(payload[:thinking]),
+          # Structured replies stream as StructuredOutput tool input, not text.
+          stream: stream && json_schema.nil?,
+          tools: native, add_dirs: [], workdir:
+        )
+        [request, emulate]
+      end
+
+      def effort(thinking)
+        value = thinking.respond_to?(:effort) ? thinking.effort.to_s : ''
+        EFFORTS.include?(value) ? value : nil
+      end
+
+      def make_workdir
+        base = @config.claude_cli_workdir
+        return Dir.mktmpdir('ruby_llm_claude_cli') unless base
+
+        FileUtils.mkdir_p(base)
+        base
+      end
+
+      # Only text from the top-level agent reaches the caller: tool_use
+      # blocks of native CLI tools would otherwise look like ruby_llm tool
+      # calls.
+      def forward_stream_event(event)
+        return unless event['type'] == 'stream_event' && event['parent_tool_use_id'].nil?
+
+        data = event['event']
+        case data['type']
+        when 'message_start'
+          @cli_blocks = {}
+        when 'content_block_start'
+          @cli_blocks[data['index']] = data.dig('content_block', 'type')
+          return unless @cli_blocks[data['index']] == 'text'
+        when 'content_block_delta', 'content_block_stop'
+          return unless @cli_blocks[data['index']] == 'text'
+        when 'message_delta', 'message_stop'
+          nil
+        else
+          return
+        end
+        yield build_chunk(data)
+      end
+
+      def response_body(result, payload, emulate, model_id)
+        blocks = if emulate
+                   ToolEmulation.blocks(result['structured_output'], payload[:schema])
+                 elsif payload[:schema]
+                   [{ 'type' => 'text', 'text' => JSON.generate(result['structured_output']) }]
+                 else
+                   [{ 'type' => 'text', 'text' => result['result'].to_s }]
+                 end
+        stop = if blocks.any? { |b| b['type'] == 'tool_use' } then 'tool_use'
+               elsif result['stop_reason'] == 'tool_use' then 'end_turn'
+               else result['stop_reason']
+               end
+        { 'content' => blocks, 'usage' => result['usage'] || {}, 'stop_reason' => stop,
+          'model' => model_id || payload[:model] }
+      end
+    end
+  end
+end

data/lib/ruby_llm/claude_cli/provider.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ClaudeCLI
+    # Runs chats through the local `claude -p` command instead of the HTTP API,
+    # so requests use whatever login Claude Code has (subscription or key).
+    #
+    #   require 'ruby_llm/claude_cli'
+    #   RubyLLM.chat(model: 'sonnet', provider: :claude_cli).ask('Hi')
+    class Provider < RubyLLM::Provider
+      protocol :claude_cli, ClaudeCLI::Protocol
+
+      # Never contacted; the transport layer just needs a base URL.
+      def api_base
+        'http://claude-cli.invalid'
+      end
+
+      def self.display_name = 'ClaudeCLI'
+
+      # Model ids are passed straight to --model: aliases (sonnet, opus,
+      # haiku) or full ids such as claude-opus-5-5.
+      def self.assume_models_exist? = true
+
+      def self.local? = true
+
+      def self.configuration_options
+        %i[
+          claude_cli_command
+          claude_cli_workdir
+          claude_cli_native_tools
+          claude_cli_extra_args
+          claude_cli_timeout
+          claude_cli_default_system_prompt
+          claude_cli_attachment_converter
+        ]
+      end
+    end
+  end
+end

data/lib/ruby_llm/claude_cli/runner.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+
+module RubyLLM
+  module ClaudeCLI
+    # Starts one `claude -p` process, feeds it a stream-json user message and
+    # yields every JSON event it prints. Returns the final "result" event.
+    class Runner
+      Request = Struct.new(:model, :system_prompt, :content, :json_schema, :effort,
+                           :stream, :tools, :add_dirs, :workdir, keyword_init: true)
+
+      def initialize(config)
+        @config = config
+      end
+
+      def run(request)
+        args = build_args(request)
+        RubyLLM.logger.debug { "claude-cli: #{args.reject { |a| a.length > 200 }.join(' ')}" }
+        input = JSON.generate({ type: 'user', message: { role: 'user', content: request.content } })
+
+        Open3.popen3(*args, chdir: request.workdir) do |stdin, stdout, stderr, wait|
+          err_reader = Thread.new { stderr.read }
+          stdin.binmode.write(input, "\n")
+          stdin.close
+
+          result = with_timeout(wait) { read_events(stdout) { |event| yield event if block_given? } }
+          status = wait.value
+          check!(result, status, err_reader.value)
+        end
+      end
+
+      def build_args(request)
+        args = [command, '-p',
+                '--input-format', 'stream-json',
+                '--output-format', 'stream-json', '--verbose',
+                '--model', request.model,
+                '--system-prompt', request.system_prompt,
+                '--tools', request.tools.join(','),
+                '--no-session-persistence',
+                '--setting-sources', '',
+                '--strict-mcp-config',
+                '--disable-slash-commands']
+        args << '--include-partial-messages' if request.stream
+        args.push('--allowedTools', request.tools.join(',')) if request.tools.any?
+        request.add_dirs.each { |dir| args.push('--add-dir', dir) }
+        args.push('--json-schema', JSON.generate(request.json_schema)) if request.json_schema
+        args.push('--effort', request.effort) if request.effort
+        args.concat(Array(@config.claude_cli_extra_args))
+      end
+
+      private
+
+      def command
+        @config.claude_cli_command || 'claude'
+      end
+
+      def read_events(stdout)
+        result = nil
+        stdout.each_line do |line|
+          next if line.strip.empty?
+
+          event = begin
+            JSON.parse(line)
+          rescue JSON::ParserError
+            RubyLLM.logger.debug { "claude-cli: non-JSON output #{line.inspect}" }
+            next
+          end
+          result = event if event['type'] == 'result'
+          yield event
+        end
+        result
+      end
+
+      def with_timeout(wait, &)
+        seconds = @config.claude_cli_timeout
+        return yield unless seconds
+
+        Timeout.timeout(seconds, &)
+      rescue Timeout::Error
+        Process.kill('KILL', wait.pid) rescue nil # rubocop:disable Style/RescueModifier
+        raise RubyLLM::Error, "claude -p did not finish within #{seconds}s"
+      end
+
+      def check!(result, status, stderr)
+        if result.nil?
+          raise RubyLLM::Error, "claude -p exited (#{status.exitstatus}) without a result: #{stderr.strip}"
+        end
+        if result['is_error']
+          detail = result['result'] || result['errors']&.join('; ') || result['subtype']
+          raise RubyLLM::Error, "claude -p failed: #{detail}"
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/ruby_llm/claude_cli/tool_emulation.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+module RubyLLM
+  module ClaudeCLI
+    # `claude -p` cannot call back into Ruby, so ruby_llm tools are emulated:
+    # the tools are described in the system prompt and the reply is forced
+    # through --json-schema into {text, tool_calls}. Tool calls come back to
+    # ruby_llm as ordinary ToolCalls, ruby_llm runs them, and the results go
+    # into the next request's transcript.
+    module ToolEmulation
+      module_function
+
+      def active_tools(tools, tool_prefs)
+        return [] if tool_prefs[:choice] == :none
+
+        list = tools.values
+        choice = tool_prefs[:choice]
+        list = list.select { |t| t.name.to_s == choice.to_s } unless choice.nil? || %i[auto required].include?(choice)
+        list
+      end
+
+      def instructions(tools, tool_prefs)
+        specs = tools.map do |tool|
+          fn = Protocols::Anthropic::Tools.function_for(tool)
+          "- #{fn[:name]}: #{fn[:description]}\n  input schema: #{JSON.generate(fn[:input_schema])}"
+        end
+        rule = if tool_prefs[:choice] && tool_prefs[:choice] != :auto
+                 'You must call at least one tool in this reply.'
+               else
+                 'Call tools only when they help; otherwise leave tool_calls empty.'
+               end
+        rule += ' Call at most one tool per reply.' if tool_prefs[:calls] == :one
+
+        <<~TEXT
+          # Tools
+          You can use these tools, which run on the caller's side:
+          #{specs.join("\n")}
+
+          To call tools, put them in "tool_calls" of your structured reply (name + arguments). You will
+          see their output in a later turn as <tool_result> blocks; never invent results yourself.
+          Put any text for the user in "text". #{rule}
+        TEXT
+      end
+
+      def schema(tools, tool_prefs, user_schema)
+        variants = tools.map do |tool|
+          fn = Protocols::Anthropic::Tools.function_for(tool)
+          { type: 'object',
+            properties: { name: { type: 'string', enum: [fn[:name]] }, arguments: clean(fn[:input_schema]) },
+            required: %w[name arguments] }
+        end
+        calls = { type: 'array', items: variants.one? ? variants.first : { anyOf: variants } }
+        calls[:minItems] = 1 if tool_prefs[:choice] && tool_prefs[:choice] != :auto
+        calls[:maxItems] = 1 if tool_prefs[:calls] == :one
+
+        properties = { text: { type: 'string' }, tool_calls: calls }
+        properties[:final] = user_schema_body(user_schema) if user_schema
+        { type: 'object', properties: properties, required: %w[text tool_calls] }
+      end
+
+      def user_schema_body(user_schema)
+        clean(user_schema[:schema])
+      end
+
+      # The CLI validates --json-schema strictly and rejects OpenAI's "strict".
+      def clean(schema)
+        case schema
+        when Hash then schema.reject { |k, _| k.to_s == 'strict' }.transform_values { |v| clean(v) }
+        when Array then schema.map { |v| clean(v) }
+        else schema
+        end
+      end
+
+      # Returns Anthropic-style content blocks for the structured reply.
+      def blocks(structured, user_schema)
+        structured ||= {}
+        blocks = []
+        text = if user_schema && structured['final'] && Array(structured['tool_calls']).empty?
+                 JSON.generate(structured['final'])
+               else
+                 structured['text'].to_s
+               end
+        blocks << { 'type' => 'text', 'text' => text } unless text.empty?
+        Array(structured['tool_calls']).each do |call|
+          blocks << { 'type' => 'tool_use', 'id' => "toolu_cli_#{SecureRandom.hex(10)}",
+                      'name' => call['name'], 'input' => call['arguments'] || {} }
+        end
+        blocks
+      end
+    end
+  end
+end

data/lib/ruby_llm/claude_cli/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ClaudeCLI
+    VERSION = '0.1.0'
+  end
+end

data/lib/ruby_llm/claude_cli.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require_relative 'claude_cli/version'
+require_relative 'claude_cli/runner'
+require_relative 'claude_cli/content'
+require_relative 'claude_cli/tool_emulation'
+require_relative 'claude_cli/protocol'
+require_relative 'claude_cli/provider'
+
+RubyLLM::Provider.register :claude_cli, RubyLLM::ClaudeCLI::Provider

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-claude_cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andreas Idogawa
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Use Claude Code (and its subscription login) as a RubyLLM provider:
+  streaming, images, PDFs, Office files, structured output and emulated tool calls
+  over `claude -p`.'
+email:
+- web@idogawa.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ruby_llm/claude_cli.rb
+- lib/ruby_llm/claude_cli/content.rb
+- lib/ruby_llm/claude_cli/protocol.rb
+- lib/ruby_llm/claude_cli/provider.rb
+- lib/ruby_llm/claude_cli/runner.rb
+- lib/ruby_llm/claude_cli/tool_emulation.rb
+- lib/ruby_llm/claude_cli/version.rb
+homepage: https://github.com/Largo/ruby_llm-claude_cli
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Largo/ruby_llm-claude_cli
+  changelog_uri: https://github.com/Largo/ruby_llm-claude_cli/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Largo/ruby_llm-claude_cli/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: RubyLLM provider that runs chats through the local `claude -p` CLI
+test_files: []