rails_agent_server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 67c2f8f4c1a4d5f62de047f40c1bf076549b7f303b1dad62b8459919cd73ed87
+  data.tar.gz: 4ae4c453471fb620d461742684b379fc0ba4e28d62b77d662f704bc039b10a54
+SHA512:
+  metadata.gz: 414387d2240dd9736ae51d8149949e0adb72d75eac81b39dcd50da9cbf03ff29424cbc281d4477fe10ab211541e45b6d7e48b5d512d3ce20389f50508e768f45
+  data.tar.gz: 325d73826e71519c811aac9b91206d1f1f702006d578ddc40618abac28d18ca7411da1dc5db54d8bc13bba68036f0bc2ad96491bf9bb3f0c621122ddef29f33a

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andy Waite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# 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 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 and is a viable alternative for this use case. However, some projects prefer to avoid Spring for various reasons:
+
+- **Simplicity**: Spring can sometimes cause confusion with stale code or require manual intervention (`spring stop`)
+- **Compatibility**: Some projects have experienced issues with Spring in certain environments or with specific gems
+
+If Spring works well for your project, you can use `bin/spring rails runner` instead. Rails Agent Server is for teams that prefer an alternative approach or have disabled 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 interfaces, Rails Agent Server is preferable when:
+
+- **Simplicity**: You just need to run Rails code quickly without defining MCP tools and schemas
+- **Flexibility**: AI agents can execute arbitrary Rails code without being limited to predefined tool operations
+- **Setup**: No need to configure MCP server definitions, transport layers, or client-server communication
+- **Performance**: Direct command execution is faster than MCP's request/response protocol overhead
+- **Token efficiency**: MCP can consume many tokens for structured tool schemas and responses
+- **Existing workflows**: Works with agents that already know how to run shell commands
+
+Rails Agent Server is a lightweight alternative that lets AI agents treat your Rails app like a fast REPL, while MCP is better suited for building formalized integrations with specific capabilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_agent_server', group: :development
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install rails_agent_server
+```
+
+## Agent Setup
+
+Add this section to your project's `CLAUDE.md` or equivalent:
+
+```markdown
+## Rails Console Access
+
+This project uses `rails_agent_server` for fast Rails runner access without boot overhead.
+
+When you need to query the database or run Rails code:
+- Use `rails_agent_server 'YourCode.here'` instead of `bin/rails runner`
+- First request auto-starts a persistent server (takes ~5 seconds)
+- Subsequent requests are instant (no Rails boot time)
+- Server stays running in background until you run `rails_agent_server stop`
+
+Examples:
+  rails_agent_server 'User.count'
+  rails_agent_server 'Post.where(published: true).count'
+  rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+```
+
+## Usage
+
+### Basic Commands
+
+These commands are designed to be used by AI agents (like Claude Code) or automation tools, and not intended for manual use.
+
+```bash
+# Run a Ruby expression (auto-starts server if needed)
+rails_agent_server 'User.count'
+
+# Run code that prints output
+rails_agent_server 'puts User.pluck(:email).join(", ")'
+
+# Run a script file
+rails_agent_server /path/to/script.rb
+
+# Server management
+rails_agent_server status                    # Check if server is running
+rails_agent_server start                     # Manually start the server
+rails_agent_server stop                      # Stop the background server
+rails_agent_server restart                   # Restart the background server
+rails_agent_server help                      # Show help
+```
+
+### Examples
+
+```bash
+# Database queries
+rails_agent_server 'User.count'
+rails_agent_server 'Post.where(published: true).pluck(:title)'
+rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+
+# Inspect schema
+rails_agent_server 'ActiveRecord::Base.connection.tables'
+rails_agent_server 'User.column_names'
+
+# Complex operations
+rails_agent_server 'User.group(:status).count'
+rails_agent_server 'Rails.cache.clear; "Cache cleared"'
+```
+
+## How It Works
+
+1. **First Request**: When you run `rails_agent_server` for the first time, it:
+   - Spawns a background server process
+   - Loads your Rails environment once
+   - Creates a Unix socket for communication
+   - Stores the PID for management
+
+2. **Subsequent Requests**: Each request:
+   - Connects to the existing Unix socket
+   - Sends code to execute
+   - Receives the result instantly
+   - No Rails boot time required
+
+3. **Server Management**: The server:
+   - Runs in the background until explicitly stopped
+   - Captures both printed output and expression results
+   - Handles errors gracefully
+   - Cleans up socket and PID files on exit
+
+## File Locations
+
+By default, the server creates these files in your Rails application:
+
+- **Socket**: `tmp/rails_agent_server.sock` - Unix socket for communication
+- **PID file**: `tmp/pids/rails_agent_server.pid` - Process ID for management
+- **Log file**: `log/rails_agent_server.log` - Server output and errors
+
+If not in a Rails directory, files are created in `/tmp/`.
+
+## Performance
+
+- **First request**: ~5-10 seconds (Rails boot time)
+- **Subsequent requests**: ~50-200ms (no boot overhead)
+- **Memory**: One Rails process running in background (~200-500MB depending on your app)
+
+## When to Restart
+
+You should restart the server when:
+- You've changed model files or schema
+- You've updated initializers
+- You've modified environment configuration
+- The server is returning stale data
+
+```bash
+rails_agent_server restart
+```
+
+## Limitations
+
+- The server may need to be restarted to pick up some code changes
+- Only one server runs per Rails application (shared socket file)
+- Requires Unix sockets (macOS, Linux, WSL)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/andyw8/rails_agent_server.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/exe/rails_agent_server

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rails_agent_server"
+
+RailsAgentServer::CLI.new(ARGV).run

data/lib/rails_agent_server/cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "server"
+
+module RailsAgentServer
+  class CLI
+    attr_reader :server
+
+    def initialize(argv = ARGV)
+      @argv = argv
+      @server = Server.new
+    end
+
+    def run
+      case @argv[0]
+      when "stop"
+        server.stop
+      when "restart"
+        server.restart
+      when "status"
+        server.status
+      when "start"
+        server.start
+        puts "Rails agent server started"
+      when "--help", "-h", "help", nil
+        print_help
+      else
+        execute_code
+      end
+    end
+
+    private
+
+    def execute_code
+      code = if @argv[0] && File.exist?(@argv[0])
+        File.read(@argv[0])
+      else
+        @argv.join(" ")
+      end
+
+      if code.empty?
+        $stderr.puts "Error: No code provided"
+        print_help
+        exit 1
+      end
+
+      begin
+        puts server.execute(code)
+      rescue Errno::ENOENT
+        $stderr.puts "Error: Could not connect to Rails agent server"
+        exit 1
+      rescue => e
+        $stderr.puts "Error: #{e.message}"
+        exit 1
+      end
+    end
+
+    def print_help
+      puts <<~HELP
+        Rails Agent Server - A persistent Rails server for AI agents
+
+        Usage:
+          rails_agent_server 'User.count'              # Run a Ruby expression
+          rails_agent_server /path/to/script.rb        # Run a script file
+          rails_agent_server start                     # Start the server
+          rails_agent_server stop                      # Stop the server
+          rails_agent_server restart                   # Restart the server
+          rails_agent_server status                    # Check server status
+          rails_agent_server help                      # Show this help
+
+        The server auto-starts on first use if not already running.
+
+        Examples:
+          rails_agent_server 'User.count'
+          rails_agent_server 'puts User.pluck(:email).join(", ")'
+          rails_agent_server 'ActiveRecord::Base.connection.tables'
+          rails_agent_server script.rb
+
+        For Claude Code or AI agents, add this to your CLAUDE.md:
+
+          ## Rails Console Access
+
+          This project uses rails_agent_server for fast Rails console access without boot overhead.
+
+          When you need to query the database or run Rails code:
+          - Use `rails_agent_server 'YourCode.here'` instead of `bin/rails runner`
+          - First request auto-starts a persistent server (takes ~5 seconds)
+          - Subsequent requests are instant (no Rails boot time)
+          - Server stays running in background until you run `rails_agent_server stop`
+
+          Examples:
+            rails_agent_server 'User.count'
+            rails_agent_server 'Post.where(published: true).count'
+            rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+      HELP
+    end
+  end
+end

data/lib/rails_agent_server/server.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "socket"
+require "fileutils"
+require "stringio"
+
+module RailsAgentServer
+  class Server
+    attr_reader :socket_path, :pid_path, :log_path
+
+    def initialize(socket_path: nil, pid_path: nil, log_path: nil)
+      @socket_path = socket_path || default_socket_path
+      @pid_path = pid_path || default_pid_path
+      @log_path = log_path || default_log_path
+    end
+
+    def start
+      return if running?
+
+      puts "Starting Rails agent server (this will take a few seconds)..."
+
+      pid = spawn(
+        RbConfig.ruby, "-r", "rails_agent_server/server",
+        "-e", "RailsAgentServer::Server.new(socket_path: '#{socket_path}', pid_path: '#{pid_path}', log_path: '#{log_path}').run",
+        out: log_path, err: log_path
+      )
+      Process.detach(pid)
+
+      wait_for_server
+    end
+
+    def stop
+      if File.exist?(pid_path)
+        pid = File.read(pid_path).strip.to_i
+        begin
+          Process.kill("TERM", pid)
+          puts "Stopped Rails agent server (PID: #{pid})"
+        rescue Errno::ESRCH
+          puts "Rails agent server is not running (stale PID file)"
+          cleanup_files
+        end
+      else
+        puts "Rails agent server is not running"
+      end
+    end
+
+    def restart
+      stop if running?
+      cleanup_files
+      sleep 0.5
+      start
+      puts "Rails agent server restarted"
+    end
+
+    def status
+      if running?
+        pid = File.read(pid_path).strip
+        puts "Rails agent server is running (PID: #{pid})"
+        true
+      else
+        puts "Rails agent server is not running"
+        false
+      end
+    end
+
+    def running?
+      return false unless File.exist?(pid_path)
+
+      pid = File.read(pid_path).strip.to_i
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def run
+      load_rails_environment
+
+      FileUtils.rm_f(socket_path)
+      server = UNIXServer.new(socket_path)
+      File.write(pid_path, Process.pid.to_s)
+
+      $stdout.puts "Rails agent server listening on #{socket_path} (PID: #{Process.pid})"
+
+      setup_signal_handlers
+      at_exit { cleanup_files }
+
+      loop do
+        client = server.accept
+        handle_client(client)
+      end
+    rescue => e
+      $stderr.puts "Server error: #{e.class}: #{e.message}"
+      $stderr.puts e.backtrace.join("\n")
+      cleanup_files
+      raise
+    end
+
+    def execute(code)
+      start unless running?
+
+      socket = UNIXSocket.new(socket_path)
+      socket.write(code)
+      socket.close_write
+      response = socket.read
+      socket.close
+      response
+    end
+
+    private
+
+    def default_socket_path
+      if defined?(Rails) && Rails.root
+        Rails.root.join("tmp", "rails_agent_server.sock").to_s
+      else
+        "/tmp/rails_agent_server.sock"
+      end
+    end
+
+    def default_pid_path
+      if defined?(Rails) && Rails.root
+        Rails.root.join("tmp", "pids", "rails_agent_server.pid").to_s
+      else
+        "/tmp/rails_agent_server.pid"
+      end
+    end
+
+    def default_log_path
+      if defined?(Rails) && Rails.root
+        Rails.root.join("log", "rails_agent_server.log").to_s
+      else
+        "/tmp/rails_agent_server.log"
+      end
+    end
+
+    def wait_for_server(timeout: 30)
+      (timeout * 2).times do
+        return if File.exist?(socket_path)
+        sleep 0.5
+      end
+
+      abort "Timed out waiting for Rails agent server to start. Check #{log_path}"
+    end
+
+    def cleanup_files
+      FileUtils.rm_f(socket_path)
+      FileUtils.rm_f(pid_path)
+    end
+
+    def setup_signal_handlers
+      trap("INT") { exit }
+      trap("TERM") { exit }
+    end
+
+    def load_rails_environment
+      return if defined?(Rails)
+
+      rails_root = find_rails_root
+      abort "Not in a Rails application directory" unless rails_root
+
+      environment_path = File.join(rails_root, "config", "environment.rb")
+      abort "Rails environment not found at #{environment_path}" unless File.exist?(environment_path)
+
+      # Ensure tmp/pids directory exists
+      FileUtils.mkdir_p(File.dirname(pid_path))
+
+      require environment_path
+    end
+
+    def find_rails_root
+      current_dir = Dir.pwd
+      until current_dir == "/"
+        config_path = File.join(current_dir, "config", "environment.rb")
+        return current_dir if File.exist?(config_path)
+        current_dir = File.dirname(current_dir)
+      end
+      nil
+    end
+
+    def handle_client(client)
+      code = client.read
+
+      output = StringIO.new
+      result = nil
+      error = nil
+
+      begin
+        old_stdout = $stdout
+        $stdout = output
+        result = eval(code, TOPLEVEL_BINDING) # rubocop:disable Security/Eval
+        $stdout = old_stdout
+      rescue => e
+        $stdout = old_stdout
+        error = format_error(e)
+      end
+
+      response = build_response(output.string, result, error)
+      client.write(response)
+      client.close
+    rescue => e
+      client.write("Server error: #{e.class}: #{e.message}")
+      client.close
+    end
+
+    def format_error(exception)
+      message = "#{exception.class}: #{exception.message}"
+      if exception.backtrace
+        backtrace = exception.backtrace.first(5).join("\n  ")
+        message += "\n  #{backtrace}"
+      end
+      message
+    end
+
+    def build_response(printed_output, result, error)
+      response = +""
+      response << printed_output unless printed_output.empty?
+
+      if error
+        response << error
+      elsif printed_output.empty?
+        response << result.inspect
+      end
+
+      response
+    end
+  end
+end

data/lib/rails_agent_server/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAgentServer
+  VERSION = "0.1.0"
+end

data/lib/rails_agent_server.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "rails_agent_server/version"
+require_relative "rails_agent_server/server"
+require_relative "rails_agent_server/cli"
+
+module RailsAgentServer
+  class Error < StandardError; end
+end

data/sig/rails_repl_server.rbs

@@ -0,0 +1,4 @@
+module RailsReplServer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: rails_agent_server
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Waite
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Rails Agent Server provides a persistent background server for running
+  Rails code without the overhead of booting Rails for each request. Perfect for AI
+  agents and automation tools that need fast Rails console access.
+email:
+- andyw8@users.noreply.github.com
+executables:
+- rails_agent_server
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/rails_agent_server
+- lib/rails_agent_server.rb
+- lib/rails_agent_server/cli.rb
+- lib/rails_agent_server/server.rb
+- lib/rails_agent_server/version.rb
+- sig/rails_repl_server.rbs
+homepage: https://github.com/andyw8/rails_agent_server
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andyw8/rails_agent_server
+  source_code_uri: https://github.com/andyw8/rails_agent_server
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A persistent Rails server for AI agents that avoids boot overhead for repeated
+  queries
+test_files: []