Standalone Mode
Use rails-ai-context without adding it to your Gemfile.
Quickstart · CLI Reference · Configuration · Troubleshooting
Install
gem install rails-ai-context
Setup
cd your-rails-app
rails-ai-context init # asks
rails-ai-context init --tools claude --defaults # asks nothing
Interactive setup asks:
- Which AI tools? (Claude, Cursor, Copilot, OpenCode, Codex, or all; an empty answer selects all five on a first run and keeps the recorded ones on a re-run)
- What should it write? (MCP config + context files, context files only for CLI mode, or MCP config only)
On a re-run it shows the tools selected last time. A re-run that drops a tool also asks whether to remove that tool's files, one that switches to the CLI setup whether to take the gem's entries out of the MCP configs, since the CLI setup starts no MCP server, and one that switches to the MCP-only setup whether to remove the context files it generated before, which nothing would refresh. Every question comes before the app boots and anything is written; an MCP-only setup does not boot the app at all. Each question has a flag: --tools claude,cursor (or all), --mcp, --cli or --mcp-only, --prune to answer yes to every removal question, and --defaults for the rest. Unlike the install generator, init has no pre-commit hook prompt. The steps are listed in What the install generator does.
Creates:
.rails-ai-context.yml- YAML configuration- MCP config files for selected AI tools
- Context files for selected AI tools
Run it from a subdirectory and it sets up the app above. Run it in a folder that holds several apps - the folder you open your editor at - and it sets them all up at once: each app gets its own .rails-ai-context.yml and context files, and the folder's MCP configs get one server per app. See init in the CLI reference.
It does not create config/initializers/rails_ai_context.rb.
Usage
rails-ai-context serve # Start MCP server (stdio)
rails-ai-context serve --transport http --port 6029 # HTTP transport
rails-ai-context tool schema --table users # Run a tool
rails-ai-context tool --list # List all tools
rails-ai-context context # Generate context files
rails-ai-context doctor # Run diagnostics
rails-ai-context watch # Auto-regenerate on changes
rails-ai-context uninstall # Remove what the gem wrote
rails-ai-context version # Show version
watch needs the listen gem, and serve's live reload uses it when it is there. Both use the app's when its bundle locks one, and otherwise one installed beside this gem: gem install listen, no Gemfile change. Without it, serve still answers from the current files: each tool call checks them first.
How standalone mode works
- Loads only its boot shim before the app - the binary requires the two files it needs to boot Rails, then
config/environment.rb, and requires the gem itself only after the boot returns. Nothing it loads first is a gem an app pins: it reads the Gemfile andconfig/boot.rbwith Ruby's own Ripper, not the prism gem, and loads json only once the app's bundle is set up - Restores
$LOAD_PATHentries thatBundler.setupstrips (since the gem isn't in the Gemfile). The gem's own dependencies come off the load path for the duration of the boot, so every gem the app locks resolves to the app's pin, and go back behind it afterwards - YAML config - uses
.rails-ai-context.ymlinstead of a Ruby initializer - Steps aside for the app's own copy - in an app whose bundle carries its own rails-ai-context (another installed version, or a
path:copy), a command that boots the app runs through that copy, asbundle exec rails-ai-contextwould, and says so on stderr. That is the copy the app's MCP configs start, and two copies in one process would each load half the gem. The bundle is the oneBUNDLE_GEMFILEnames when you set it (a dual boot'sGemfile.next), and a command typed in a subdirectory runs from the app root it found.initasks its questions itself and has that copy write only the context files; an MCP-only setup, chosen with--mcp-onlyor at the prompt, runs nothing of the app's. So does--no-boot: bundle exec would evaluate the app's Gemfile and start whatever copy the app names, which on a repo just cloned is code nobody has read. A bundle not installed yet (bundle checkfails) is left alone too: its boot fails, and the static tier answers. A copy installed under the bundle's own path (bundle config set path vendor/bundle, or a deployment bundle) is handed the run as well. A copy from git is not seen from outside the bundle, so there the installed copy runs and the app's boot loads the bundle's copy over it: in such an app, start the server withbundle exec rails-ai-context.
This means you get the same 35 tools, same MCP server, same context generation - without touching the project's Gemfile.
Configuration via YAML
# .rails-ai-context.yml
ai_tools:
- claude
- cursor
tool_mode: mcp
preset: full
context_mode: compact
# MCP Server
cache_ttl: 60
max_tool_response_chars: 200000
http_port: 6029
# Query safety
query_timeout: 5
query_row_limit: 100
allow_query_in_production: false
# Filtering
excluded_models:
- ApplicationRecord
excluded_association_names:
- active_storage_attachments
- active_storage_blobs
excluded_paths:
- node_modules
- tmp
- log
# Skip tools
skip_tools:
- rails_security_scan
init, rails ai:context and the install generator own three keys of this file - ai_tools, tool_mode and context_files - and rewrite one only when its value changes, where it stands. Your comments and every other key stay as you wrote them.
YAML limitations
One config option is Ruby-only and can't be set via YAML:
custom_tools- a tool class is a Ruby class reference, which a YAML file cannot name
For that one, use the initializer approach (in-Gemfile mode). Naming it in the YAML file warns that it is initializer-only and ignores it.
Every other option is a YAML key, excluded_concerns included: write the patterns as strings and each is compiled at load. A YAML list replaces the framework defaults rather than adding to them, and a string is an unanchored pattern - see Configuration.
A key the gem does not know warns on stderr and is ignored; the rest of the file still applies.
Precedence
In standalone mode .rails-ai-context.yml is the only config source of a booted run. The gem is not loaded while config/initializers runs, so a config/initializers/rails_ai_context.rb contributes nothing there: the generated file, which guards on defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure), is a silent no-op, and one without that guard raises NoMethodError (the binary opens the RailsAiContext namespace before the boot, so the constant exists but configure is not defined on it) and drops the command into the static tier. On the static tier the gem reads the literal sensitive_patterns, excluded_paths and skip_tools values such a file writes, without running it (SECURITY.md).
For in-Gemfile installs both sources apply and merge key by key - see Precedence.
Ruby version manager compatibility
Standalone mode works with all Ruby version managers:
| Manager | Supported |
|---|---|
| rbenv | Yes |
| rvm | Yes |
| asdf | Yes |
| mise | Yes |
| chruby | Yes |
| System Ruby | Yes |
Codex CLI environment
Codex starts an MCP server with a cleared environment that still keeps PATH and a few more. The .codex/config.toml entry lists env_vars = ["GEM_HOME", "GEM_PATH", "GEM_ROOT", "RUBY_VERSION", "BUNDLE_PATH"], which Codex passes from the shell it was started in, so Codex finds Ruby and gems under any version manager. Nothing machine-specific is saved, so switching Ruby needs no new install.
A config an earlier release wrote saved this machine's PATH and GEM_HOME instead. rails ai:doctor warns about one, and re-running rails-ai-context init replaces it.
Updating
A gem installed with gem install stays at its version until you update it:
gem update rails-ai-context
rails-ai-context init --defaults # in each app: brings its MCP configs and context files up to the new version
Each Ruby has its own copy, so update under the Ruby your AI client starts the server with. Restart the AI client afterwards so its MCP server runs the new copy.
The binary checks rubygems.org for a newer release at most once a day, in the
background. When there is one, a command run in a terminal says so on stderr,
and the MCP server tells the agent to pass it on, in its instructions and at the
end of rails_onboard. A server reads the answer the check left the last time,
so the first check shows up from the next start. RAILS_AI_CONTEXT_NO_UPDATE_CHECK=1 turns the check off.
It stays off in CI and in a copy the app's bundle runs, where the lockfile picks
the version.
Switching between standalone and in-Gemfile
You can switch freely:
# To switch to in-Gemfile:
bundle add rails-ai-context --group development
rails generate rails_ai_context:install
# To switch to standalone:
bundle remove rails-ai-context
rails-ai-context init
# To remove it entirely:
rails-ai-context uninstall
gem uninstall rails-ai-context # once no other app uses it
The MCP config files are updated automatically. Both modes generate the same set of context files and provide the same 35 tools. The commands named inside the files follow the install mode.
Both also take --mcp-only, which writes the MCP config and no context files
at all. See CONFIGURATION.md.
Troubleshooting
"Bundler::GemNotFound" on rails-ai-context serve
The gem's $LOAD_PATH restoration may have failed. Check:
gem list rails-ai-context # Is it installed?
ruby -v # Right Ruby version?
"YAML config not loading"
The file is read from the app root, once, at boot. Check:
- You are inside the app, or passed
--app-path. A command run from a subdirectory reads the config of the app root it walks up to, and names it on stderr. - The key is one the gem knows. An unknown key warns on stderr and is ignored;
custom_toolsis initializer-only. - The file is readable and parses. A directory at that path, an unreadable file or broken YAML warns on stderr and keeps the defaults.
Commands hang
The serve command waits for stdio input by design. Use doctor or tool --list to verify the gem works, then let your AI tool connect to the server.