Ruby API Reference

Reference surface for the Ruby SDK. These APIs wrap the Autohand CLI JSON-RPC runtime while keeping host-language lifecycle and event handling idiomatic.

Source: autohandai/code-agent-sdk-ruby/docs/API_REFERENCE.md.

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

`AutohandSDK.configure`

Configuration sets the working directory, CLI binary path, debug output, request timeout, model override, skills, system prompt additions, and execution-mode flags.

ruby

AutohandSDK.configure do |config|
  config.cli_path = "/usr/local/bin/autohand"
  config.env_vars = { "AUTOHAND_NO_BANNER" => "1" }
end

`AutohandSDK::Client`

Use the low-level wrapper when you need direct JSON-RPC control.

  • .open(config = nil, **options) { |client| ... }
  • #start / #stop / #close
  • #stream_prompt(message_or_params, **options)
  • #prompt(message_or_params, **options)
  • #abort(reason: nil)
  • #permission_response
  • #set_permission_mode(mode)
  • #set_plan_mode(enabled)
  • #get_state
  • #get_messages

`AutohandSDK::Agent`

The high-level agent API is the best fit for product code that sends prompts, streams events, and waits for final results.

ruby

agent = AutohandSDK::Agent.create(cwd: ".")
run = agent.send("Review the public API")
result = run.wait
agent.close
  • .create(config = nil, instructions: nil, **options)
  • #send(input, **options)
  • #run(input, **options)
  • #run_json(input, schema_name: nil, schema: nil, output_instructions: nil, validate: nil, **options)
  • #stream(input, **options)

Run

  • #stream returns an event enumerator
  • #wait returns the final result hash
  • #json(validate: nil) parses the final text as JSON
  • #abort aborts the active run

CLI Runtime Control

The typed runtime-control surface is available on AutohandSDK::Client and its RPC client.

  • Conversation and handoff: reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff
  • Auto-mode: start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log
  • Approvals and sessions: acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes, get_session_history, get_session_details, attach_session
  • Integrations and context: set_yolo_mode, register_vscode_mcp_tools, complete_mcp_invocation, recommend_project_learning, update_project_learning, generate_project_skill, get_tools_registry, set_context_compaction

See Control the CLI runtime for behavior, safety contracts, and the equivalent names in every CLI-backed SDK.

SDK events

All CLI-backed SDKs expose the same runtime event names, with language-specific wrappers or helper methods around the raw JSON payload.

  • agent_start
  • turn_start
  • message_update
  • message_end
  • tool_start
  • tool_update
  • tool_end
  • permission_request
  • automode_iteration, automode_complete, automode_error
  • error

See Hooks and events for the complete normalized event contract.

Structured JSON

Use the JSON helpers when the host application needs typed output from the final assistant response.

ruby

risk = agent.run_json(
  "Assess publish readiness",
  schema_name: "ReleaseRisk",
  schema: { summary: "string" }
)

puts risk.fetch("summary")