Configuration
Every option, every default, every validation rule.
Configuration methods
Ruby initializer (recommended for in-Gemfile)
# config/initializers/rails_ai_context.rb
if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
RailsAiContext.configure do |config|
config.ai_tools = %i[claude cursor copilot opencode codex]
config.tool_mode = :mcp
config.preset = :full
end
end
YAML config (recommended for standalone)
# .rails-ai-context.yml
ai_tools:
- claude
- cursor
tool_mode: mcp
preset: full
Precedence
Important
configureblock > YAML > Defaults, merged key by key. The file is read once, at boot, afterconfig/application.rband the environment's file and beforeconfig/initializers. Code that runs before the file and assigns a key keeps it, in aconfigureblock or throughRailsAiContext.configuration(config.tool_mode = :cli); an initializer may assign a key or edit it in place. A key no code assigns keeps the YAML value. The three lists that keep something back,sensitive_patterns,excluded_pathsandskip_tools, are the exception: the YAML's entries and every value the code adds are kept together, whichever runs first, soconfig.sensitive_patterns << "config/partner_keys.yml"inconfig/application.rbsurvives the file, and assigning one of them in an initializer does not drop what the file lists (ADR 0014). Corrupted YAML degrades gracefully with a warning, and a key the gem does not know warns on stderr and is ignored while the rest of the file applies. On the static tier no initializer runs: the app's settings are read from its files in the same order. The literal values that the app's Ruby files naming the gem write to those three lists are added to the YAML's, and one the gem cannot read stops the static tier with an error naming its file and line (SECURITY.md). For every other key the last literal aconfigureblock's parameter orRailsAiContext.configurationis given wins (config.server_name = "shop",config.http_port = 7000,config.preset = :standard). A value computed at boot, or a write under a condition (if Rails.env.test?, acasebranch) or in a block that runs later (after_initialize, a proc), is not read, and the YAML or the default answers for that key. So is a write toconfig.rails_ai_context, which Rails sets only after the initializers run. A boot that fails part way, afterconfig/application.rbran, falls back to the static tier with these settings read from the files, not with what the failed boot had set.
All options
AI Tools & Mode
| Option | Type | Default | Description |
|---|---|---|---|
ai_tools |
Array of symbols | nil (all five) |
Which AI tools to generate context for. Options: :claude, :cursor, :copilot, :opencode, :codex. Unset, it reads the selection the installer recorded, and all five when there is none. A name that is none of these is kept, and writing context files refuses it by name |
tool_mode |
Symbol | :mcp |
:mcp (MCP server primary, CLI fallback) or :cli (CLI only, no MCP server). Any other value is refused. Under :cli the tools' own next-step hints name the command (rails-ai-context tool schema table=posts, or the rake task when the gem is in the Gemfile) rather than an MCP call |
context_files |
Boolean | true |
Set false for MCP-only: the server and the CLI still answer, and no context file is written or touched |
MCP only
Some apps keep their own CLAUDE.md, AGENTS.md and rules files and want the
server and nothing else:
rails generate rails_ai_context:install --mcp-only # or: rails-ai-context init --mcp-only
rails generate rails_ai_context:install --tools claude --mcp-only --defaults # asks nothing
That writes the MCP config for the tools you pick and records:
RailsAiContext.configure do |config|
config.tool_mode = :mcp
config.context_files = false
end
rails ai:context then writes nothing and exits 0, rails ai:watch writes
nothing, and rails ai:doctor raises no context-file warning. A command that
names a file still writes it: rails ai:context:claude and
rails-ai-context context --format claude.
config.ai_tools = [] means no AI tool at all: no context files and no MCP
config file are written, and rails ai:context does not ask which tools you
use. The installer has no such choice, so set it by hand. Before v5.27.0 an
empty list wrote every tool's files.
Introspection
| Option | Type | Default | Description |
|---|---|---|---|
preset |
Symbol | :full |
:full (40 introspectors) or :standard (17 introspectors) |
context_mode |
Symbol | :compact |
:compact (the root file within claude_max_lines lines and 12,000 bytes) or :full (no line cap, all introspection data within 24,000 bytes). Any other value is refused, and so is any other CONTEXT_MODE on a rake task |
introspectors |
Array of symbols | (from preset) | Override the introspector list directly |
generate_root_files |
Boolean | true |
Set false to generate split rules only: no CLAUDE.md, AGENTS.md or copilot-instructions.md, and the overview and tools rules are written in their place (.ai-context.json is still written) |
anti_hallucination_rules |
Boolean | true |
Embed 6-rule verification protocol in generated context files |
report_issue_line |
Boolean | true |
End every tool answer with one line asking the AI to offer you a GitHub issue when rails-ai-context answered wrong, missed something or failed |
claude_max_lines |
Integer | 150 |
Budget for the non-blank lines of the compact root file's gem-managed block, the <!-- BEGIN/END rails-ai-context --> markers included, beside its 12,000 bytes. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut from the bottom, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 70 lines with the anti-hallucination protocol). Must be positive |
MCP Server
| Option | Type | Default | Validation | Description |
|---|---|---|---|---|
server_name |
String | "rails-ai-context" |
- | The MCP server name the server announces. When it is left at the default, the RAILS_AI_CONTEXT_SERVER_NAME environment variable takes its place for one process, which is how a workspace's entries announce their app |
cache_ttl |
Integer | 60 |
Must be positive | Cache time-to-live in seconds |
max_tool_response_chars |
Integer | 200_000 |
Must be positive | Safety cap for tool responses and MCP resource payloads. An over-cap resource keeps its JSON shape: whole elements are dropped and reported under a _truncated key |
live_reload |
Symbol/Boolean | :auto |
- | :auto (uses listen gem if available), true, or false. The watch tells clients when files change; every server checks the app's files at each tool call either way, so its answers follow edits with or without it |
live_reload_debounce |
Float | 1.5 |
- | Seconds to wait before processing file changes |
auto_mount |
Boolean | false |
- | Auto-mount Rack middleware for HTTP transport |
allow_http_in_production |
Boolean | false |
- | Let the mounted engine and auto_mount answer in production and every other environment but development and test. Off, they refuse there with a 403 and a JSON-RPC error saying how to opt in. Every tool answers whoever reaches the endpoint, so set it only with the endpoint behind your app's authentication (see SECURITY.md). The endpoint answers the hosts the app's config.hosts allows |
http_path |
String | "/mcp" |
- | HTTP endpoint path, for auto_mount and the standalone HTTP server (the engine answers where you mount it) |
http_bind |
String | "127.0.0.1" |
- | Address the standalone HTTP server (serve --transport http, rails ai:serve_http) binds. Another address opens the port to the network with no authentication, but the server answers only requests whose Host header is 127.0.0.1, ::1 or localhost: a client that uses the machine's IP or name gets 403 "Invalid Host header", and one that sends Host: localhost gets every tool. It suits a container whose port is published to the host. The engine and auto_mount use the app's own server and ignore it |
http_port |
Integer | 6029 |
1 to 65535 | Port of the standalone HTTP server. The engine and auto_mount use the app's own server and ignore it |
Cross-Tool Hydration
| Option | Type | Default | Description |
|---|---|---|---|
hydration_enabled |
Boolean | true |
Auto-inject schema hints into controller/view tool responses |
hydration_max_hints |
Integer | 5 |
Maximum schema hints per tool response |
Filtering
| Option | Type | Default | Description |
|---|---|---|---|
excluded_models |
Array | 8 framework models | Models to skip during introspection |
excluded_controllers |
Array | 2 framework controllers | Controllers to skip |
excluded_route_prefixes |
Array | 7 framework prefixes | Route controller prefixes rails_get_routes hides with app_only: the routes Rails' engines and gems draw on their own. A route the app's route files declare (devise_for, the health check) is not one |
excluded_filters |
Array | 5 framework filters | Controller filters to skip |
excluded_middleware |
Array | 25 framework middleware | Middleware to skip in listing |
excluded_paths |
Array | ["node_modules", "tmp", "log", "vendor", ".git", "doc", "docs"] |
Paths excluded from search |
excluded_association_names |
Array | 7 framework associations | Association names to hide from model output |
excluded_concerns |
Array of Regex or String | Framework concerns | Concerns to hide everywhere they are listed. Each default names a whole namespace (ActiveRecord and ActiveRecord::...), so an app module such as ActiveRecordLikeInterface is not hidden |
A hidden concern's associations, scopes, callbacks and macros are hidden with
it: both tiers merge what a concern declared into the model, and the walk
never reads a concern the key hides. Model output says how many went, as
"1 concern hidden by excluded_concerns", without naming them.
NoteA YAML
excluded_concernslist replaces the framework defaults, soActionText,ActiveStorage,Devise::Models,Turbo::andDEBUGGER__::concerns come back into model and controller output. Use the initializer'sconfig.excluded_concerns += [...]to add to them instead. Each string is compiled to an unanchored pattern, soPostalso hidesPostable; write^Post$when you mean the one concern.
excluded_filters hides a name from a controller's filter list in both
tiers. A filter the controller explicitly skips is still shown, as a
struck-through ~~name~~ _(skipped)_ line, because a skip is a fact about
the class rather than a filter that runs. A skip carrying if: or unless:
takes the filter out on some requests only, so the filter keeps its place in
the chain and the line names the condition instead:
- `before` **require_functional!** (skipped unless: :limited_federation_mode?)
A condition written as a lambda prints the line the file holds, collapsed to
one line, the same way a filter's own if: does. A skip carrying only: or
except: takes the filter out on those actions only, so a whole-controller
answer keeps the filter and names them:
- `before` **authenticate!** (skipped on: index)
Ask about one action and the answer is absolute again: on that action the filter either runs or is struck through.
File Size Limits
| Option | Type | Default | Description |
|---|---|---|---|
max_file_size |
Integer | 5_000_000 (5 MB) |
General file read limit |
max_test_file_size |
Integer | 1_000_000 (1 MB) |
Test file read limit |
max_schema_file_size |
Integer | 10_000_000 (10 MB) |
Schema file read limit |
max_view_total_size |
Integer | 10_000_000 (10 MB) |
Doctor threshold: app/views above this warns. Not a read cap |
max_view_file_size |
Integer | 1_000_000 (1 MB) |
Accepted and stored; no check reads it. Not a read cap |
Search
| Option | Type | Default | Description |
|---|---|---|---|
max_search_results |
Integer | 200 |
Maximum lines a search may emit, matches and context together |
max_validate_files |
Integer | 50 |
Maximum files for validation |
search_extensions |
Array | nil |
Narrows the Ruby fallback to these extensions. Unset, the fallback searches every non-hidden, non-binary file, as ripgrep does, so both backends return the same lines |
concern_paths |
Array | nil (discovers app/concerns and app/*/concerns) |
Paths to scan for concerns. Setting it replaces discovery, so it can narrow as well as widen |
frontend_paths |
Array | nil (auto-detect) |
Frontend directories, e.g. ["app/frontend", "../web-client"]. One outside the app root is read for its package.json, lockfiles and bundler config, plus its tsconfig.json and the configs it extends inside that directory, and the frontend section of rails_get_config names it |
extra_app_paths |
Array | [] |
Extra directories under the app root to treat as application code |
Directories that carry their own Rails tree - plugins/*, modules/*,
gems/plugins/*, engines/*, anything up to three levels down holding an
app/ plus a gemspec, a plugin.rb or a lib/**/engine.rb - are found from
the layout and need no configuration. extra_app_paths is for a tree that
fits neither that shape nor the conventional one.
Instrumentation
| Option | Type | Default | Description |
|---|---|---|---|
instrumentation_include_arguments |
Boolean | false |
Include tool arguments in instrumentation events |
Warning
instrumentation_include_argumentsforwards raw tool arguments to your subscribers, which forrails_querymeans the SQL text and for other tools can mean environment variable names. Leave it off unless your subscriber is as trusted as your logs.
Database Query Safety
| Option | Type | Default | Validation | Description |
|---|---|---|---|---|
query_timeout |
Number | 5 |
positive | SQL query timeout in seconds. A fraction of a second is allowed |
query_row_limit |
Integer | 100 |
1 to 1000 | Maximum rows returned |
query_redacted_columns |
Array | 14 patterns | - | Column names that cause a query to be rejected, on top of a fixed built-in list (see SECURITY.md) |
query_allowed_columns |
Array | [] |
- | Column names exempted from the built-in secret column names and from query_redacted_columns. It does not release an encrypts column |
allow_query_in_production |
Boolean | false |
- | Allow rails_query tool in production |
rails_query treats a column as a secret column when one of these holds:
- its name is in
query_redacted_columnsor in the built-in list (password_reset_token,remember_token,secret,private_key,authentication_string,rolpassword,setconfig); - an
encryptsdeclaration covers it; - its name ends in
password,secret,token,key,digestorhash; - its name contains
password,secret,tokenornonce; - its name is
ivor ends in_iv; - its name is secret to the gem's log and config redaction (
passwd,salt,credentials,pepper,signing_keyand the rest of its secret words); - it is a generated column whose expression reads a secret column.
A statement that names a secret column is refused, and a secret column's values come back as [FILTERED]. A name in query_allowed_columns is not secret. An encrypts column, and a generated column that reads one, is the exception: a statement that names it is still refused, and its values stay filtered. On MySQL, MariaDB and SQLite a statement is also refused when it names a view whose definition reads a secret column, or holds a * inside a subquery while it names a table with a secret column. On PostgreSQL the view rule holds for a materialized view. SECURITY.md is the full statement of the rule, with how each check reads it and its stated limits.
Logs
| Option | Type | Default | Description |
|---|---|---|---|
log_lines |
Integer | 50 |
Default log lines to return |
Security
| Option | Type | Default | Description |
|---|---|---|---|
sensitive_patterns |
Array | 34 patterns | File patterns blocked from search/read (.env*, *.env, .envrc, *.key, *.pem, config/credentials.yml.enc, config/application.yml, config/settings.local.yml, .ssh/*, etc.) |
A placeholder such as .env.example stays readable unless a path pattern or
its exact name blocks it; see SECURITY.md.
Extensibility
| Option | Type | Default | Description |
|---|---|---|---|
custom_tools |
Array | [] |
Additional MCP::Tool classes to register (initializer only - a class reference cannot be written in YAML). A custom tool takes a built-in's name only when skip_tools lists that built-in. One that reuses the old name of a rails_get_config section (rails_get_gems) is served as its own tool, and the gem's own hints still mean the built-in section: they print rails_get_config(section:"gems") |
skip_tools |
Array | [] |
Built-in tool names to exclude (e.g., %w[rails_security_scan]). The notes below this table say what a skipped tool leaves and how the rails_get_config sections are skipped |
What skip_tools does:
- A skipped tool is left out of
tools/list,tool --list, the tool guide and the context files. - No other tool's answer points at it: the hint that would name it is left out.
- A custom tool with the same name takes its place and is listed with the app's tools. The gem's own hints, guide steps and composite answers leave it out, since those carry the built-in's arguments.
- A call that names a skipped tool anyway says it is turned off here. That holds from the CLI, rake, an MCP client and
rails_get_context(include:). - The ten tools that became
rails_get_configsections still go here by their old names:rails_get_envturns theenvsection off. rails_get_configturns off onlyapp. Withappoff,sectionis required.- The tool leaves
tools/listonce all eleven names are listed. - Listing
rails_get_configwhile a custom tool has that name gives the custom tool the built-in's place. The ten sections go with the built-in, and a call to an old name such asrails_get_gemsis then an unknown tool.
Output
| Option | Type | Default | Description |
|---|---|---|---|
output_dir |
String | Rails.root | Directory for generated context files. OpenCode reads app/models/AGENTS.md and app/controllers/AGENTS.md beside the code, so those two are written only where the directory exists under it, and named no app/models under output_dir otherwise |
Environment variables
Read from the environment of the process, so an MCP config sets them in its
server entry's env.
| Variable | Read by | Effect |
|---|---|---|
RAILS_AI_CONTEXT_BOOT_TIMEOUT |
Every command that boots the app, and the ai:serve, ai:serve_http and ai:tool rake tasks |
Seconds a boot may take before it counts as failed; a command that can then answers from the static tier. Default 20 for serve over stdio and rails ai:serve, whose client waits about 30 seconds for its first answer, and 60 for everything else. A value that is not a whole number warns and keeps the default |
RAILS_AI_CONTEXT_NO_UPDATE_CHECK |
The standalone binary | Any non-empty value turns off the daily check for a newer release on rubygems.org. The check also stays off in CI, on a prerelease and in a copy the app's bundle runs |
RAILS_AI_CONTEXT_SERVER_NAME |
The MCP server | The name it announces for one process, in place of the default server_name; a server_name the app sets wins. A workspace's MCP entries set it |
DEBUG |
Every command and the MCP server | Any value prints the backtrace of a failed boot, a failed command and an exception that escapes a tool, and names the errors a fallback swallows |
RAILS_ENV, RACK_ENV |
Every command | The Rails environment to boot, read the way Rails reads it; --environment sets it for one command. Default development |
JSON |
rails 'ai:tool[NAME]' |
JSON=1 prints the JSON envelope, as --json does |
CONTEXT_MODE |
rails ai:context, ai:context:<format> and ai:context_for |
compact or full for one run, in place of config.context_mode. Any other value stops the task |
FORMAT |
rails ai:context_for |
The format when the task is given none: FORMAT=cursor rails ai:context_for. Default claude |
STRICT |
rails ai:doctor |
STRICT=1 (or true, yes) exits 1 when a check fails, as doctor --strict does |
Presets
:full (default) - 40 introspectors
All available introspectors. Maximum context.
:standard - 17 introspectors
Lightweight subset for faster generation:
schema, models, routes, jobs, gems, conventions, controllers, tests, migrations, stimulus, view_templates, config, components, turbo, auth, performance, i18n
Generated files by AI tool
| AI Tool | Root File | Split Rules | MCP Config |
|---|---|---|---|
| Claude Code | CLAUDE.md |
.claude/rules/*.md |
.mcp.json |
| Cursor | AGENTS.md |
.cursor/rules/*.mdc |
.cursor/mcp.json |
| GitHub Copilot | .github/copilot-instructions.md |
.github/instructions/*.instructions.md |
.vscode/mcp.json (VS Code), .github/mcp.json (Copilot CLI) |
| OpenCode | AGENTS.md |
app/models/AGENTS.md, app/controllers/AGENTS.md |
opencode.json |
| Codex CLI | (shares AGENTS.md) |
(shares OpenCode rules) | .codex/config.toml |
The root content is written once, into a file every chosen tool reads: AGENTS.md when Cursor, OpenCode or Codex CLI is chosen, with CLAUDE.md holding only @AGENTS.md, and Copilot's identical copy beside it. With generate_root_files off, the Claude Code, Cursor and Copilot rules carry the overview and the tools guide instead. See Generated Files.
Examples
Minimal config
RailsAiContext.configure do |config|
config.ai_tools = %i[claude]
end
Full config
RailsAiContext.configure do |config|
# AI tools
config.ai_tools = %i[claude cursor copilot opencode codex]
config.tool_mode = :mcp
# Introspection
config.preset = :full
config.context_mode = :compact
# MCP Server
config.cache_ttl = 120
config.max_tool_response_chars = 300_000
config.live_reload = true
config.http_port = 6029
# Hydration
config.hydration_enabled = true
config.hydration_max_hints = 5
# Query safety
config.query_timeout = 10
config.query_row_limit = 200
config.allow_query_in_production = false
# Extensibility
config.custom_tools = [MyCustomTool]
config.skip_tools = %w[rails_security_scan]
# Filtering
config.excluded_models = %w[ApplicationRecord SolidQueue::Job]
end