agentsclimarketplace
Sign in

Claude agent ruby

Skill ya-luotao/claude-agent-sdk-ruby/plugins/claude-agent-ruby/skills/claude-agent-ruby

Implement or modify Ruby code using the claude-agent-sdk gem. Covers query() one-shot calls, Client-based interactive sessions, streaming input, all 27 hook events, permission callbacks, SDK MCP servers, structured output, bare mode, full sandbox settings (network + filesystem), all 26 message types (including tool_progress, auth_status, prompt_suggestion, hook lifecycle, compact_boundary, session_state_changed, mirror_error, task_updated), session browsing/mutations, SessionStore transcript mirroring to external storage (S3/Redis/Postgres) with store-backed resume, subagents, file checkpointing, Rails integration, and custom transports. Use this skill whenever the user mentions claude-agent-sdk, Claude Agent Ruby, building AI agents in Ruby, or integrating Claude Code into a Ruby/Rails application.From its SKILL.md

Install
npx -y skills add ya-luotao/claude-agent-sdk-ruby --skill claude-agent-ruby

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

10.8 KB, as published. Nobody here has run it

Claude Agent Ruby SDK

Overview

Use this skill to build or refactor Ruby integrations with Claude Code via claude-agent-sdk, favoring the gem's README, the docs/ topic subpages, and lib/ types for exact APIs.

Decision Guide

  • Choose ClaudeAgentSDK.query for one-shot queries or streaming input. Internally uses the control protocol (streaming mode).
  • Choose ClaudeAgentSDK::Client for multi-turn sessions, hooks, permission callbacks, MCP server control, or dynamic model switching; wrap in Async do ... end.wait.
  • Choose SDK MCP servers (create_tool, create_sdk_mcp_server) for in-process tools; choose external MCP configs for subprocess/HTTP servers.
  • Choose ClaudeAgentSDK.list_sessions / ClaudeAgentSDK.get_session_messages for browsing previous session transcripts (pure filesystem, no CLI needed).

Implementation Checklist

  • Confirm prerequisites (Ruby 3.2+, Node.js, Claude Code CLI).
  • Build ClaudeAgentSDK::ClaudeAgentOptions and pass it to query or Client.new.
  • Handle messages by type — the SDK has 26 typed message classes:
    • Core: AssistantMessage, UserMessage, ResultMessage, StreamEvent, RateLimitEvent
    • System init: InitMessage (session start / /clear — carries uuid, session_id, tools, model, cwd, agents, betas, claude_code_version, permission_mode, slash_commands, output_style, skills, plugins, fast_mode_state)
    • Compaction: CompactBoundaryMessage (uuid, session_id, compact_metadata with pre_tokens, trigger, preserved_segment)
    • Status: StatusMessage (compacting status, permission mode changes)
    • Tasks: TaskStartedMessage (+ workflow_name, prompt), TaskProgressMessage (+ summary), TaskNotificationMessage, TaskUpdatedMessage (lifecycle state change; status derived from patch['status'], task_id always a String — clear active-task tracking when status is in TERMINAL_TASK_STATUSES)
    • Hooks: HookStartedMessage, HookProgressMessage, HookResponseMessage
    • Sessions: SessionStateChangedMessage (idle/running/requires_action)
    • Tools: ToolProgressMessage (elapsed_time_seconds per tool), ToolUseSummaryMessage
    • Auth: AuthStatusMessage (isAuthenticating, output, error)
    • Files: FilesPersistedMessage (files, failed, processed_at)
    • API: APIRetryMessage (attempt, max_retries, retry_delay_ms, error_status)
    • Session store: MirrorErrorMessage (a SessionStore append failed terminally — timeouts immediately, other failures after up to three attempts; session continues; local transcript stays durable)
    • Other: LocalCommandOutputMessage, ElicitationCompleteMessage, PromptSuggestionMessage
    • Unknown message types return nil (forward-compatible)
  • Handle content blocks: TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock, UnknownBlock
  • AssistantMessage carries: content, model, parent_tool_use_id, error, usage, message_id (API message ID), stop_reason, session_id, uuid (transcript UUID)
  • ResultMessage carries: stop_reason, model_usage (per-model breakdown), permission_denials, errors (on error subtypes), uuid, fast_mode_state, terminal_reason (why the query loop ended; aborted_streaming/aborted_tools mean interrupted)
  • Use output_format for JSON schema structured output
  • Use thinking: with ThinkingConfigAdaptive, ThinkingConfigEnabled(budget_tokens:), or ThinkingConfigDisabled. Use effort: for effort level.

Hooks (27 events)

All hook events: PreToolUse, PostToolUse, PostToolUseFailure, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop, PreCompact, PostCompact, PermissionRequest, PermissionDenied, Setup, TeammateIdle, TaskCreated, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded, CwdChanged, FileChanged.

Define hooks as Ruby procs/lambdas. Do not combine can_use_tool with permission_prompt_tool_name. Tool-lifecycle hooks carry agent_id and agent_type when firing inside subagents. StopHookInput and SubagentStopHookInput include last_assistant_message.

Hook-specific outputs with to_h: PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, NotificationHookSpecificOutput, SubagentStartHookSpecificOutput, SessionStartHookSpecificOutput, SetupHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, CwdChangedHookSpecificOutput, FileChangedHookSpecificOutput.

Bare Mode

Use bare: true for minimal startup — skips hooks, LSP, plugin sync, CLAUDE.md auto-discovery, auto-memory, keychain reads. Explicitly provide context via system_prompt, add_dirs, setting_sources, allowed_tools.

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  bare: true,
  system_prompt: 'You are a code reviewer.',
  permission_mode: 'bypassPermissions'
)

Sandbox Settings (full CC parity)

  • SandboxSettings: enabled, fail_if_unavailable, auto_allow_bash_if_sandboxed, excluded_commands, allow_unsandboxed_commands, network, filesystem, ignore_violations (Hash), enable_weaker_nested_sandbox, enable_weaker_network_isolation, ripgrep
  • SandboxNetworkConfig: allowed_domains, denied_domains, allow_managed_domains_only, allow_unix_sockets, allow_all_unix_sockets, allow_local_binding, allow_mach_lookup, http_proxy_port, socks_proxy_port
  • SandboxFilesystemConfig: allow_write, deny_write, deny_read, allow_read, allow_managed_read_paths_only

SDK MCP Tools

  • Include mcp__<server>__<tool> in allowed_tools
  • Use annotations: on create_tool for MCP tool annotations
  • Use meta: on create_tool for _meta field forwarding (e.g., { 'anthropic/maxResultSizeChars' => 100000 } to prevent truncation of large results)
  • If annotations[:maxResultSizeChars] is set, _meta is auto-populated
  • Both symbol-keyed and string-keyed input_schema hashes are accepted

Session Management

  • resume, session_id, fork_session option for session handling
  • ClaudeAgentSDK.delete_session(session_id:, directory:) — hard-deletes a session
  • ClaudeAgentSDK.fork_session(session_id:, directory:, up_to_message_id:, title:) → ForkSessionResult — filesystem fork with UUID remapping
  • ClaudeAgentSDK.list_sessions(directory:, limit:, offset:, include_worktrees:) — supports offset for pagination
  • ClaudeAgentSDK.list_subagents(session_id:, directory:) / ClaudeAgentSDK.get_subagent_messages(session_id:, agent_id:, directory:, limit:, offset:) — local-disk subagent transcript readers (disk counterparts of the *_from_store pair)
  • SessionStore mirroring: ClaudeAgentOptions.new(session_store: store) mirrors transcripts to external storage (subclass ClaudeAgentSDK::SessionStore — only #append/#load required; InMemorySessionStore for tests; S3/Redis/Postgres reference adapters in examples/session_stores/). session_store_flush: 'eager' flushes per frame; load_timeout_ms bounds resume store calls.
  • Resume from store: pair session_store with resume:/continue_conversation — no local JSONL needed. Note: runs the CLI against a bare temp CLAUDE_CONFIG_DIR (user-scope settings.json/agents/skills invisible; project .claude/* still applies).
  • Store-backed helpers: list_sessions_from_store, get_session_info_from_store, get_session_messages_from_store, list_subagents_from_store, get_subagent_messages_from_store, rename_session_via_store, tag_session_via_store, delete_session_via_store, fork_session_via_store, import_session_to_store (migrate disk → store). Store reads default directory: to cwd. Validate adapters with ClaudeAgentSDK::Testing.run_session_store_conformance.
  • Client#get_context_usage — context window breakdown (tokens by category, model, MCP tools, etc.)
  • Client#reconnect_mcp_server(name), Client#toggle_mcp_server(name, enabled), Client#stop_task(task_id) for live control
  • Client#rewind_files(uuid) with enable_file_checkpointing: true
  • McpStatusResponse.parse(client.get_mcp_status) for typed MCP status

Where To Look For Exact Details

  • Locate the gem: bundle show claude-agent-sdk
  • Read <gem_path>/README.md for the overview, install, and minimal API examples
  • Read <gem_path>/docs/*.md for topic subpages — client.md (bidirectional + custom transports), mcp-servers.md (SDK MCP tools/resources/prompts), hooks-and-permissions.md (27 hook events + permission callbacks), configuration.md (structured output, thinking, budget, sandbox, bare mode, file checkpointing), sessions.md (list/read/rename/tag/fork/resume + SessionStore mirroring/store-backed helpers), observability.md (OTel + Langfuse), rails.md (ActionCable, jobs, initializers), types.md (message/content-block/configuration types), errors.md (error hierarchy + timeout)
  • Inspect <gem_path>/lib/claude_agent_sdk/types.rb for all types
  • Inspect <gem_path>/lib/claude_agent_sdk/message_parser.rb for message parsing
  • Inspect <gem_path>/lib/claude_agent_sdk/sessions.rb for session browsing
  • Inspect <gem_path>/lib/claude_agent_sdk/errors.rb for error classes
  • Use references/usage-map.md for a documentation map (README + docs/) and minimal skeletons

Resources

references/

  • Read references/usage-map.md to map tasks to README and docs/ subpages, gem paths, and minimal skeletons.
  • Read references/message-handling.md to extract text/tool blocks, build streaming input, use Client runtime APIs, and capture UUIDs for rewind.
  • Read references/options.md to configure ClaudeAgentOptions (defaults, tools, permissions, skills, output formats, budgets, sandbox, sessions, agents, custom transports), and to browse/mutate sessions.
  • Read references/mcp-servers.md to define in-process SDK MCP tools/resources/prompts, configure external MCP servers, or manage MCP servers at runtime.
  • Read references/rails.md for initializers, background jobs, ActionCable streaming, and session resumption patterns.
  • Read references/troubleshooting.md for common setup/runtime errors and timeout tuning.

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.