{"id":46992935,"url":"https://github.com/andyw8/rails_agent_server","last_synced_at":"2026-03-17T20:01:35.872Z","repository":{"id":343611333,"uuid":"1178404753","full_name":"andyw8/rails_agent_server","owner":"andyw8","description":"A persistent Rails server for AI agents (no MCP needed). Avoids boot overhead for repeated queries via fast command-line access.","archived":false,"fork":false,"pushed_at":"2026-03-12T12:37:40.000Z","size":88,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-14T02:09:00.817Z","etag":null,"topics":["ai","ai-agents","automation","claude","rails"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyw8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T01:48:32.000Z","updated_at":"2026-03-12T20:37:58.000Z","dependencies_parsed_at":"2026-03-11T08:00:26.297Z","dependency_job_id":null,"html_url":"https://github.com/andyw8/rails_agent_server","commit_stats":null,"previous_names":["andyw8/rails_agent_server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/andyw8/rails_agent_server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyw8%2Frails_agent_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyw8%2Frails_agent_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyw8%2Frails_agent_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyw8%2Frails_agent_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyw8","download_url":"https://codeload.github.com/andyw8/rails_agent_server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyw8%2Frails_agent_server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30510950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-14T14:51:43.155Z","status":"ssl_error","status_checked_at":"2026-03-14T14:47:41.964Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","automation","claude","rails"],"created_at":"2026-03-11T14:16:32.990Z","updated_at":"2026-03-14T17:01:31.697Z","avatar_url":"https://github.com/andyw8.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rails Agent Server\n\nA 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.\n\n## Why This Gem?\n\nWhen 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.\n\nRails 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.\n\n### Why Not `bin/rails console`?\n\nAI agents can't easily interact with `bin/rails console` because:\n\n- **Interactive TTY requirement**: Rails console expects an interactive terminal (TTY) and won't accept input from standard pipes\n- **No request/response protocol**: There's no simple way to send a command and receive just its result back\n- **Session complexity**: Managing an interactive console session requires handling readline, prompt detection, and terminal control sequences\n- **Output parsing**: Console output includes prompts, formatting, and IRB metadata that's difficult to parse programmatically\n\nRails Agent Server provides a simple request/response interface over Unix sockets, making it trivial for AI agents to execute code and get clean results.\n\n### Why Not Spring?\n\nSpring is Rails' official application preloader and is a viable alternative for this use case. However, some projects prefer to avoid Spring for various reasons:\n\n- **Simplicity**: Spring can sometimes cause confusion with stale code or require manual intervention (`spring stop`)\n- **Compatibility**: Some projects have experienced issues with Spring in certain environments or with specific gems\n\nIf 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.\n\n### Why Not MCP (Model Context Protocol)?\n\nMCP 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:\n\n- **Simplicity**: You just need to run Rails code quickly without defining MCP tools and schemas\n- **Flexibility**: AI agents can execute arbitrary Rails code without being limited to predefined tool operations\n- **Setup**: No need to configure MCP server definitions, transport layers, or client-server communication\n- **Performance**: Direct command execution is faster than MCP's request/response protocol overhead\n- **Token efficiency**: MCP can consume many tokens for structured tool schemas and responses\n- **Existing workflows**: Works with agents that already know how to run shell commands\n\nRails 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.\n\n## Installation\n\n### Option 1: Global Installation (Recommended for AI Agents)\n\nInstall the gem globally so it works with any Rails app without modifying Gemfiles:\n\n```bash\ngem install rails_agent_server\n```\n\nThis allows AI agents to use the tool on any Rails project immediately.\n\n### Option 2: Add to Gemfile\n\nAlternatively, add it to your application's Gemfile:\n\n```ruby\ngem 'rails_agent_server', group: :development\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\n## Agent Setup\n\nAdd this section to your project's `CLAUDE.md` or equivalent:\n\n```markdown\n## Rails Console Access\n\nThis project uses `rails_agent_server` for fast Rails runner access without boot overhead.\n\nWhen you need to query the database or run Rails code:\n- Use `rails_agent_server 'YourCode.here'` instead of `bin/rails runner`\n- First request auto-starts a persistent server (takes ~5 seconds)\n- Subsequent requests are almost instant (no Rails boot time)\n- Server stays running in background until you run `rails_agent_server stop`\n- **Important**: Unlike `bin/rails runner`, this is stateful - variables and state persist between requests (like `bin/rails console`)\n\nExamples:\n  rails_agent_server 'puts User.count'\n  rails_agent_server 'puts Post.where(published: true).count'\n  rails_agent_server 'puts User.find_by(email: \"test@example.com\")\u0026.name'\n\nReloading code changes:\n- For most changes: `rails_agent_server 'Rails.application.reloader.reload!'`\n- For initializer changes: `rails_agent_server stop` (auto-starts on next request)\n\nNote: Use `bundle exec rails_agent_server` if the gem is in your Gemfile, or just `rails_agent_server` if installed globally.\n```\n\n## Usage\n\n### Basic Commands\n\nThese commands are designed to be used by AI agents (like Claude Code) or automation tools, and not intended for manual use.\n\n```bash\n# Run a Ruby expression (auto-starts server if needed)\nrails_agent_server 'puts User.count'\n\n# Run code that prints output\nrails_agent_server 'puts User.pluck(:email).join(\", \")'\n\n# Run a script file\nrails_agent_server /path/to/script.rb\n\n# Server management\nrails_agent_server status                    # Check if server is running\nrails_agent_server stop                      # Stop the background server\n```\n\n### Examples\n\n```bash\n# Database queries\nrails_agent_server 'puts User.count'\nrails_agent_server 'puts Post.where(published: true).pluck(:title)'\nrails_agent_server 'puts User.find_by(email: \"test@example.com\")\u0026.name'\n\n# Inspect schema\nrails_agent_server 'puts ActiveRecord::Base.connection.tables'\nrails_agent_server 'puts User.column_names'\n\n# Complex operations\nrails_agent_server 'Rails.cache.clear; puts \"Cache cleared\"'\n```\n\n## How It Works\n\n1. **First Request**: When you run `rails_agent_server` for the first time, it:\n   - Spawns a background server process\n   - Loads your Rails environment once\n   - Creates a Unix socket for communication\n   - Stores the PID for management\n\n2. **Subsequent Requests**: Each request:\n   - Connects to the existing Unix socket\n   - Sends code to execute\n   - Receives the result instantly\n   - No Rails boot time required\n\n3. **Server Management**: The server:\n   - Runs in the background until explicitly stopped\n   - Captures both printed output and expression results\n   - Handles errors gracefully\n   - Cleans up socket and PID files on exit\n\n## File Locations\n\nBy default, the server creates these files in your Rails application:\n\n- **Socket**: `tmp/rails_agent_server.sock` - Unix socket for communication\n- **PID file**: `tmp/pids/rails_agent_server.pid` - Process ID for management\n- **Log file**: `log/rails_agent_server.log` - Server output and errors\n\nIf not in a Rails directory, files are created in `/tmp/`.\n\n## Performance\n\n- **First request**: ~5-10 seconds (Rails boot time)\n- **Subsequent requests**: Almost instant (no boot overhead)\n- **Memory**: One Rails process running in background (~200-500MB depending on your app)\n\n## Development\n\nAfter 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.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n### Testing\n\nThe test suite includes unit tests (fast, run in CI) and integration tests (slower, require process forking). By default, `rake test` runs only unit tests. See [TESTING.md](TESTING.md) for details on running integration tests locally.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/andyw8/rails_agent_server.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyw8%2Frails_agent_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyw8%2Frails_agent_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyw8%2Frails_agent_server/lists"}