Configuration

Every option, every default, every validation rule.

Quickstart · Custom Tools · AI Tool Setup · FAQ


Configuration methods

# 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
# .rails-ai-context.yml
ai_tools:
  - claude
  - cursor
tool_mode: mcp
preset: full

Precedence

Importantconfigure block > YAML > Defaults, merged key by key. The file is read once, at boot, after config/application.rb and the environment's file and before config/initializers. Code that runs before the file and assigns a key keeps it, in a configure block or through RailsAiContext.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_paths and skip_tools, are the exception: the YAML's entries and every value the code adds are kept together, whichever runs first, so config.sensitive_patterns << "config/partner_keys.yml" in config/application.rb survives 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 a configure block's parameter or RailsAiContext.configuration is 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?, a case branch) 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 to config.rails_ai_context, which Rails sets only after the initializers run. A boot that fails part way, after config/application.rb ran, 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_concerns list replaces the framework defaults, so ActionText, ActiveStorage, Devise::Models, Turbo:: and DEBUGGER__:: concerns come back into model and controller output. Use the initializer's config.excluded_concerns += [...] to add to them instead. Each string is compiled to an unanchored pattern, so Post also hides Postable; 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
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

Warninginstrumentation_include_arguments forwards raw tool arguments to your subscribers, which for rails_query means 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:

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:

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

← Custom Tools · AI Tool Setup →

Back to Home