ruby_llm-providers-claude_code 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe5cd79fe98220731f2e1a919d13189ba320ddb9ac825358953e0ee57dd371f0
+  data.tar.gz: bb081f3ccfaa77ac8b49a2dbc126835d72532ee3cd321994b9185702fa6436f7
+SHA512:
+  metadata.gz: 0fad42bba710715989f5bd57a8e45603db0ffa04e8d1a0cfc09b29ae3961ccfb0cfcdf1c25276cd495a01ff03f2b4234f60fa0e69e8da00d79bcaa09b2663e08
+  data.tar.gz: f1ca13d507b49572d7a943504de2858b5ee819c7a3fbedd8f8f4e2822afc691638f63268b41b5e3785731c6e80469f564051da222781c2eca93415928141c5b3

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-11-06
+
+- Initial release: `claude -p` as a RubyLLM provider with resumable sessions,
+  streaming, structured output, effort levels and attachment notes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+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,123 @@
+# ruby_llm-providers-claude_code
+
+A [RubyLLM](https://rubyllm.com) provider that uses the **Claude Code agent**
+as the model. Each completion runs `claude -p` in batch mode, writes the
+prompt to its stdin and reads the JSON result from stdout.
+
+This is deliberately *not* an isolated stand-in for the Anthropic API. The
+agent keeps everything that makes it an agent: its own tools (Read, Edit,
+Bash, ...), its settings, hooks and MCP servers, and it works in the current
+directory. Multi-turn chats resume the same CLI session, so the agent keeps
+its context, tool results and plan between turns.
+
+```ruby
+require 'ruby_llm/providers/claude_code'
+
+chat = RubyLLM.chat(model: 'sonnet', provider: :claude_code)
+chat.ask('What does the Rakefile in this directory do?')
+chat.ask('Add a `lint` task to it') { |chunk| print chunk.content }
+```
+
+With [aia](https://github.com/madbomber/aia) the provider is picked from the
+model prefix, so any prompt, pipeline or multi-model run can be driven by the
+agent:
+
+```bash
+aia --model claude_code/opus refactor_prompt
+aia --model claude_code/sonnet=implementer,codex/default=reviewer --consensus review
+```
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RubyLLM 2.1 or newer
+- The Claude Code CLI on your PATH (`claude --version`), logged in. Requests
+  use whatever login Claude Code has; no API key is read by this gem.
+
+## Installation
+
+```ruby
+gem 'ruby_llm-providers-claude_code', require: 'ruby_llm/providers/claude_code'
+```
+
+The provider registers itself as `:claude_code` when required. No
+configuration is required.
+
+## Models
+
+The part after the slash goes straight to `claude --model`: an alias
+(`opus`, `sonnet`, `haiku`) or a full id such as `claude-opus-5-5`. The id
+`default` (or an empty id) sends no `--model` flag and lets the CLI choose.
+`list_models` returns this static set; any other id is passed through.
+
+## Sessions
+
+RubyLLM hands the provider the whole transcript on every turn. The provider
+fingerprints what it has sent before, and when the transcript minus the newest
+message matches what the CLI session already saw, it sends only the new
+message with `--resume <session id>`. Any other shape, such as a rewound or
+edited history, a cleared chat or a changed system prompt, starts a fresh
+session with the full conversation replayed as a tagged transcript.
+
+```ruby
+chat.with_provider_options(claude_code: { resume: false })      # fresh session every turn
+chat.with_provider_options(claude_code: { session_id: 'uuid' }) # continue a known session
+provider = chat.instance_variable_get(:@provider)
+provider.session.id                                              # the CLI session in use
+```
+
+## Configuration
+
+Global options are `RubyLLM.config.claude_code_*`; the same keys can be set
+per chat with `with_provider_options(claude_code: { ... })`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `command` | `claude` | CLI executable |
+| `cwd` | current directory | Directory the agent works in |
+| `timeout` | `600` | Seconds before the process group is killed; `nil` or `0` disables |
+| `permission_mode` | CLI default | `--permission-mode` (`acceptEdits`, `plan`, `bypassPermissions`, ...) |
+| `args` | none | Extra CLI arguments, array or shell string (`--add-dir`, `--max-turns`, `--mcp-config`, ...) |
+| `system_prompt_mode` | `append` | `append` adds RubyLLM instructions to Claude Code's prompt; `replace` uses them instead |
+| `env` | none | Extra environment variables for the process |
+| `resume` | `true` | Reuse the CLI session across turns |
+| `session_id` | none | Per-request only: force `--resume` with this id |
+
+```ruby
+RubyLLM.configure do |c|
+  c.claude_code_permission_mode = 'acceptEdits'
+  c.claude_code_timeout = 900
+  c.claude_code_args = ['--add-dir', '/path/to/other/repo']
+end
+```
+
+## What is supported
+
+| Feature | How |
+|---|---|
+| Text, system prompts, multi-turn | Native; see Sessions |
+| Streaming | `--output-format stream-json`; only the top-level agent's text is streamed, not subagent output |
+| Structured output (`with_schema`) | `--json-schema`; the result is the JSON string |
+| `with_thinking(effort:)` | `--effort` (low, medium, high, xhigh, max) |
+| Token counts and cost | From the CLI result, including cache reads and writes and `total_cost_usd` |
+| Attachments | Noted in the prompt as `[Attached file 'name': path]`; the agent opens local files itself |
+| RubyLLM tools (`with_tools`) | **Not supported**: raises `UnsupportedFeatureError`. The agent uses its own tools and MCP servers. The provider class answers `accepts_tools?` with `false` so hosts such as aia can skip attaching tools |
+| temperature, max tokens | Ignored (logged at debug level) |
+
+The streamed text is everything the agent says along the way; the returned
+message content is its final result.
+
+## Safety
+
+In batch mode the agent can edit files and run commands in `cwd` under its
+usual permission rules. Set `permission_mode` (or pass `--allowedTools` via
+`args`) deliberately rather than relying on defaults you have not looked at.
+
+## Development
+
+```bash
+bundle install
+asgard test_verbose       # offline: the CLI is replaced by a fake runner
+asgard quality            # tests, rubocop, flog, flay, reek, ...
+bin/console
+```

data/lib/ruby_llm/providers/claude_code/command.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Builds the argv for one `claude -p` invocation.
+      class Command
+        EFFORTS = %w[low medium high xhigh max].freeze
+
+        def initialize(settings)
+          @settings = settings
+        end
+
+        # @param model [String, nil] model id or alias; "default" means the CLI's own choice
+        # @param stream [Boolean] ask for stream-json output with partial messages
+        # @param resume_id [String, nil] CLI session id to continue
+        # @param system_prompt [String, nil] sent only when starting a session
+        # @param schema [Hash, nil] RubyLLM schema payload for structured output
+        # @param effort [String, nil] one of EFFORTS
+        # @return [Array<String>]
+        def build(model: nil, stream: false, resume_id: nil, system_prompt: nil, schema: nil, effort: nil)
+          argv = [@settings.command, '-p', '--output-format', stream ? 'stream-json' : 'json']
+          argv.push('--verbose', '--include-partial-messages') if stream
+          argv.push('--model', model.to_s) if self.class.named?(model)
+          argv.push('--resume', resume_id) if resume_id
+          argv.concat(system_prompt_args(system_prompt)) unless resume_id
+          argv.push('--permission-mode', @settings.permission_mode) if @settings.permission_mode
+          argv.push('--json-schema', JSON.generate(self.class.schema_definition(schema))) if schema
+          argv.push('--effort', effort) if effort
+          argv.concat(@settings.args)
+        end
+
+        class << self
+          def named?(model)
+            !(model.nil? || model.to_s.empty? || model.to_s == DEFAULT_MODEL)
+          end
+
+          # The bare JSON Schema from RubyLLM's payload, without the "strict"
+          # keys the CLI rejects.
+          def schema_definition(schema)
+            clean(schema[:schema] || schema['schema'] || schema)
+          end
+
+          def clean(schema)
+            case schema
+            when Hash then schema.reject { |key, _| key.to_s == 'strict' }.transform_values { |value| clean(value) }
+            when Array then schema.map { |value| clean(value) }
+            else schema
+            end
+          end
+        end
+
+        private
+
+        def system_prompt_args(text)
+          return [] if text.nil? || text.strip.empty?
+
+          flag = @settings.system_prompt_mode == 'replace' ? '--system-prompt' : '--append-system-prompt'
+          [flag, text]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Raised when the claude CLI cannot be run, exits without a result, or
+      # reports an error of its own.
+      class Error < RubyLLM::Error; end
+
+      # Raised when the CLI runs past the configured timeout and is killed.
+      class TimeoutError < Error; end
+
+      # Raised for RubyLLM features the CLI cannot honour, such as tools.
+      class UnsupportedFeatureError < Error; end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/response.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Reads the CLI's JSON output line by line. While streaming, text deltas
+      # from the top-level agent become Chunks; the final "result" event
+      # becomes the Message.
+      class Response
+        STOP_REASONS = { 'end_turn' => :stop, 'stop_sequence' => :stop, 'max_tokens' => :max_tokens }.freeze
+
+        attr_reader :session_id, :result, :model_id
+
+        def initialize(model:, schema: nil)
+          @model  = model
+          @schema = schema
+          @blocks = {}
+        end
+
+        # @param line [String] one line of stdout
+        # @yield [RubyLLM::Chunk] a streamed piece of assistant text
+        # @return [Hash, nil] the parsed event, or nil for non-JSON lines
+        def ingest(line)
+          event = self.class.parse(line)
+          return nil unless event
+
+          case event['type']
+          when 'stream_event'
+            text = text_delta(event)
+            yield chunk(text) if text && block_given?
+          when 'assistant' then @model_id ||= event.dig('message', 'model')
+          when 'result'
+            @result = event
+            @session_id = event['session_id']
+          when 'system' then @session_id ||= event['session_id']
+          end
+          event
+        end
+
+        # @param run [Runner::Result, nil] used for diagnostics when no result arrived
+        # @return [RubyLLM::Message]
+        def message(run = nil)
+          raise_without_result!(run) unless @result
+          raise Error, "claude -p failed: #{error_detail}" if @result['is_error']
+
+          usage = @result['usage'] || {}
+          Message.new(
+            role: :assistant,
+            content: content,
+            model: @model,
+            input_tokens: usage['input_tokens'],
+            output_tokens: usage['output_tokens'],
+            cache_read_tokens: usage['cache_read_input_tokens'],
+            cache_write_tokens: usage['cache_creation_input_tokens'],
+            thinking_tokens: usage.dig('output_tokens_details', 'thinking_tokens'),
+            reported_cost: @result['total_cost_usd'],
+            finish_reason: STOP_REASONS.fetch(@result['stop_reason'], :stop),
+            raw: @result
+          )
+        end
+
+        def self.parse(line)
+          text = line.to_s.strip
+          return nil unless text.start_with?('{')
+
+          JSON.parse(text)
+        rescue JSON::ParserError
+          RubyLLM.logger.debug { "claude_code: non-JSON output #{text.inspect}" }
+          nil
+        end
+
+        private
+
+        def content
+          structured = @result['structured_output']
+          return JSON.generate(structured) if @schema && !structured.nil?
+
+          @result['result'].to_s
+        end
+
+        def error_detail
+          detail = @result['result'].to_s
+          detail = Array(@result['errors']).join('; ') if detail.empty?
+          detail = @result['subtype'].to_s if detail.empty?
+          detail
+        end
+
+        def raise_without_result!(run)
+          status = run&.status&.exitstatus
+          stderr = run&.stderr.to_s.strip
+          raise Error,
+                "claude -p exited#{" (#{status})" if status} without a result#{": #{stderr}" unless stderr.empty?}"
+        end
+
+        # Text from the top-level agent only: subagent output carries a
+        # parent_tool_use_id and is not part of the reply.
+        def text_delta(event)
+          return nil unless event['parent_tool_use_id'].nil?
+
+          data  = event['event'] || {}
+          index = data['index']
+          case data['type']
+          when 'content_block_start'
+            @blocks[index] = data.dig('content_block', 'type')
+            nil
+          when 'content_block_delta'
+            delta = data['delta'] || {}
+            delta['text'] if delta['type'] == 'text_delta' && (@blocks[index].nil? || @blocks[index] == 'text')
+          end
+        end
+
+        def chunk(text)
+          Chunk.new(role: :assistant, content: text, model: @model)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Spawns the CLI, feeds it stdin, and yields each stdout line on the
+      # caller's thread as it arrives. The process group is killed when the
+      # timeout passes.
+      class Runner
+        # What the process produced: full stdout, full stderr, and its exit status.
+        Result = Data.define(:stdout, :stderr, :status)
+        GRACE_SECONDS = 2
+        EOF = Object.new.freeze
+
+        # @param argv [Array<String>] command and arguments
+        # @param stdin [String] text written to the process's stdin
+        # @param cwd [String, nil] working directory (default: Dir.pwd)
+        # @param timeout [Numeric, nil] seconds before the process is killed
+        # @param env [Hash] extra environment variables
+        # @yield [String] each line of stdout
+        # @return [Result]
+        def run(argv, stdin: '', cwd: nil, timeout: nil, env: {}, &block)
+          Open3.popen3(env.to_h, *argv, chdir: cwd || Dir.pwd, pgroup: true) do |input, output, error, wait|
+            collect(input, output, error, wait, stdin:, timeout:, &block)
+          rescue TimeoutError
+            terminate(wait)
+            raise TimeoutError, "#{argv.first} did not finish within #{timeout}s"
+          end
+        rescue Errno::ENOENT => e
+          raise Error, "cannot run #{argv.first.inspect}: #{e.message}"
+        end
+
+        private
+
+        # Drives one spawned process: feeds stdin and reads stderr on their own
+        # threads, pumps stdout through a queue so each line can be yielded
+        # before the process exits, and assembles the Result once it does.
+        def collect(input, output, error, wait, stdin:, timeout:)
+          feeder = Thread.new { feed(input, stdin) }
+          errors = Thread.new { error.read }
+          queue  = Queue.new
+          reader = Thread.new { pump(output, queue) }
+          lines  = []
+          drain(queue, deadline(timeout)) do |line|
+            lines << line
+            yield line if block_given?
+          end
+          [feeder, reader].each(&:join)
+          Result.new(stdout: lines.join, stderr: errors.value.to_s, status: wait.value)
+        end
+
+        def deadline(timeout)
+          timeout && (now + timeout)
+        end
+
+        def feed(input, text)
+          input.binmode
+          input.write(text.to_s)
+        rescue Errno::EPIPE, IOError
+          nil
+        ensure
+          input.close unless input.closed?
+        end
+
+        def pump(output, queue)
+          output.each_line { |line| queue << line }
+        ensure
+          queue << EOF
+        end
+
+        # Pops lines until EOF, raising TimeoutError once the deadline passes.
+        def drain(queue, deadline)
+          loop do
+            remaining = deadline && [deadline - now, 0].max
+            line = remaining ? queue.pop(timeout: remaining) : queue.pop
+            raise TimeoutError if line.nil?
+            break if line.equal?(EOF)
+
+            yield line
+          end
+        end
+
+        def terminate(wait)
+          pgid = -wait.pid
+          Process.kill('TERM', pgid)
+          return if wait.join(GRACE_SECONDS)
+
+          Process.kill('KILL', pgid)
+          wait.join
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/session.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Decides, per completion, whether to resume the CLI session that
+      # answered the previous turn or to start a new one. A session is resumed
+      # only when the transcript RubyLLM hands over, minus the newest message,
+      # is exactly what that session already saw. A rewound, edited or cleared
+      # history gets a fresh session replayed from the whole transcript.
+      class Session
+        Plan = Data.define(:messages, :resume_id) do
+          def resume?
+            !resume_id.nil?
+          end
+        end
+
+        attr_reader :id
+
+        def initialize
+          reset!
+        end
+
+        # @param messages [Array<RubyLLM::Message>] the full RubyLLM transcript
+        # @param session_id [String, nil] a caller-chosen session to continue
+        # @param resume [Boolean] false forces a fresh session every time
+        # @return [Plan] the messages to send and the session to resume, if any
+        def plan(messages, session_id: nil, resume: true)
+          raise ArgumentError, 'no messages to send' if messages.empty?
+          return Plan.new(messages: [messages.last], resume_id: session_id) if session_id
+          return Plan.new(messages: messages, resume_id: nil) unless resume && continues?(messages)
+
+          Plan.new(messages: [messages.last], resume_id: @id)
+        end
+
+        # Remember which session answered, and what it has now seen.
+        def record(messages, reply, id:)
+          @id = id
+          @fingerprint = id ? Transcript.fingerprint(messages + [reply]) : nil
+        end
+
+        def reset!
+          @id = nil
+          @fingerprint = nil
+        end
+
+        private
+
+        def continues?(messages)
+          return false unless @id && @fingerprint && messages.size > 1
+
+          Transcript.fingerprint(messages[0...-1]) == @fingerprint
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/settings.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # The settings for one completion. Each value comes from, in order of
+      # precedence, chat.with_provider_options(claude_code: {...}), the
+      # RubyLLM.config.claude_code_* option, then the default here.
+      class Settings
+        DEFAULT_COMMAND = 'claude'
+        DEFAULT_TIMEOUT = 600
+        SYSTEM_PROMPT_MODES = %w[append replace].freeze
+
+        attr_reader :command, :cwd, :timeout, :permission_mode, :args, :system_prompt_mode, :env, :session_id
+
+        def initialize(config, provider_options = {})
+          opts = self.class.namespaced(provider_options)
+          @command            = opts.fetch(:command) { config.claude_code_command } || DEFAULT_COMMAND
+          @cwd                = opts.fetch(:cwd) { config.claude_code_cwd }
+          @timeout            = self.class.positive_or_nil(opts.fetch(:timeout) { timeout_default(config) })
+          @permission_mode    = opts.fetch(:permission_mode) { config.claude_code_permission_mode }&.to_s
+          @args               = self.class.split_args(opts.fetch(:args) { config.claude_code_args })
+          @system_prompt_mode = self.class.mode(opts.fetch(:system_prompt_mode) do
+            config.claude_code_system_prompt_mode
+          end)
+          @env                = self.class.stringify(opts.fetch(:env) { config.claude_code_env })
+          @session_id         = opts[:session_id]
+          @resume             = opts.fetch(:resume) { config.claude_code_resume.nil? || config.claude_code_resume }
+        end
+
+        # False when every completion must start a fresh CLI session.
+        def resume?
+          @resume ? true : false
+        end
+
+        class << self
+          # The claude_code: sub-hash of provider_options with symbol keys.
+          def namespaced(provider_options)
+            return {} unless provider_options.is_a?(Hash)
+
+            raw = provider_options[:claude_code] || provider_options['claude_code'] || {}
+            raise ArgumentError, 'provider_options[:claude_code] must be a Hash' unless raw.is_a?(Hash)
+
+            raw.transform_keys(&:to_sym)
+          end
+
+          # A positive number of seconds, or nil for "no timeout".
+          def positive_or_nil(value)
+            return nil if value.nil?
+
+            number = Float(value)
+            number.positive? ? number : nil
+          end
+
+          # Extra CLI arguments given as an array or a shell-style string.
+          def split_args(value)
+            case value
+            when nil then []
+            when String then Shellwords.split(value)
+            else Array(value).map(&:to_s)
+            end
+          end
+
+          def mode(value)
+            return 'append' if value.nil?
+
+            text = value.to_s
+            return text if SYSTEM_PROMPT_MODES.include?(text)
+
+            raise ArgumentError, "claude_code system_prompt_mode must be one of #{SYSTEM_PROMPT_MODES.join(', ')}"
+          end
+
+          def stringify(value)
+            (value || {}).to_h.to_h { |key, item| [key.to_s, item.to_s] }
+          end
+        end
+
+        private
+
+        def timeout_default(config)
+          config.claude_code_timeout.nil? ? DEFAULT_TIMEOUT : config.claude_code_timeout
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/transcript.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module RubyLLM
+  module Providers
+    class ClaudeCode < Provider
+      # Renders RubyLLM messages into the text the CLI reads from stdin, and
+      # fingerprints transcripts so Session can tell whether a CLI session
+      # already holds the earlier turns.
+      class Transcript
+        REPLAY_PREAMBLE = "The conversation so far follows. Continue it by writing the assistant's next reply " \
+                          "to the last turn. Do not repeat the tags.\n\n"
+        EMPTY = '(empty message)'
+
+        class << self
+          def fingerprint(messages)
+            Digest::SHA256.hexdigest(JSON.generate(messages.map { |message| summary(message) }))
+          end
+
+          def summary(message)
+            {
+              role: message.role.to_s,
+              content: message.content.to_s,
+              tool_call_id: message.tool_call_id,
+              tool_calls: tool_calls(message).map { |call| [call.id, call.name, call.arguments] },
+              attachments: attachments(message).map { |attachment| attachment_note(attachment) }
+            }
+          end
+
+          # The message text plus a note per attachment naming its location;
+          # the agent can open local files with its own tools.
+          def text_of(message)
+            parts = [message.content.to_s]
+            attachments(message).each { |attachment| parts << attachment_note(attachment) }
+            parts.reject(&:empty?).join("\n").strip
+          end
+
+          def attachment_note(attachment)
+            source = attachment.respond_to?(:source) ? attachment.source : attachment
+            name = attachment.respond_to?(:filename) ? attachment.filename : nil
+            location = source.respond_to?(:to_path) ? source.to_path : source.to_s
+            "[Attached file#{" '#{name}'" if name}: #{location}]"
+          end
+
+          def attachments(message)
+            message.respond_to?(:attachments) ? Array(message.attachments) : []
+          end
+
+          def tool_calls(message)
+            calls = message.respond_to?(:tool_calls) ? message.tool_calls : nil
+            calls.respond_to?(:values) ? calls.values : Array(calls)
+          end
+        end
+
+        def initialize(messages)
+          @system, @turns = messages.partition { |message| message.role == :system }
+        end
+
+        # All system messages joined, or nil when there are none.
+        def system_prompt
+          text = @system.map { |message| self.class.text_of(message) }.reject(&:empty?).join("\n\n")
+          text.empty? ? nil : text
+        end
+
+        # A lone user turn goes through as-is; anything longer becomes a
+        # tagged replay of the conversation.
+        def prompt
+          return EMPTY if @turns.empty?
+          return single_turn if @turns.one? && @turns.first.role == :user
+
+          REPLAY_PREAMBLE + @turns.map { |message| turn(message) }.join("\n")
+        end
+
+        private
+
+        def single_turn
+          text = self.class.text_of(@turns.first)
+          text.empty? ? EMPTY : text
+        end
+
+        def turn(message)
+          body = self.class.text_of(message)
+          case message.role
+          when :tool then "<tool_result id=\"#{message.tool_call_id}\">\n#{body}\n</tool_result>"
+          when :assistant then "<assistant>\n#{body}#{tool_calls_text(message)}\n</assistant>"
+          else "<user>\n#{body}\n</user>"
+          end
+        end
+
+        def tool_calls_text(message)
+          self.class.tool_calls(message).map do |call|
+            "\n<tool_call id=\"#{call.id}\" name=\"#{call.name}\">#{JSON.generate(call.arguments)}</tool_call>"
+          end.join
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Version of the ruby_llm-providers-claude_code gem. Kept in its own file
+    # so the gemspec can read the literal without loading the provider.
+    class ClaudeCode < Provider
+      VERSION = '0.0.1'
+
+      def self.version
+        VERSION
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/claude_code.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'ruby_llm/providers/claude_code/version'
+require 'ruby_llm/providers/claude_code/errors'
+require 'ruby_llm/providers/claude_code/settings'
+require 'ruby_llm/providers/claude_code/command'
+require 'ruby_llm/providers/claude_code/transcript'
+require 'ruby_llm/providers/claude_code/session'
+require 'ruby_llm/providers/claude_code/runner'
+require 'ruby_llm/providers/claude_code/response'
+
+module RubyLLM
+  module Providers
+    # ClaudeCode: the Claude Code agent (`claude -p`) as a RubyLLM provider.
+    #
+    # Each completion spawns the claude CLI in batch mode, writes the prompt
+    # to its stdin and reads its JSON result from stdout. The agent keeps its
+    # own tools, settings and MCP servers and works in the current directory
+    # (or config.claude_code_cwd), so the "model" can read and edit files and
+    # run commands. Multi-turn chats resume the same CLI session (--resume)
+    # as long as the RubyLLM transcript still matches what that session has
+    # seen; otherwise a fresh session is started from the whole transcript.
+    #
+    #   require 'ruby_llm/providers/claude_code'
+    #   chat = RubyLLM.chat(model: 'sonnet', provider: :claude_code)
+    #   chat.ask('Summarise the README in this directory')
+    class ClaudeCode < Provider
+      DEFAULT_MODEL = 'default'
+      MODELS = %w[default opus sonnet haiku].freeze
+      CAPABILITIES = %w[streaming structured_output].freeze
+
+      # Satisfies RubyLLM's protocol lookups; every request goes through
+      # #complete below, never through a wire protocol.
+      protocol :claude_code, RubyLLM::Protocol
+
+      class << self
+        # Anything responding to #run like Runner; tests inject fakes here.
+        attr_accessor :runner
+
+        def configuration_options
+          %i[
+            claude_code_command
+            claude_code_cwd
+            claude_code_timeout
+            claude_code_permission_mode
+            claude_code_args
+            claude_code_system_prompt_mode
+            claude_code_env
+            claude_code_resume
+          ]
+        end
+
+        def configuration_requirements
+          []
+        end
+
+        def local?
+          true
+        end
+
+        # Any id goes straight to --model, so there is no catalog to check.
+        def assume_models_exist?
+          true
+        end
+
+        # The agent runs its own tools; RubyLLM tools cannot be handed to it.
+        # Hosts such as aia check this before attaching tools or MCP servers.
+        def accepts_tools?
+          false
+        end
+
+        def display_name
+          'Claude Code'
+        end
+      end
+
+      attr_reader :session
+
+      def initialize(config)
+        super
+        @session = Session.new
+      end
+
+      # Never contacted; the transport layer only needs a base URL.
+      def api_base
+        'cli://claude'
+      end
+
+      # Messages go to the CLI as text, so there is nothing to upload or
+      # convert beforehand.
+      def preprocess_messages(messages, **)
+        messages
+      end
+
+      def discard_missing_uploads(_messages, _error, **)
+        []
+      end
+
+      # :reek:LongParameterList -- the keyword set is RubyLLM's Provider#complete contract
+      def complete(messages, model:, tools: {}, provider_options: {}, schema: nil, thinking: nil,
+                   temperature: nil, max_output_tokens: nil, before_request: [], **, &block)
+        reject_tools!(tools)
+        log_ignored(temperature:, max_output_tokens:)
+        settings   = Settings.new(@config, provider_options)
+        plan       = session.plan(messages, session_id: settings.session_id, resume: settings.resume?)
+        transcript = Transcript.new(plan.messages)
+        argv       = build_argv(settings, model, transcript, plan, schema, thinking, block)
+        before_request.each { |hook| hook.call({ argv: argv, prompt: transcript.prompt }) }
+        response   = Response.new(model: model, schema: schema)
+        run        = runner.run(argv, stdin: transcript.prompt, cwd: settings.cwd, timeout: settings.timeout,
+                                      env: settings.env) do |line|
+          response.ingest(line) { |chunk| block.call(chunk) }
+        end
+        message = response.message(run)
+        session.record(messages, message, id: response.session_id)
+        message
+      end
+
+      # A static catalog: the CLI's aliases plus "default" for its own choice.
+      def list_models
+        MODELS.map { |id| static_model(id) }
+      end
+
+      private
+
+      def runner
+        self.class.runner || Runner.new
+      end
+
+      def build_argv(settings, model, transcript, plan, schema, thinking, block)
+        Command.new(settings).build(
+          model: self.class.model_id(model),
+          stream: !block.nil?,
+          resume_id: plan.resume_id,
+          system_prompt: transcript.system_prompt,
+          schema: schema,
+          effort: self.class.effort_for(thinking)
+        )
+      end
+
+      def static_model(id)
+        Model.new(
+          id: id,
+          name: "Claude Code (#{id})",
+          provider: slug,
+          capabilities: CAPABILITIES,
+          modalities: { input: %w[text], output: %w[text] },
+          metadata: { source: 'ruby_llm-providers-claude_code' }
+        )
+      end
+
+      def reject_tools!(tools)
+        return if tools.nil? || tools.empty?
+
+        raise UnsupportedFeatureError,
+              'RubyLLM tools cannot be handed to the claude CLI; the agent brings its own tools. ' \
+              'Remove with_tools or choose another provider.'
+      end
+
+      def log_ignored(**options)
+        ignored = options.compact.keys
+        return if ignored.empty?
+
+        RubyLLM.logger.debug { "claude_code: ignoring #{ignored.join(', ')} (not supported by claude -p)" }
+      end
+
+      class << self
+        def model_id(model)
+          model.respond_to?(:id) ? model.id : model.to_s
+        end
+
+        def effort_for(thinking)
+          return nil unless thinking.respond_to?(:effort) && thinking.effort
+
+          value = thinking.effort.to_s
+          Command::EFFORTS.include?(value) ? value : nil
+        end
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :claude_code, RubyLLM::Providers::ClaudeCode unless RubyLLM::Provider.resolve(:claude_code)

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-providers-claude_code
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+  - Dewayne VanHoozer
+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.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "2.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+description: "Adds a claude_code provider to RubyLLM. Prompts are written to the Claude Code CLI's stdin in batch mode and its JSON result is read back from stdout, so the agent (with its own tools, settings and resumable sessions) can be used wherever RubyLLM expects a model, e.g. `--model claude_code/opus` in aia."
+email:
+  - dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+  - CHANGELOG.md
+  - LICENSE.txt
+  - README.md
+  - lib/ruby_llm/providers/claude_code.rb
+  - lib/ruby_llm/providers/claude_code/command.rb
+  - lib/ruby_llm/providers/claude_code/errors.rb
+  - lib/ruby_llm/providers/claude_code/response.rb
+  - lib/ruby_llm/providers/claude_code/runner.rb
+  - lib/ruby_llm/providers/claude_code/session.rb
+  - lib/ruby_llm/providers/claude_code/settings.rb
+  - lib/ruby_llm/providers/claude_code/transcript.rb
+  - lib/ruby_llm/providers/claude_code/version.rb
+homepage: "https://github.com/madbomber/ruby_llm-providers-claude_code"
+licenses:
+  - MIT
+metadata:
+  homepage_uri: "https://github.com/madbomber/ruby_llm-providers-claude_code"
+  source_code_uri: "https://github.com/madbomber/ruby_llm-providers-claude_code"
+  changelog_uri: "https://github.com/madbomber/ruby_llm-providers-claude_code/blob/main/CHANGELOG.md"
+  bug_tracker_uri: "https://github.com/madbomber/ruby_llm-providers-claude_code/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.1.0.beta3
+specification_version: 4
+summary: RubyLLM provider that drives the Claude Code agent through `claude -p`.
+test_files: []