Codex SDK for Ruby (Unofficial)

gem 'codex-sdk'

require 'codex_sdk'

# Create a Codex instance
codex = CodexSdk.new(api_key: ENV['CODEX_API_KEY'])

# Start a new conversation thread
thread = codex.start_thread(
  working_directory: '/path/to/your/project'
)

# Run a turn and get the response
result = thread.run("Diagnose the test failure in my project")

puts result[:final_response]
# => "I found the issue in your test suite..."

puts "Items: #{result[:items].size}"
puts "Usage: #{result[:usage]}"

# Create a Codex client
codex = CodexSdk.new

# Start a thread
thread = codex.start_thread

# Send a message
result = thread.run("What is the purpose of this codebase?")
puts result[:final_response]

thread = codex.start_thread

thread.run_streamed("Fix the bug in user authentication").each do |event|
  case event['type']
  when 'item.started'
    puts "Started: #{event['item']['type']}"
  when 'item.completed'
    item = event['item']
    puts "Completed: #{item['type']}"
    puts "Content: #{item['text']}" if item['text']
  when 'turn.completed'
    puts "Turn completed. Usage: #{event['usage']}"
  end
end

thread = codex.start_thread

# First turn
result1 = thread.run("What files handle user authentication?")
puts result1[:final_response]

# Second turn - maintains context
result2 = thread.run("Add two-factor authentication to those files")
puts result2[:final_response]

# Save thread ID for later
thread_id = thread.id

# Resume a previous conversation
thread = codex.resume_thread("thread-abc-123")

# Continue the conversation
result = thread.run("What was my last request?")
puts result[:final_response]

schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    priority: { type: "string", enum: ["high", "medium", "low"] },
    files: {
      type: "array",
      items: { type: "string" }
    }
  },
  required: ["summary", "priority"]
}

result = thread.run(
  "Analyze the critical issues in this codebase",
  output_schema: schema
)

# Parse the structured response
data = JSON.parse(result[:final_response])
puts "Summary: #{data['summary']}"
puts "Priority: #{data['priority']}"
puts "Files: #{data['files'].join(', ')}"

codex = CodexSdk.new(
  api_key: "sk-...",                    # API key (default: ENV['CODEX_API_KEY'])
  base_url: "https://api.custom.com",   # Custom API endpoint
  codex_path_override: "/path/to/codex" # Custom binary path (for testing)
)

thread = codex.start_thread(
  model: "gpt-4",                      # Model to use
  working_directory: "/path/to/dir",   # Working directory
  sandbox_mode: "workspace-write",     # Sandbox mode
  skip_git_repo_check: false          # Skip git repository check
)

begin
  result = thread.run("Perform a complex task")
  puts result[:final_response]
rescue CodexSdk::ThreadError => e
  puts "Thread error: #{e.message}"
rescue CodexSdk::ProcessError => e
  puts "Process error: #{e.message}"
rescue CodexSdk::ValidationError => e
  puts "Validation error: #{e.message}"
end

codex = CodexSdk.new
thread = codex.start_thread(
  working_directory: '/path/to/project',
  sandbox_mode: 'read-only'
)

result = thread.run("Review the code in src/main.rb and suggest improvements")

result[:items].each do |item|
  case item['type']
  when 'agent_message'
    puts "Review: #{item['text']}"
  when 'reasoning'
    puts "Thinking: #{item['text']}"
  end
end

codex = CodexSdk.new
thread = codex.start_thread(
  working_directory: '/path/to/project',
  sandbox_mode: 'workspace-write'
)

# Run tests
result = thread.run("Run the test suite and fix any failures")

if result[:final_response].include?("All tests passed")
  puts "✓ Success!"
else
  puts "Some tests failed, running again..."
  thread.run("Try fixing the remaining test failures")
end

schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    api_endpoints: {
      type: "array",
      items: {
        type: "object",
        properties: {
          path: { type: "string" },
          method: { type: "string" },
          description: { type: "string" }
        }
      }
    }
  }
}

result = thread.run(
  "Analyze the API endpoints and generate documentation",
  output_schema: schema
)

docs = JSON.parse(result[:final_response])
puts "API Summary: #{docs['summary']}"
docs['api_endpoints'].each do |endpoint|
  puts "#{endpoint['method']} #{endpoint['path']} - #{endpoint['description']}"
end