Rails Agent Server

A persistent Rails server for AI agents that avoids boot overhead for repeated queries. Intended for AI agents like Claude Code that need fast Rails runner access without waiting for Rails to boot on every request.

Why This Gem?

When using AI coding assistants or automation tools with Rails applications, the agent often needs to run many small queries via bin/rails runner to understand the runtime behaviour or state. Using bin/rails runner for each query means booting Rails every time, which can typically take 5-10 seconds per query.

Rails Agent Server starts a persistent background server that keeps Rails loaded in memory. The first request takes the normal Rails boot time, but subsequent requests are almost instant.

Why Not bin/rails console?

AI agents can't easily interact with bin/rails console because:

• Interactive TTY requirement: Rails console expects an interactive terminal (TTY) and won't accept input from standard pipes
• No request/response protocol: There's no simple way to send a command and receive just its result back
• Session complexity: Managing an interactive console session requires handling readline, prompt detection, and terminal control sequences
• Output parsing: Console output includes prompts, formatting, and IRB metadata that's difficult to parse programmatically

Rails Agent Server provides a simple request/response interface over Unix sockets, making it trivial for AI agents to execute code and get clean results.

Why Not Spring?

Spring is Rails' official application preloader, but it's designed for different use cases.

How They Work

Spring keeps a preloaded Rails application in memory and uses fork() to create a new process for each command. When you run bin/spring rails runner, it forks the preloaded process, runs your code in isolation, and exits. Each invocation is stateless with a clean slate. This also means Spring can safely handle concurrent requests from multiple agents or parallel processes.

Rails Agent Server boots Rails once and keeps a single persistent session running. It accepts code over a Unix socket and evaluates it in the same long-running process. Variables and state persist between requests - like rails console, not rails runner. This means it's designed for single agent use - concurrent requests would share state unpredictably.

Both solve the "Rails is slow to boot" problem. Spring forks a fresh process for each command while Rails Agent Server runs code in a single persistent session.

How Rails Agent Server Works (Pseudocode)

# Server process (runs in background)
def run
  load_rails_environment        # Boot Rails once
  create_unix_socket           # Create socket file for communication
  
  loop do
    client = accept_connection  # Wait for code to execute
    code = client.read          # Read the code string
    output = capture_output do  # Capture stdout/stderr
      eval(code, TOPLEVEL_BINDING)  # Execute in persistent session
    end
    client.write(output)        # Send output back
    client.close
  end
end

# Client (called by rails_agent_server command)
def execute(code)
  start_server unless server_running?  # Auto-start if needed
  
  socket = connect_to_server
  socket.write(code)              # Send code to evaluate
  response = socket.read          # Get output back
  socket.close
  
  puts response                   # Display to user
end

The key insight: code runs in TOPLEVEL_BINDING of a persistent process, so variables and state carry over between requests, just like in rails console.

Spring is a viable option if it works well for your team. Rails Agent Server is for teams that prefer to not use Spring.

Why Not MCP (Model Context Protocol)?

MCP servers provide a structured way for AI agents to interact with systems through defined tools and resources. While MCP is excellent for complex, multi-step workflows and standardized

... View full README on GitHub