ruby_claude 0.0.0 → 0.0.1

checksums.yaml

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

data/README.md

@@ -1,59 +1,36 @@
 # 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.
+A tiny, zero-dependency Ruby SDK for Claude that shells out to the **Claude Code
+CLI** (`claude -p`) and authenticates with your **Claude Pro/Max subscription**
+instead of an API key.
 
-## Prerequisites
+> **Unofficial** community gem — not affiliated with Anthropic. It uses the
+> supported `claude -p` headless mode within your subscription's rate limits; no
+> OAuth-token handling and no direct API calls.
 
-This gem drives the `claude` binary; it does not install or replace it.
+## Subscription, not API key
 
-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"
-   ```
+`claude -p` uses whatever the CLI is logged in with — if that's a subscription,
+calls draw on it with no API billing. Ruby Claude **strips `ANTHROPIC_API_KEY`
+from the child environment by default** so the CLI can't silently fall back to
+API billing; set `use_subscription = false` to opt back in.
 
-## Installation
+## Prerequisites
 
-Add it to your `Gemfile`:
+`claude` must be installed and logged in (this gem drives it, it doesn't replace it):
 
-```ruby
-gem "ruby_claude"
+```bash
+npm install -g @anthropic-ai/claude-code
+claude        # run /login once and choose the subscription option
 ```
 
-Or install directly:
+## Install
 
-```bash
-gem install ruby_claude
+```ruby
+gem "ruby_claude"   # in your Gemfile
 ```
 
-Ruby **3.2+** is required (the value objects use `Data.define`). The gem has
-**zero runtime dependencies** — it only uses the standard library.
+…or `gem install ruby_claude`. Requires Ruby 3.2+; zero runtime dependencies.
 
 ## Quickstart
 
@@ -63,167 +40,76 @@ 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
-)
+# A configured client
+client = RubyClaude::Client.new(model: "claude-sonnet-4-6",
+                                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
+res.text         # final text (Response#to_s returns it too, so `puts res` works)
+res.session_id   # String
+res.cost_usd     # Float (often 0.0 on a subscription)
+res.usage        # Hash   — also: res.num_turns, res.duration_ms, res.error?, res.raw
 
-`#stream` yields typed events as they arrive and returns the final `Response`.
-
-```ruby
+# Streaming — yields typed events, returns the final Response
 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
+  print event.text if event.type == :assistant
 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.
+# Multi-turn session — resumes the underlying session_id automatically
+chat = client.session
+chat.query("My favorite number is 7.")
+puts chat.query("What's my favorite number?")   # => "...7..."
 
-### 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
+# Global defaults for RubyClaude.query and new clients
+RubyClaude.configure { |c| c.model = "claude-sonnet-4-6"; c.timeout = 300 }
 ```
 
-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
-```
+A streaming `Event#type` is `:system`, `:assistant`, `:user`, or `:result`. Use
+`#query` (alias `#ask`) — there is intentionally no `#send`.
 
-These become the defaults for `RubyClaude.query` and for new `Client`
-instances. Per-client options passed to `Client.new(**opts)` override them.
+## Configuration
 
-> **Note:** there is intentionally no `#send` method (it would shadow
-> `Object#send`). Use `#query`, or its alias `#ask`.
+`Client.new(**opts)` overrides per instance; `RubyClaude.configure` sets globals.
 
-## 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.
+| Option | Default | Maps to |
+|--------|---------|---------|
+| `binary` | `"claude"` | executable name/path |
+| `model` | `nil` | `--model` |
+| `cwd` | `Dir.pwd` | subprocess working directory |
+| `timeout` | `300` | seconds before the child is killed |
+| `use_subscription` | `true` | strip `ANTHROPIC_API_KEY` from the child env |
+| `append_system_prompt` | `nil` | `--append-system-prompt` |
+| `allowed_tools` / `disallowed_tools` | `nil` | `--allowedTools` / `--disallowedTools` |
+| `add_dirs` | `[]` | `--add-dir` |
+| `permission_mode` | `nil` | `--permission-mode` |
+| `max_turns` | `nil` | `--max-turns` |
 
 ## 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
-```
+All subclass `RubyClaude::Error`: `BinaryNotFoundError` (no `claude` on PATH),
+`AuthenticationError` (not logged in), `TimeoutError`, `ExecutionError` (non-zero
+exit or an `is_error` result; carries `#status`/`#stderr`), and `ParseError`.
 
 ## 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.
+`Command` builds the argv + child env (pure, no I/O); `Runner` spawns `claude`
+via `Open3` (array form — no shell; prompt on stdin), enforces the timeout, and
+parses output; `Client` builds `Response`/`Event`; `Session` resumes via
+`--resume`. The runner is stateless per call, so a `Client` is safe to share
+across 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
+bundle exec rake        # tests + lint (hermetic — never spawns the real claude)
+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.)
+Contributing or tracking upstream SDK changes? See
+[`doc/DEVELOPMENT.md`](doc/DEVELOPMENT.md).
 
 ## Building and publishing the gem
 
@@ -233,7 +119,7 @@ Before a release, bump it following [SemVer](https://semver.org).
 ### Build locally
 
 ```bash
-gem build ruby_claude.gemspec        # => ruby_claude-<version>.gem
+gem build ruby_claude.gemspec             # => ruby_claude-<version>.gem
 gem install ./ruby_claude-<version>.gem   # try the built gem locally
 ```
 
@@ -270,9 +156,6 @@ rake install    # build and install locally
    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):

data/lib/ruby_claude/version.rb

@@ -2,5 +2,5 @@
 
 module RubyClaude
   # The released version of the gem, following Semantic Versioning.
-  VERSION = "0.0.0"
+  VERSION = "0.0.1"
 end

data/ruby_claude.gemspec

@@ -6,7 +6,7 @@ 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.email = ["kaiquekandykoga@gmail.com"]
 
   spec.summary = "Subscription-authenticated Ruby SDK for Claude via the Claude Code CLI."
   spec.description = <<~DESC

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_claude
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Kaíque Kandy Koga
@@ -74,7 +74,7 @@ description: |
   credentials. Unofficial; uses a supported headless feature within the
   subscription's rate limits.
 email:
-- kaique.koga@javln.com
+- kaiquekandykoga@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []