Ruby SDK

The Ruby gem starts the Autohand Code CLI in RPC mode and gives Ruby apps streaming events, run lifecycle helpers, permissions, skills, sessions, hooks, and Rails-friendly configuration.

Repository: autohandai/code-agent-sdk-ruby. This SDK is in beta while the Agent SDK APIs stabilize. Pin commits or package versions in production.

Requirements

  • Ruby 3.2 or newer.
  • Bundler.
  • Autohand Code CLI installed through `bundle exec autohand-sdk install-cli` or supplied with `cli_path:`.

Install

Gemfile

gem "autohand_sdk", git: "https://github.com/autohandai/code-agent-sdk-ruby"

CLI

bundle install
bundle exec autohand-sdk install-cli
bundle exec autohand-sdk doctor

Run your first agent

Start with the high-level agent API when you want the SDK to own the run lifecycle and final result collection.

main.rb

require "autohand_sdk"

AutohandSDK::Agent.open(
  cwd: ".",
  instructions: "Review code with staff-level Ruby judgement.",
  permission_mode: "interactive"
) do |agent|
  run = agent.send("List the main source files and tell me what looks risky.")

  run.stream.each do |event|
    print event["delta"] if event["type"] == "message_update"
  end

  result = run.wait
  puts result.fetch(:text)
end

API shape

  • `AutohandSDK::Agent` and `Run` for host application code.
  • `AutohandSDK::Client` for direct session control.
  • Ruby enumerators for streaming message, tool, permission, and error events.
  • Optional Railtie support without making Rails a runtime dependency.

Rails configuration

When Rails is loaded, configure the SDK in an initializer and keep CLI path and environment overrides explicit.

initializer

AutohandSDK.configure do |config|
  config.cli_path = Rails.application.credentials.dig(:autohand, :cli_path)
  config.env_vars = { "AUTOHAND_NO_BANNER" => "1" }
end

AutohandSDK::Client.open(cwd: Rails.root.to_s, permission_mode: "interactive") do |sdk|
  sdk.stream_prompt("Review app/models/user.rb").each do |event|
    Rails.logger.info(event.inspect)
  end
end

Next steps