ruby_claude 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 46dffd5cda4df76cdd6a657076af87f43c068929ce40b0973e2aa4dd26b4a7f1
+  data.tar.gz: 5c55b6f8448491d93d3716bbfe9694ea7f160bef7bd1c5410a3021778f5b362a
+SHA512:
+  metadata.gz: 34dcef3922757a6b7580f196f0528268b9827ec6bdf0fea979ef768a7d12ecc0723c3f75dcec094b25f8dd45d7a20c682aef654e535f878775d4470bcd33a615
+  data.tar.gz: 0b2ecd60e8dbf74ef7d64b4b0eda9932b7b9dc5aad6a1c09aeb1dabaa159de5f0fdd1656b13cfc5944b7b681d269bc69668a967e2e8d825a92320244b86d14c5

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kaíque Kandy Koga
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,289 @@
+# Ruby Claude
+
+A small, dependency-light, idiomatic Ruby SDK for talking to Claude — by
+shelling out to the **Claude Code CLI** (`claude -p`) in headless mode and
+authenticating with your **Claude Pro/Max subscription** instead of an
+Anthropic API key.
+
+> **Unofficial.** This is a community gem. It is *not* affiliated with or
+> endorsed by Anthropic. It uses a documented, supported headless feature
+> (`claude -p`) and stays within your subscription's normal rate limits. It
+> does **not** extract or reuse OAuth tokens, and it makes **no** direct HTTP
+> calls to the Anthropic API.
+
+## Why a subscription instead of an API key?
+
+`claude -p "<prompt>"` runs Claude Code non-interactively and prints the
+result, using whatever credentials the CLI is logged in with. If you logged in
+with a **subscription** (`claude` → `/login` → subscription option), those
+calls draw on your subscription — **no API billing**.
+
+The one catch: if `ANTHROPIC_API_KEY` is present in the environment, Claude
+Code may use it and bill the API. **Ruby Claude strips `ANTHROPIC_API_KEY`
+from the child process environment by default** (`use_subscription = true`) so
+the CLI falls back to your logged-in subscription credentials. Set
+`use_subscription = false` only if you *want* API-key billing.
+
+## Prerequisites
+
+This gem drives the `claude` binary; it does not install or replace it.
+
+1. Install Node.js and the Claude Code CLI, and make sure `claude` is on your `PATH`:
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   claude --version
+   ```
+2. Log in **once**, choosing the subscription option:
+   ```bash
+   claude        # then run /login and pick "Claude account with subscription"
+   ```
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem "ruby_claude"
+```
+
+Or install directly:
+
+```bash
+gem install ruby_claude
+```
+
+Ruby **3.2+** is required (the value objects use `Data.define`). The gem has
+**zero runtime dependencies** — it only uses the standard library.
+
+## Quickstart
+
+```ruby
+require "ruby_claude"
+
+puts RubyClaude.query("Summarize lib/foo.rb in two sentences")
+```
+
+That's it — if `claude` is installed and logged in, you get an answer back,
+billed against your subscription.
+
+## Usage
+
+### 1. One-shot convenience
+
+Delegates to a memoized, globally-configured default client.
+
+```ruby
+puts RubyClaude.query("Summarize lib/foo.rb in two sentences")
+```
+
+### 2. A configured client
+
+```ruby
+client = RubyClaude::Client.new(
+  model: "claude-sonnet-4-6",
+  cwd: "/path/to/project",
+  append_system_prompt: "Always answer concisely.",
+  allowed_tools: ["Read", "Grep"],
+  timeout: 180
+)
+
+res = client.query("What does this project do?")
+res.text        # => String, the final assistant result
+res.session_id  # => String
+res.cost_usd    # => Float (often 0.0 on a subscription)
+res.usage       # => Hash (token counts, when present)
+res.num_turns   # => Integer
+res.duration_ms # => Integer
+res.error?      # => false
+res.raw         # => parsed Hash of the CLI's final result JSON
+```
+
+`Response#to_s` returns `text`, so `puts client.query("...")` prints the answer.
+
+### 3. Streaming
+
+`#stream` yields typed events as they arrive and returns the final `Response`.
+
+```ruby
+client.stream("Write a haiku about Ruby") do |event|
+  case event.type
+  when :assistant then print event.text   # assistant text for the turn
+  when :result    then puts "\n[done in #{event.duration_ms}ms]"
+  end
+end
+```
+
+Each `Event` exposes `type` (`:system`, `:assistant`, `:user`, `:result`),
+`text`, `session_id`, `cost_usd`, `duration_ms`, and `raw` (the full parsed
+line). Streaming uses `--output-format stream-json --verbose` under the hood.
+
+### 4. Multi-turn session
+
+A `Session` captures the underlying `session_id` from the first reply and
+transparently resumes it on later calls.
+
+```ruby
+session = client.session
+session.query("My favorite number is 7.")
+puts session.query("What's my favorite number?")  # => "...7..."
+session.id  # => the session_id being resumed
+```
+
+You can also resume a known session: `client.session(id: "…")`.
+
+### 5. Global configuration
+
+```ruby
+RubyClaude.configure do |c|
+  c.model            = "claude-sonnet-4-6"
+  c.timeout          = 300
+  c.binary           = "claude"   # path/name of the CLI
+  c.cwd              = Dir.pwd
+  c.use_subscription = true       # strips ANTHROPIC_API_KEY from the child env
+end
+```
+
+These become the defaults for `RubyClaude.query` and for new `Client`
+instances. Per-client options passed to `Client.new(**opts)` override them.
+
+> **Note:** there is intentionally no `#send` method (it would shadow
+> `Object#send`). Use `#query`, or its alias `#ask`.
+
+## Configuration options
+
+| Option                 | Default              | Maps to / effect                                                          |
+|------------------------|----------------------|---------------------------------------------------------------------------|
+| `binary`               | `"claude"`           | executable name/path                                                      |
+| `model`                | `nil` (CLI default)  | `--model`                                                                 |
+| `cwd`                  | `Dir.pwd`            | working directory for the subprocess                                      |
+| `timeout`              | `300`                | seconds before the child is killed                                        |
+| `use_subscription`     | `true`               | when true, delete `ANTHROPIC_API_KEY` from the child env                  |
+| `append_system_prompt` | `nil`                | `--append-system-prompt`                                                  |
+| `allowed_tools`        | `nil`                | `--allowedTools` (array of tool/permission rules)                         |
+| `disallowed_tools`     | `nil`                | `--disallowedTools`                                                       |
+| `add_dirs`             | `[]`                 | `--add-dir` (extra readable/writable directories)                         |
+| `permission_mode`      | `nil`                | `--permission-mode` (`default` / `acceptEdits` / `plan` / `bypassPermissions`) |
+| `max_turns`            | `nil`                | `--max-turns`                                                             |
+
+Tool and directory lists are passed as separate CLI tokens, so permission-rule
+patterns that contain spaces (e.g. `"Bash(git log *)"`) are preserved.
+
+## Errors
+
+All errors inherit from `RubyClaude::Error`:
+
+| Error                            | Raised when                                                                 |
+|----------------------------------|-----------------------------------------------------------------------------|
+| `RubyClaude::BinaryNotFoundError`| `claude` is not on `PATH` / not executable (message explains how to install)|
+| `RubyClaude::AuthenticationError`| output/exit indicates you are not logged in (suggests `claude` + `/login`)  |
+| `RubyClaude::TimeoutError`       | the child exceeded `timeout`; the gem killed it                             |
+| `RubyClaude::ExecutionError`     | non-zero exit, or a result with `is_error: true` (carries `#status`, `#stderr`) |
+| `RubyClaude::ParseError`         | the CLI output couldn't be parsed as the expected JSON                      |
+
+```ruby
+begin
+  RubyClaude.query("hello")
+rescue RubyClaude::BinaryNotFoundError => e
+  warn e.message   # install + /login instructions
+rescue RubyClaude::AuthenticationError
+  warn "Run `claude` and `/login` with your subscription."
+rescue RubyClaude::ExecutionError => e
+  warn "claude failed (status #{e.status}): #{e.stderr}"
+end
+```
+
+## How it works
+
+Ruby Claude is a thin, well-factored wrapper around `claude -p`:
+
+- **`Command`** (pure, no I/O) turns your configuration + per-call options into
+  the argv array (`["claude", "-p", "--output-format", "json", …]`) and the
+  child-environment overrides (removing `ANTHROPIC_API_KEY` in subscription mode).
+- **`Runner`** owns all subprocess concerns: it spawns `claude` via `Open3`
+  (always the array form — your prompt is **never** shell-interpolated), writes
+  the prompt to **stdin** (avoiding `ARG_MAX` and escaping issues), enforces the
+  timeout by killing the child, captures output, and — for streaming — reads
+  stdout line-by-line as newline-delimited JSON.
+- **`Client`** composes the two and builds `Response` / `Event` objects.
+- **`Session`** remembers the `session_id` and passes `--resume <id>`.
+
+The runner is stateless and spawns one subprocess per call, so a `Client` is
+safe to reuse and to call concurrently from multiple threads.
+
+## Development
+
+```bash
+bundle install   # install dev/test dependencies
+rake test        # run the test suite (hermetic — never spawns claude)
+rake lint        # rubocop
+rake             # test + lint
+bin/console      # IRB with the gem loaded
+```
+
+Tests inject a fake runner at the `Client`'s runner boundary, so the suite is
+fully hermetic: it never makes a network call and never invokes the real
+`claude` binary. (A handful of `Runner` tests spawn a throwaway local `ruby`
+process to exercise the subprocess plumbing.)
+
+## Building and publishing the gem
+
+The version lives in [`lib/ruby_claude/version.rb`](lib/ruby_claude/version.rb).
+Before a release, bump it following [SemVer](https://semver.org).
+
+### Build locally
+
+```bash
+gem build ruby_claude.gemspec        # => ruby_claude-<version>.gem
+gem install ./ruby_claude-<version>.gem   # try the built gem locally
+```
+
+`spec.files` is derived from `git ls-files`, so only **tracked** files are
+packaged — commit (or at least stage) your changes before building, or the gem
+will be missing files. Bundler's gem tasks do the same and drop the artifact in
+`pkg/`:
+
+```bash
+rake build      # build into pkg/
+rake install    # build and install locally
+```
+
+### Publish to RubyGems
+
+1. Create a [RubyGems.org](https://rubygems.org) account and sign in once
+   (credentials are stored in `~/.gem/credentials`):
+
+   ```bash
+   gem signin
+   ```
+
+2. Make sure the tree is green and committed:
+
+   ```bash
+   rake            # tests + lint
+   git status      # nothing uncommitted
+   ```
+
+3. Build and push:
+
+   ```bash
+   gem build ruby_claude.gemspec
+   gem push ruby_claude-<version>.gem
+   ```
+
+   The name `ruby_claude` is currently available on RubyGems. Releasing
+   `0.0.0` is unusual — bump to e.g. `0.1.0` for your first real publish.
+
+Alternatively, do it all in one step with Bundler's release task, which builds
+the gem, creates and pushes a `v<version>` git tag, and pushes to RubyGems
+(requires a clean, committed tree):
+
+```bash
+rake release
+```
+
+> The gemspec sets `rubygems_mfa_required`, so enable MFA on your RubyGems
+> account; pushes and yanks will then prompt for a one-time code.
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

data/lib/ruby_claude/client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyClaude
+  # Composes a {Command} and a {Runner} to execute queries and build
+  # {Response} and {Event} objects.
+  #
+  # A client holds an immutable {Configuration} and a stateless runner, builds
+  # fresh argv/env per call, and never mutates shared state — so one instance
+  # is safe to reuse and to call concurrently from many threads.
+  class Client
+    # Heuristic patterns in stderr/result text that indicate an auth problem.
+    # Deliberately specific: bare "authentication" / "api key" / "credit
+    # balance" match too much benign text and would misclassify ordinary
+    # execution and billing failures as authentication errors.
+    AUTH_PATTERNS = Regexp.union(
+      /invalid api key/i,
+      /authentication[ _](?:failed|error|required)/i,
+      /unauthorized/i,
+      /not logged ?in/i,
+      %r{/login}i,
+      /oauth/i,
+      /log ?in to claude/i
+    ).freeze
+
+    # @return [Configuration] the effective configuration for this client
+    attr_reader :config
+
+    # @param runner [#run, #stream] subprocess runner (injectable for tests)
+    # @param overrides [Hash] per-instance {Configuration} overrides
+    # @raise [ArgumentError] on an unknown configuration option
+    def initialize(runner: Runner.new, **overrides)
+      @config = RubyClaude.configuration.merge(overrides)
+      @runner = runner
+    end
+
+    # Run a one-shot query and return its {Response}.
+    #
+    # @param prompt [String]
+    # @param resume [String, nil] a session id to resume
+    # @return [Response]
+    # @raise [AuthenticationError, ExecutionError, ParseError, TimeoutError,
+    #   BinaryNotFoundError]
+    def query(prompt, resume: nil)
+      argv, env = Command.new(@config).build(stream: false, resume: resume)
+      result = @runner.run(**run_args(argv, env, prompt))
+      interpret(result)
+    end
+    alias ask query
+
+    # Stream a query, yielding {Event}s as they arrive.
+    #
+    # @param prompt [String]
+    # @param resume [String, nil] a session id to resume
+    # @yieldparam event [Event]
+    # @return [Response] the final result, built from the +result+ event
+    # @raise [AuthenticationError, ExecutionError, TimeoutError,
+    #   BinaryNotFoundError]
+    def stream(prompt, resume: nil)
+      argv, env = Command.new(@config).build(stream: true, resume: resume)
+      final = nil
+      result = @runner.stream(**run_args(argv, env, prompt)) do |line|
+        data = try_parse(line)
+        next unless data
+
+        final = data if data["type"] == "result"
+        yield Event.from_hash(data) if block_given?
+      end
+      check_stream_result!(final, result)
+      Response.from_result(final)
+    end
+
+    # Start a multi-turn {Session} backed by this client.
+    #
+    # @param id [String, nil] an existing session id to resume
+    # @return [Session]
+    def session(id: nil)
+      Session.new(self, id: id)
+    end
+
+    private
+
+    def run_args(argv, env, prompt)
+      { argv: argv, env: env, cwd: @config.cwd, timeout: @config.timeout, stdin: prompt.to_s }
+    end
+
+    # Turn a one-shot {RunResult} into a {Response} or raise a typed error.
+    def interpret(result)
+      data = try_parse(result.stdout)
+      if data.is_a?(Hash) && data["type"] == "result"
+        raise_result_error!(data, result) if data["is_error"]
+        return Response.from_result(data)
+      end
+
+      raise failure_for(result) if failed?(result)
+
+      raise ParseError, "could not parse claude output as JSON: #{truncate(result.stdout)}"
+    end
+
+    def check_stream_result!(final, result)
+      raise_result_error!(final, result) if final && final["is_error"]
+      raise failure_for(result) if final.nil? && failed?(result)
+    end
+
+    def failed?(result)
+      status = result.exit_status
+      status.nil? || !status.zero?
+    end
+
+    def raise_result_error!(data, result)
+      detail = data["result"] || data["errors"]&.join("; ") || "subtype=#{data["subtype"]}"
+      raise AuthenticationError, auth_message(detail) if auth?(detail, result&.stderr)
+
+      raise ExecutionError.new(
+        "claude returned an error result: #{detail}",
+        status: result&.exit_status,
+        stderr: result&.stderr
+      )
+    end
+
+    def failure_for(result)
+      stderr = result.stderr.to_s
+      return AuthenticationError.new(auth_message(stderr.strip)) if auth?(stderr, result.stdout)
+
+      status = result.exit_status
+      ExecutionError.new(
+        "claude exited with status #{status || "signal"}: #{truncate(stderr)}",
+        status: status,
+        stderr: stderr
+      )
+    end
+
+    def auth?(*sources)
+      sources.compact.any? { |source| AUTH_PATTERNS.match?(source.to_s) }
+    end
+
+    def auth_message(detail)
+      base = "Claude authentication failed. Run `claude` and use `/login` to sign in with " \
+             "your Claude subscription (or set use_subscription = false to use ANTHROPIC_API_KEY)."
+      detail.nil? || detail.empty? ? base : "#{base}\n#{detail}"
+    end
+
+    def try_parse(string)
+      return nil if string.nil? || string.strip.empty?
+
+      JSON.parse(string)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def truncate(string, max = 500)
+      stripped = string.to_s.strip
+      stripped.length > max ? "#{stripped[0, max]}..." : stripped
+    end
+  end
+end

data/lib/ruby_claude/command.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # Pure translation of a {Configuration} plus per-call options into the argv
+  # array and child-environment overrides for the +claude+ CLI.
+  #
+  # Performs no I/O, which makes flag mapping trivial to unit-test. The prompt
+  # is intentionally *never* part of argv — it is written to the child's stdin
+  # by the {Runner} to avoid +ARG_MAX+ limits and shell-escaping concerns.
+  class Command
+    # @param config [Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Build the argv array and child-environment overrides.
+    #
+    # @param stream [Boolean] use stream-json output (also adds +--verbose+,
+    #   which the CLI requires for stream-json in print mode)
+    # @param resume [String, nil] a session id to resume via +--resume+
+    # @return [Array(Array<String>, Hash)] +[argv, env]+
+    def build(stream:, resume: nil)
+      argv = [@config.binary, "-p", "--output-format", stream ? "stream-json" : "json"]
+      argv << "--verbose" if stream
+      add_flag(argv, "--model", @config.model)
+      add_flag(argv, "--append-system-prompt", @config.append_system_prompt)
+      add_list(argv, "--allowedTools", @config.allowed_tools)
+      add_list(argv, "--disallowedTools", @config.disallowed_tools)
+      add_list(argv, "--add-dir", @config.add_dirs)
+      add_flag(argv, "--permission-mode", @config.permission_mode)
+      add_flag(argv, "--max-turns", @config.max_turns&.to_s)
+      add_flag(argv, "--resume", resume)
+      [argv, child_env]
+    end
+
+    # Environment overrides for the child process. In subscription mode,
+    # +ANTHROPIC_API_KEY+ is mapped to +nil+, which tells +Open3+/+spawn+ to
+    # remove it from the inherited environment so the CLI falls back to the
+    # logged-in subscription credentials.
+    #
+    # @return [Hash{String => String, nil}]
+    def child_env
+      return {} unless @config.use_subscription
+
+      { "ANTHROPIC_API_KEY" => nil }
+    end
+
+    private
+
+    # Append +flag value+ when +value+ is present.
+    def add_flag(argv, flag, value)
+      return if value.nil?
+
+      string = value.to_s
+      return if string.empty?
+
+      argv.push(flag, string)
+    end
+
+    # Append +flag item item ...+ (each list item as its own argv token, which
+    # matches the CLI's space-separated variadic options and preserves spaces
+    # inside permission-rule patterns such as +Bash(git log *)+).
+    def add_list(argv, flag, value)
+      items = Array(value).map(&:to_s).reject(&:empty?)
+      return if items.empty?
+
+      argv.push(flag, *items)
+    end
+  end
+end

data/lib/ruby_claude/configuration.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # Holds every tunable option with sane defaults.
+  #
+  # Used as the global default (via {RubyClaude.configure}) and as the basis
+  # for per-{Client} overrides through {#merge}. A configuration is only ever
+  # read while a query runs, never mutated, which keeps {Client} thread-safe.
+  class Configuration
+    # @return [String] executable name or path of the CLI
+    attr_accessor :binary
+
+    # @return [String, nil] model for +--model+ (nil uses the CLI default)
+    attr_accessor :model
+
+    # @return [String, nil] working directory for the subprocess
+    attr_accessor :cwd
+
+    # @return [Integer] seconds before the child process is killed
+    attr_accessor :timeout
+
+    # @return [Boolean] when true, strip +ANTHROPIC_API_KEY+ from the child env
+    attr_accessor :use_subscription
+
+    # @return [String, nil] text for +--append-system-prompt+
+    attr_accessor :append_system_prompt
+
+    # @return [Array<String>, String, nil] tools for +--allowedTools+
+    attr_accessor :allowed_tools
+
+    # @return [Array<String>, String, nil] tools for +--disallowedTools+
+    attr_accessor :disallowed_tools
+
+    # @return [Array<String>] directories for repeated +--add-dir+
+    attr_accessor :add_dirs
+
+    # @return [String, nil] mode for +--permission-mode+
+    attr_accessor :permission_mode
+
+    # @return [Integer, nil] limit for +--max-turns+
+    attr_accessor :max_turns
+
+    def initialize
+      @binary = "claude"
+      @model = nil
+      @cwd = Dir.pwd
+      @timeout = 300
+      @use_subscription = true
+      @append_system_prompt = nil
+      @allowed_tools = nil
+      @disallowed_tools = nil
+      @add_dirs = []
+      @permission_mode = nil
+      @max_turns = nil
+    end
+
+    # Return a copy with the given overrides applied. The receiver is left
+    # untouched, so the global configuration is never mutated by a {Client}.
+    #
+    # @param overrides [Hash{Symbol => Object}]
+    # @return [Configuration]
+    # @raise [ArgumentError] when an option is not recognized
+    def merge(overrides)
+      dup.tap do |copy|
+        overrides.each do |key, value|
+          setter = "#{key}="
+          raise ArgumentError, "unknown configuration option: #{key}" unless copy.respond_to?(setter)
+
+          copy.public_send(setter, value)
+        end
+      end
+    end
+
+    # @return [Hash{Symbol => Object}] a plain-hash view of the configuration
+    def to_h
+      {
+        binary: binary, model: model, cwd: cwd, timeout: timeout,
+        use_subscription: use_subscription, append_system_prompt: append_system_prompt,
+        allowed_tools: allowed_tools, disallowed_tools: disallowed_tools,
+        add_dirs: add_dirs, permission_mode: permission_mode, max_turns: max_turns
+      }
+    end
+
+    private
+
+    # Deep-copy the mutable array options so a {Client} can never mutate the
+    # array held by the global configuration.
+    def initialize_copy(source)
+      super
+      @add_dirs = source.add_dirs.dup if source.add_dirs.is_a?(Array)
+      @allowed_tools = source.allowed_tools.dup if source.allowed_tools.is_a?(Array)
+      @disallowed_tools = source.disallowed_tools.dup if source.disallowed_tools.is_a?(Array)
+    end
+  end
+end

data/lib/ruby_claude/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # Base class for every error raised by Ruby Claude.
+  class Error < StandardError; end
+
+  # Raised when the +claude+ binary cannot be found on PATH or executed.
+  #
+  # The message explains how to install Claude Code and reminds the user that
+  # they must run +claude+ and +/login+ at least once.
+  class BinaryNotFoundError < Error; end
+
+  # Raised when the CLI output or exit status indicates the user is not
+  # logged in or that authentication otherwise failed.
+  class AuthenticationError < Error; end
+
+  # Raised when the child process exceeds the configured timeout and the gem
+  # kills it.
+  class TimeoutError < Error; end
+
+  # Raised on a non-zero exit status, or on a result payload that reports
+  # +is_error: true+. Carries the exit status and captured stderr.
+  class ExecutionError < Error
+    # @return [Integer, nil] the child process exit status, when known
+    attr_reader :status
+
+    # @return [String, nil] captured standard error output, when available
+    attr_reader :stderr
+
+    # @param message [String, nil]
+    # @param status [Integer, nil]
+    # @param stderr [String, nil]
+    def initialize(message = nil, status: nil, stderr: nil)
+      @status = status
+      @stderr = stderr
+      super(message)
+    end
+  end
+
+  # Raised when the CLI output cannot be parsed as the expected JSON.
+  class ParseError < Error; end
+end

data/lib/ruby_claude/event.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # Immutable streaming event parsed from one line of +--output-format
+  # stream-json+ output. The {#type} mirrors the CLI's +type+ field as a
+  # Symbol (+:system+, +:assistant+, +:user+, +:result+, ...).
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] the event type
+  # @!attribute [r] text
+  #   @return [String, nil] text extracted from assistant/user/result payloads
+  # @!attribute [r] session_id
+  #   @return [String, nil] the session id, when present
+  # @!attribute [r] cost_usd
+  #   @return [Float, nil] total cost, present on the result event
+  # @!attribute [r] duration_ms
+  #   @return [Integer, nil] duration, present on the result event
+  # @!attribute [r] raw
+  #   @return [Hash] the full parsed line
+  Event = Data.define(:type, :text, :session_id, :cost_usd, :duration_ms, :raw) do
+    # Build an Event from one parsed NDJSON line.
+    #
+    # @param data [Hash, nil] the parsed line
+    # @return [Event]
+    def self.from_hash(data)
+      data ||= {}
+      new(
+        type: (data["type"] || "unknown").to_sym,
+        text: extract_text(data),
+        session_id: data["session_id"],
+        cost_usd: data["total_cost_usd"],
+        duration_ms: data["duration_ms"],
+        raw: data
+      )
+    end
+
+    # Pull human-readable text out of a parsed line, if any.
+    #
+    # @param data [Hash]
+    # @return [String, nil]
+    def self.extract_text(data)
+      case data["type"]
+      when "assistant", "user"
+        message = data["message"] || data
+        text_from_content(message["content"])
+      when "result"
+        data["result"]
+      end
+    end
+
+    # Join the text from a content array (or pass a bare string through).
+    #
+    # @param content [String, Array, nil]
+    # @return [String, nil]
+    def self.text_from_content(content)
+      return content if content.is_a?(String)
+      return nil unless content.is_a?(Array)
+
+      texts = content
+              .select { |block| block.is_a?(Hash) && block["type"] == "text" }
+              .filter_map { |block| block["text"] }
+      texts.empty? ? nil : texts.join
+    end
+
+    # @return [Boolean] whether this is the final result event
+    def result? = type == :result
+
+    # @return [Boolean] whether this is an assistant message event
+    def assistant? = type == :assistant
+
+    # @return [Boolean] whether this is a system event
+    def system? = type == :system
+
+    # @return [Boolean] whether this is a user message event
+    def user? = type == :user
+  end
+end

data/lib/ruby_claude/response.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # Immutable value object describing the final result of a query.
+  #
+  # Built from the CLI's +--output-format json+ result object (or from the
+  # final +result+ line of a stream). Missing keys map to sensible defaults
+  # rather than raising.
+  #
+  # @!attribute [r] text
+  #   @return [String] the assistant's final text result
+  # @!attribute [r] session_id
+  #   @return [String, nil] the session id of this conversation
+  # @!attribute [r] cost_usd
+  #   @return [Float] total cost in USD (often +0.0+ on a subscription)
+  # @!attribute [r] usage
+  #   @return [Hash] token usage counts, when present
+  # @!attribute [r] num_turns
+  #   @return [Integer] number of agentic turns
+  # @!attribute [r] duration_ms
+  #   @return [Integer] wall-clock duration in milliseconds
+  # @!attribute [r] error
+  #   @return [Boolean] whether the CLI reported an error
+  # @!attribute [r] raw
+  #   @return [Hash] the full parsed result object
+  Response = Data.define(:text, :session_id, :cost_usd, :usage,
+                         :num_turns, :duration_ms, :error, :raw) do
+    # Build a Response from a parsed CLI result hash.
+    #
+    # @param data [Hash, nil] the parsed result object
+    # @return [Response]
+    def self.from_result(data)
+      data ||= {}
+      new(
+        text: data["result"] || "",
+        session_id: data["session_id"],
+        cost_usd: (data["total_cost_usd"] || data["cost_usd"] || 0.0).to_f,
+        usage: data["usage"] || {},
+        num_turns: (data["num_turns"] || 0).to_i,
+        duration_ms: (data["duration_ms"] || 0).to_i,
+        error: data.fetch("is_error", false) ? true : false,
+        raw: data
+      )
+    end
+
+    # @return [Boolean] whether the result represents an error
+    def error? = !!error
+
+    # @return [Boolean] whether the result was successful
+    def success? = !error?
+
+    # Returns the assistant text, so +puts response+ prints the answer.
+    #
+    # @return [String]
+    def to_s = text
+  end
+end

data/lib/ruby_claude/runner.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module RubyClaude
+  # The captured result of a completed subprocess run.
+  #
+  # @!attribute [r] stdout
+  #   @return [String, nil] captured stdout (nil when streaming)
+  # @!attribute [r] stderr
+  #   @return [String] captured stderr
+  # @!attribute [r] exit_status
+  #   @return [Integer, nil] exit code, or nil if the process was signalled
+  RunResult = Data.define(:stdout, :stderr, :exit_status)
+
+  # Owns every subprocess concern: spawning +claude+ via +Open3+, writing the
+  # prompt to stdin, enforcing the timeout by killing the child, capturing
+  # output, and translating spawn failures into {BinaryNotFoundError}.
+  #
+  # The runner is stateless, so a single instance is safe to share across
+  # threads. The {Client} accepts an injected runner so tests never spawn.
+  class Runner
+    # Seconds to wait after +SIGTERM+ before escalating to +SIGKILL+.
+    KILL_GRACE = 2
+
+    # Run the command to completion and capture its output.
+    #
+    # @param argv [Array<String>] the command and its arguments
+    # @param env [Hash] environment overrides (nil values unset a variable)
+    # @param cwd [String, nil] working directory
+    # @param timeout [Numeric] seconds before the child is killed
+    # @param stdin [String, nil] data to write to the child's stdin
+    # @return [RunResult]
+    # @raise [TimeoutError] if the child exceeds +timeout+
+    # @raise [BinaryNotFoundError] if the binary cannot be executed
+    def run(argv:, env:, cwd:, timeout:, stdin: nil)
+      spawn(argv, env, cwd) do |stdin_io, stdout_io, stderr_io, wait_thr|
+        out_reader = Thread.new { stdout_io.read }
+        err_reader = Thread.new { stderr_io.read }
+        write_stdin(stdin_io, stdin)
+
+        if wait_thr.join(timeout).nil?
+          terminate(wait_thr)
+          out_reader.kill
+          err_reader.kill
+          raise TimeoutError, "claude did not finish within #{timeout}s; the process was killed"
+        end
+
+        RunResult.new(
+          stdout: out_reader.value,
+          stderr: err_reader.value,
+          exit_status: wait_thr.value.exitstatus
+        )
+      end
+    end
+
+    # Run the command and yield each non-empty stdout line as it arrives.
+    #
+    # @param (see #run)
+    # @yieldparam line [String] one chomped, non-empty stdout line
+    # @return [RunResult] with +stdout+ nil (it was streamed, not captured)
+    # @raise [TimeoutError] if the child exceeds +timeout+
+    # @raise [BinaryNotFoundError] if the binary cannot be executed
+    def stream(argv:, env:, cwd:, timeout:, stdin: nil)
+      spawn(argv, env, cwd) do |stdin_io, stdout_io, stderr_io, wait_thr|
+        err_reader = Thread.new { stderr_io.read }
+        # Write stdin on its own thread so a prompt larger than the OS pipe
+        # buffer can't deadlock against stdout we haven't started reading yet.
+        writer = Thread.new { write_stdin(stdin_io, stdin) }
+        timed_out = false
+        watchdog = Thread.new do
+          sleep(timeout)
+          timed_out = true
+          terminate(wait_thr)
+        end
+
+        begin
+          stdout_io.each_line do |line|
+            chomped = line.chomp
+            yield chomped unless chomped.empty?
+          end
+        ensure
+          watchdog.kill
+          writer.join
+        end
+
+        raise TimeoutError, "claude streaming exceeded #{timeout}s; the process was killed" if timed_out
+
+        RunResult.new(stdout: nil, stderr: err_reader.value, exit_status: wait_thr.value.exitstatus)
+      end
+    end
+
+    private
+
+    def spawn(argv, env, cwd, &block)
+      validate_cwd!(cwd)
+      options = {}
+      options[:chdir] = cwd if cwd
+      Open3.popen3(env || {}, *argv, **options, &block)
+    rescue Errno::ENOENT
+      raise BinaryNotFoundError, binary_not_found_message(argv.first)
+    end
+
+    def validate_cwd!(cwd)
+      return if cwd.nil? || File.directory?(cwd)
+
+      raise Error, "working directory does not exist: #{cwd}"
+    end
+
+    def write_stdin(stdin_io, data)
+      stdin_io.write(data) if data
+    rescue Errno::EPIPE
+      # The child exited before reading stdin; the failure surfaces via status.
+    ensure
+      stdin_io.close unless stdin_io.closed?
+    end
+
+    # Send +SIGTERM+, wait up to {KILL_GRACE} for the child to exit, then
+    # escalate to +SIGKILL+ if it ignored the polite signal.
+    #
+    # This runs synchronously while holding +wait_thr+: the child's PID can't
+    # be reaped (and therefore can't be recycled by the OS) until we let go,
+    # so the +SIGKILL+ can never land on an unrelated, reused PID.
+    def terminate(wait_thr)
+      Process.kill("TERM", wait_thr.pid)
+      return if wait_thr.join(KILL_GRACE)
+
+      Process.kill("KILL", wait_thr.pid)
+    rescue Errno::ESRCH
+      # The process already exited.
+    end
+
+    def binary_not_found_message(binary)
+      "could not run #{binary.inspect}: is Claude Code installed and on your PATH?\n" \
+        "Install it with `npm install -g @anthropic-ai/claude-code`, then run `claude` " \
+        "and `/login` once to sign in with your Claude subscription."
+    end
+  end
+end

data/lib/ruby_claude/session.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # A multi-turn conversation.
+  #
+  # The first {#query} captures the +session_id+ from the reply; subsequent
+  # queries transparently pass +--resume <id>+ so the conversation continues.
+  class Session
+    # @return [String, nil] the session id being resumed (nil until the first
+    #   reply, unless one was supplied to {Client#session})
+    attr_reader :id
+
+    # @param client [Client] the client used to run each turn
+    # @param id [String, nil] an existing session id to resume from the start
+    def initialize(client, id: nil)
+      @client = client
+      @id = id
+      @mutex = Mutex.new
+    end
+
+    # Ask a question within this conversation, resuming the captured session.
+    #
+    # @param prompt [String]
+    # @return [Response]
+    def query(prompt)
+      @mutex.synchronize do
+        response = @client.query(prompt, resume: @id)
+        @id = response.session_id || @id
+        response
+      end
+    end
+    alias ask query
+  end
+end

data/lib/ruby_claude/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RubyClaude
+  # The released version of the gem, following Semantic Versioning.
+  VERSION = "0.0.0"
+end

data/lib/ruby_claude.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "ruby_claude/version"
+require_relative "ruby_claude/errors"
+require_relative "ruby_claude/configuration"
+require_relative "ruby_claude/response"
+require_relative "ruby_claude/event"
+require_relative "ruby_claude/command"
+require_relative "ruby_claude/runner"
+require_relative "ruby_claude/session"
+require_relative "ruby_claude/client"
+
+# Ruby Claude — a subscription-authenticated Ruby SDK that talks to Claude by
+# shelling out to the Claude Code CLI (+claude -p+) in headless mode.
+#
+# It is an unofficial, community wrapper around a supported headless feature.
+# By default it strips +ANTHROPIC_API_KEY+ from the child environment so calls
+# draw on the logged-in Pro/Max subscription rather than API billing.
+#
+# @example One-shot
+#   puts RubyClaude.query("Summarize lib/foo.rb in two sentences")
+#
+# @example A configured client
+#   client = RubyClaude::Client.new(model: "claude-sonnet-4-6", timeout: 180)
+#   client.query("What does this project do?").text
+module RubyClaude
+  class << self
+    # The global configuration used by {RubyClaude.query} and as the default
+    # for new {Client} instances.
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the global defaults.
+    #
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    def configure
+      yield configuration if block_given?
+      @default_client = nil # rebuild with the new configuration on next use
+      configuration
+    end
+
+    # Reset all global state. Mainly useful in tests.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+      @default_client = nil
+    end
+
+    # One-shot convenience that delegates to a memoized default {Client}.
+    #
+    # @param prompt [String]
+    # @param options [Hash] forwarded to {Client#query} (e.g. +resume:+)
+    # @return [Response]
+    def query(prompt, **options)
+      default_client.query(prompt, **options)
+    end
+
+    # The memoized default {Client}, rebuilt whenever {configure} is called.
+    #
+    # @return [Client]
+    def default_client
+      @default_client ||= Client.new
+    end
+  end
+end

data/ruby_claude.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/ruby_claude/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ruby_claude"
+  spec.version = RubyClaude::VERSION
+  spec.authors = ["Kaíque Kandy Koga"]
+  spec.email = ["kaique.koga@javln.com"]
+
+  spec.summary = "Subscription-authenticated Ruby SDK for Claude via the Claude Code CLI."
+  spec.description = <<~DESC
+    Ruby Claude is a small, dependency-light, idiomatic Ruby wrapper around the
+    Claude Code CLI in headless mode (claude -p). It lets Ruby programs talk to
+    Claude using a Claude Pro/Max subscription for authentication instead of an
+    Anthropic API key: by default it strips ANTHROPIC_API_KEY from the child
+    process environment so the CLI falls back to the logged-in subscription
+    credentials. Unofficial; uses a supported headless feature within the
+    subscription's rate limits.
+  DESC
+  spec.homepage = "https://github.com/kaiquekandykoga/ruby_claude"
+  spec.license = "BSD-3-Clause"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").select do |path|
+      path.start_with?("lib/") ||
+        %w[README.md LICENSE ruby_claude.gemspec].include?(path)
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "test-unit", "~> 3.6"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: ruby_claude
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Kaíque Kandy Koga
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  Ruby Claude is a small, dependency-light, idiomatic Ruby wrapper around the
+  Claude Code CLI in headless mode (claude -p). It lets Ruby programs talk to
+  Claude using a Claude Pro/Max subscription for authentication instead of an
+  Anthropic API key: by default it strips ANTHROPIC_API_KEY from the child
+  process environment so the CLI falls back to the logged-in subscription
+  credentials. Unofficial; uses a supported headless feature within the
+  subscription's rate limits.
+email:
+- kaique.koga@javln.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_claude.rb
+- lib/ruby_claude/client.rb
+- lib/ruby_claude/command.rb
+- lib/ruby_claude/configuration.rb
+- lib/ruby_claude/errors.rb
+- lib/ruby_claude/event.rb
+- lib/ruby_claude/response.rb
+- lib/ruby_claude/runner.rb
+- lib/ruby_claude/session.rb
+- lib/ruby_claude/version.rb
+- ruby_claude.gemspec
+homepage: https://github.com/kaiquekandykoga/ruby_claude
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/kaiquekandykoga/ruby_claude
+  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.10
+specification_version: 4
+summary: Subscription-authenticated Ruby SDK for Claude via the Claude Code CLI.
+test_files: []